สร้างรายงานการค้นหาใน Search Ads 360 Reporting API

อ่านส่วนด้านล่างเพื่อดูวิธีสร้างรายงานการค้นหาใน Search Ads 360 Reporting API

บริการ Search

Search Ads 360 Reporting API มีบริการพิเศษสำหรับการค้นหาและการรายงาน

SearchAds360Service เป็นบริการดึงข้อมูลออบเจ็กต์และการรายงานแบบรวมที่ให้บริการค้นหา 2 วิธี ได้แก่ SearchStream และ Search โดยการค้นหาจะส่งผ่านสตริงการค้นหา ที่เขียนด้วย Search Ads 360 Query Language คุณสามารถกำหนดการค้นหาเพื่อทำสิ่งต่อไปนี้ได้

• ดึงข้อมูลแอตทริบิวต์ที่เฉพาะเจาะจงของออบเจ็กต์
• ดึงข้อมูลเมตริกประสิทธิภาพของออบเจ็กต์ตามช่วงวันที่
• จัดเรียงออบเจ็กต์ตามแอตทริบิวต์
• กรองผลลัพธ์โดยใช้เงื่อนไขที่ระบุออบเจ็กต์ที่จะแสดง
• จำกัดจำนวนออบเจ็กต์ที่แสดง

วิธีการค้นหาทั้ง 2 วิธีจะแสดงผลแถวทั้งหมดที่ตรงกับการค้นหา ตัวอย่างเช่น เมื่อดึงข้อมูล campaign.id, campaign.name และ metrics.clicks API จะแสดงผล SearchAds360Row ที่มีออบเจ็กต์แคมเปญซึ่งตั้งค่าช่อง id และ name แล้ว รวมถึงออบเจ็กต์ metrics ซึ่งตั้งค่าช่อง clicks แล้ว

วิธีการค้นหา

SearchStream

ส่งคำขอเดียวและเริ่มการเชื่อมต่อแบบถาวรกับ Search Ads 360 Reporting API ไม่ว่ารายงานจะมีขนาดเท่าใดก็ตาม

• แพ็กเก็ตข้อมูลจะเริ่มดาวน์โหลดทันทีโดยแคชผลลัพธ์ทั้งหมดไว้ในบัฟเฟอร์ข้อมูล
• โค้ดของคุณจะเริ่มอ่านข้อมูลที่บัฟเฟอร์ไว้ได้โดยไม่ต้องรอให้สตรีมทั้งหมดเสร็จสมบูรณ์

Search

ส่งคำขอแบบแบ่งหน้าหลายรายการเพื่อดาวน์โหลดรายงานทั้งหมด

SearchStream มักจะให้ประสิทธิภาพที่ดีกว่าเนื่องจากช่วยลดเวลาในการรับส่งข้อมูลไปกลับของเครือข่ายที่ต้องใช้ในการขอแต่ละหน้า เราขอแนะนำให้ใช้ SearchStream สำหรับรายงานทั้งหมดที่มีมากกว่า 10,000 แถว วิธีการทั้ง 2 วิธีไม่มีความแตกต่างด้านประสิทธิภาพอย่างมีนัยสำคัญสำหรับรายงานขนาดเล็ก (<10,000 แถว)

วิธีการที่คุณใช้จะไม่มีผลต่อโควต้าและขีดจำกัดของ API โดยระบบจะนับการค้นหาหรือรายงานเดียวเป็นการดำเนินการ 1 รายการ ไม่ว่าผลลัพธ์จะแบ่งหน้าหรือสตรีมก็ตาม

ตัวอย่างคำค้นหา

คำค้นหาตัวอย่างนี้จะแสดงผลข้อมูลประสิทธิภาพของบัญชีในช่วง 30 วันที่ผ่านมาตามแคมเปญ โดยแบ่งกลุ่มตามอุปกรณ์

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

ส่งคำขอ

หากต้องการส่งคำขอ คุณต้องส่ง customer_id และสตริง query ไปยังอินเทอร์เฟซ SearchAds360Service.SearchStream หรือ SearchAds360Service.Search

คำขอประกอบด้วย POST ของ HTTP ไปยังเซิร์ฟเวอร์ Search Ads 360 Reporting API ที่ URL ใด URL หนึ่งต่อไปนี้

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

นี่คือตัวอย่างที่สมบูรณ์ของการกำหนดรายงานสำหรับ searchStream ที่อยู่ในคำขอ POST ของ HTTP

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

ประมวลผลการตอบกลับ

SearchAds360Service จะแสดงผลรายการ SearchAds360Row ออบเจ็กต์

SearchAds360Row แต่ละรายการแสดงออบเจ็กต์ที่แสดงผลโดยการค้นหา ออบเจ็กต์แต่ละรายการประกอบด้วยชุดแอตทริบิวต์ที่ป้อนข้อมูลตามช่องที่ขอในอนุประโยค SELECT ของการค้นหา ระบบจะไม่ป้อนข้อมูลแอตทริบิวต์ที่ไม่ได้รวมอยู่ในอนุประโยค SELECT ในออบเจ็กต์ในการตอบกลับ

ตัวอย่างเช่น การค้นหาด้านล่างจะป้อนข้อมูลออบเจ็กต์ SearchAds360Row แต่ละรายการด้วย campaign.id, campaign.name และ campaign.status เท่านั้น ระบบจะละเว้นแอตทริบิวต์อื่นๆ เช่น campaign.engine_id หรือ campaign.bidding_strategy_type

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

เอกสารประกอบอ้างอิง

ส่วนอ้างอิงมีข้อมูลทั้งหมดที่คุณ ต้องใช้เพื่อใช้สิ่งประดิษฐ์แต่ละรายการอย่างถูกต้อง โดยจะมี 1 หน้าสำหรับทรัพยากรแต่ละรายการ for example ad_group และ campaign หน้า segments และ metrics จะแสดงรายการช่องกลุ่มและเมตริกทั้งหมดที่พร้อมใช้งาน

ทรัพยากร กลุ่ม และเมตริกบางรายการไม่เข้ากันและใช้ร่วมกันไม่ได้ ในขณะที่รายการอื่นๆ เข้ากันได้ดีและเสริมซึ่งกันและกัน หน้าทรัพยากรแต่ละหน้าจะมีข้อมูลต่อไปนี้ (หากมีและเหมาะสม) และอื่นๆ

ทรัพยากรที่มีการระบุแหล่งที่มา

สำหรับทรัพยากรบางรายการ คุณอาจมีตัวเลือกในการรวมทรัพยากรที่เกี่ยวข้องโดยนัยด้วยการเลือกช่องของทรัพยากรเหล่านั้นพร้อมกับช่องของทรัพยากรในอนุประโยค FROM ตัวอย่างเช่น ทรัพยากร campaign เป็นทรัพยากรที่มีการระบุแหล่งที่มาของทรัพยากร ad_group ซึ่งหมายความว่าคุณสามารถรวมช่องต่างๆ เช่น campaign.id และ campaign.bidding_strategy_type ไว้ในการค้นหาเมื่อใช้ ad_group ในอนุประโยค FROM

ส่วนทรัพยากรที่มีการระบุแหล่งที่มา จะแสดงรายการทรัพยากรที่มีการระบุแหล่งที่มาที่พร้อมใช้งาน ไม่ใช่ทุกทรัพยากรจะมีทรัพยากรที่มีการระบุแหล่งที่มา

คอลัมน์ช่องทรัพยากร

ช่องทั้งหมดของทรัพยากรจะรวมอยู่ในคอลัมน์ช่องทรัพยากร ช่องทรัพยากรแต่ละช่องจะลิงก์ไปยังรายละเอียดเพิ่มเติมเกี่ยวกับช่อง ซึ่งรวมถึงคำอธิบาย หมวดหมู่ ประเภทข้อมูล URL ของประเภท และการตั้งค่าที่กรองได้ เลือกได้ จัดเรียงได้ และทำซ้ำได้

คอลัมน์กลุ่ม

ไม่ใช่ทุกช่องกลุ่มที่จะเลือกได้ด้วยทรัพยากรที่กำหนด

คอลัมน์กลุ่ม จะแสดงรายการช่อง segments ที่คุณใช้ในอนุประโยค SELECT เดียวกันกับช่องของทรัพยากรได้ ช่องแต่ละช่องจะลิงก์ไปยังรายละเอียดทั้งหมดเกี่ยวกับช่อง ซึ่งรวมถึงคำอธิบาย หมวดหมู่ ประเภทข้อมูล URL ของประเภท และการตั้งค่าที่กรองได้ เลือกได้ จัดเรียงได้ และทำซ้ำได้ หากคุณใช้ทรัพยากรในอนุประโยค FROM คุณสามารถใช้เมนูแบบเลื่อนลงใช่/ไม่ใช่ เพื่อกรองกลุ่มที่ไม่พร้อมใช้งานออก

คอลัมน์เมตริก

ไม่ใช่ทุกช่องเมตริกที่จะเลือกได้ด้วยทรัพยากรที่กำหนด

คอลัมน์เมตริก จะแสดงรายการช่อง metrics ที่คุณใช้ในอนุประโยค SELECT เดียวกันกับช่องของทรัพยากรได้ ช่องแต่ละช่องจะลิงก์ไปยังรายละเอียดทั้งหมดเกี่ยวกับช่อง ซึ่งรวมถึงคำอธิบาย หมวดหมู่ ประเภทข้อมูล URL ของประเภท และการตั้งค่าที่กรองได้ เลือกได้ จัดเรียงได้ และทำซ้ำได้ หากคุณใช้ทรัพยากรในอนุประโยค FROM ให้ใช้เมนูแบบเลื่อนลงใช่/ไม่ใช่ เพื่อกรองเมตริกที่ไม่พร้อมใช้งานออก

การแบ่งกลุ่มทรัพยากร

ทรัพยากรบางรายการมีช่องทรัพยากรการแบ่งกลุ่มที่คุณเลือกได้เมื่อทรัพยากรอยู่ในอนุประโยค FROM ตัวอย่างเช่น หากคุณเลือกช่องทรัพยากร campaign เช่น campaign.name เมื่อใช้ campaign_budget ในอนุประโยค FROM ระบบจะแสดงผล campaign.resource_name โดย อัตโนมัติและแบ่งกลุ่มตาม เนื่องจาก campaign เป็นทรัพยากรการแบ่งกลุ่มของ campaign_budget

ส่วนทรัพยากรการแบ่งกลุ่ม จะแสดงรายการทรัพยากรการแบ่งกลุ่มที่พร้อมใช้งาน ไม่ใช่ทุกทรัพยากรจะมีทรัพยากรการแบ่งกลุ่ม

เลือกได้ด้วย

ช่อง segments บางช่องไม่เข้ากันกับทรัพยากร กลุ่ม และเมตริกอื่นๆ

หน้า segments มีส่วนเลือกได้ด้วย ที่ขยายได้สำหรับช่อง segments แต่ละช่อง ซึ่งแสดงรายการช่องทรัพยากร ช่อง metrics และช่อง segments อื่นๆ ทั้งหมดที่เข้ากันได้ ซึ่งคุณสามารถรวมไว้ ในอนุประโยค SELECT ได้

การแบ่งกลุ่ม

คุณสามารถแบ่งกลุ่มผลการค้นหาได้โดยเพิ่มช่อง segments.FIELD_NAME ลงในอนุประโยค SELECTของการค้นหา

ตัวอย่างเช่น segments.device ในการค้นหาด้านล่างจะแสดงผลรายงานที่มีแถวสำหรับ impressions ของอุปกรณ์แต่ละเครื่องสำหรับทรัพยากรที่ระบุในอนุประโยค FROM

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

ผลลัพธ์ที่แสดงผลโดย SearchAds360Service.SearchStream จะมีลักษณะคล้ายสตริง JSON ต่อไปนี้

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

ดู segments เพื่อดูรายการช่องกลุ่มที่พร้อมใช้งานที่คุณ ใช้ได้

หลายกลุ่ม

คุณสามารถระบุกลุ่มหลายกลุ่มในอนุประโยค SELECT ของการค้นหา การตอบกลับจะมีออบเจ็กต์ SearchAds360Row 1 รายการสำหรับการผสมผสาน ของอินสแตนซ์ ของทรัพยากรหลักที่ระบุในอนุประโยค FROM และค่า ของช่อง segment ที่เลือกแต่ละช่อง

ตัวอย่างเช่น การค้นหาต่อไปนี้จะแสดงผล 1 แถวสำหรับการผสมผสานของ campaign, segments.ad_network_type และ segments.date แต่ละรายการ

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

โปรดทราบว่าระบบจะแบ่งกลุ่มผลลัพธ์โดยนัยตามอินสแตนซ์ ของทรัพยากรหลักแต่ละรายการ แต่ไม่ใช่ตามค่าของช่องที่เลือกแต่ละช่อง

การค้นหาตัวอย่างต่อไปนี้จะแสดงผล 1 แถวต่อแคมเปญ ไม่ใช่ 1 แถวต่อค่าที่ไม่ซ้ำกันของช่อง campaign.status

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

การแบ่งกลุ่มโดยนัย

ระบบจะแบ่งกลุ่มรายงานทั้งหมดในขั้นต้นตามทรัพยากรที่ระบุในอนุประโยค FROM และแบ่งกลุ่มเมตริกตามช่อง resource_name ของทรัพยากรนี้

การค้นหาตัวอย่างนี้จะแสดงผล ad_group.resource_name โดยอัตโนมัติและใช้ โดยนัยเพื่อแบ่งกลุ่มเมตริกที่ระดับ ad_group

SELECT metrics.impressions
FROM ad_group

สตริง JSON ที่แสดงผลจะมีลักษณะคล้ายกับสตริงต่อไปนี้

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

กลุ่มวันที่หลัก

คุณสามารถใช้กลุ่มวันที่หลักใน WHEREอนุประโยคเพื่อระบุวันที่หรือ ช่วงเวลา

ช่องกลุ่มต่อไปนี้เรียกว่า กลุ่มวันที่หลัก: segments.date, segments.week, segments.month, segments.quarter, และ segments.year

การค้นหาตัวอย่างนี้จะแสดงผลเมตริก clicks ของแคมเปญในช่วง 30 วันที่ผ่านมา

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

ช่องกลุ่มวันที่หลักเป็นข้อยกเว้น ของกฎทั่วไปที่ว่าคุณไม่สามารถใช้ช่องกลุ่มในอนุประโยค WHERE ได้ เว้นแต่คุณจะรวมช่องดังกล่าวไว้ในอนุประโยค SELECT ด้วย ดูข้อมูลเพิ่มเติมได้ที่ การกรองที่ไม่อนุญาต

กฎของกลุ่มวันที่หลัก

• คุณสามารถใช้ช่องวันที่หลักในอนุประโยค WHERE ได้โดยไม่ต้องรวมไว้ในอนุประโยค SELECT นอกจากนี้ คุณยังรวมช่องไว้ในทั้ง 2 อนุประโยคได้หากต้องการ

  การค้นหาตัวอย่างนี้จะแสดงผลเมตริก clicks ตามชื่อแคมเปญในช่วงวันที่ โปรดทราบว่า segments.date ไม่ได้รวมอยู่ในอนุประโยค SELECT

  SELECT
      campaign.name,
      metrics.clicks
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

• หากคุณรวมช่องวันที่หลักไว้ในอนุประโยค SELECT คุณต้องระบุวันที่หรือช่วงวันที่ที่แน่นอนในอนุประโยค WHERE ช่องที่ระบุใน อนุประโยค SELECT และ WHERE ไม่จำเป็นต้องตรงกัน

  การค้นหาตัวอย่างนี้จะแสดงผลเมตริก clicks ตามชื่อแคมเปญที่แบ่งกลุ่มตามเดือนสำหรับทุกวันในช่วงวันที่

  SELECT
    campaign.name,
    metrics.clicks,
    segments.month
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

วันที่ ISO 8601

คุณสามารถใช้รูปแบบ YYYY-MM-DD (ISO 8601) เพื่อระบุวันที่และช่วงวันที่ได้ เช่น

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

สำหรับช่องกลุ่มวันที่หลักที่ต้องใช้ช่วงเวลา (segments.week, segments.month, segments.quarter) คุณสามารถใช้โอเปอเรเตอร์ = กับ วันแรกของช่วงเวลาได้ เช่น

WHERE segments.month = '2022-06-01'

วันที่ที่กำหนดไว้ล่วงหน้า

นอกจากนี้ คุณยังใช้วันที่และช่วงวันที่ที่กำหนดไว้ล่วงหน้าต่อไปนี้ได้ด้วย

ตัวอย่าง

WHERE segments.date DURING LAST_30_DAYS

เมตริกเป็น 0

เมื่อเรียกใช้การค้นหา คุณอาจพบเมตริกที่มีค่าเป็น 0 สำหรับเอนทิตีบางรายการ ดูข้อมูลเกี่ยวกับวิธีจัดการเมตริกที่เป็น 0 ในการค้นหา

ประเภท Enum ที่ไม่รู้จัก

หากระบบแสดงผลทรัพยากรที่มีประเภทข้อมูล Enum เป็น UNKNOWN แสดงว่า API เวอร์ชันนั้นไม่รองรับประเภทดังกล่าวอย่างเต็มที่ ทรัพยากรเหล่านี้อาจสร้างขึ้นผ่านอินเทอร์เฟซอื่นๆ ตัวอย่างเช่น มีการเปิดตัวแคมเปญหรือโฆษณาใหม่ใน UI ของ Search Ads 360 แต่ API เวอร์ชันที่คุณกำลังค้นหายังไม่รองรับ

คุณยังคงเลือกเมตริกได้เมื่อทรัพยากรมีประเภทเป็น UNKNOWN แต่ต้องคำนึงถึงสิ่งต่อไปนี้

• ทรัพยากรที่มีประเภท UNKNOWN อาจได้รับการรองรับในภายหลัง แต่ก็อาจยังคงเป็น UNKNOWN ไปเรื่อยๆ

• ออบเจ็กต์ใหม่ที่มีประเภท UNKNOWN อาจปรากฏขึ้นได้ทุกเมื่อ ออบเจ็กต์เหล่านี้เข้ากันได้กับเวอร์ชันก่อนหน้าเนื่องจากค่า Enum พร้อมใช้งานแล้ว เราจะเปิดตัวทรัพยากรที่มีการเปลี่ยนแปลงนี้เมื่อพร้อมใช้งานเพื่อให้คุณเห็นภาพที่ถูกต้องของบัญชี ทรัพยากร UNKNOWN อาจปรากฏขึ้นเนื่องจากมีกิจกรรมใหม่ในบัญชีผ่านอินเทอร์เฟซอื่นๆ หรือเนื่องจากระบบไม่รองรับทรัพยากรอย่างเป็นทางการอีกต่อไป

• ทรัพยากร UNKNOWN อาจมีเมตริกโดยละเอียดแนบอยู่ ซึ่งคุณสามารถค้นหาได้

• โดยปกติแล้วทรัพยากร UNKNOWN จะมองเห็นได้ทั้งหมดใน UI ของ Search Ads 360