Search Ads 360 Reporting API เวอร์ชันใหม่พร้อมให้ใช้งานแล้ว เข้าร่วมกลุ่ม Google searchads-api-announcements เพื่อติดตามการปรับปรุงและรุ่นที่กำลังจะเปิดตัว

หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

ค้นหาบริการ

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

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

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

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

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

SearchStream

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

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

Search

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

โดยทั่วไป SearchStream จะให้ประสิทธิภาพที่ดีกว่า เนื่องจากจะช่วยลดเวลาในการขอหน้าเว็บหนึ่งๆ ของเครือข่ายแบบไปกลับ เราขอแนะนำให้ใช้ SearchStream สำหรับรายงานทั้งหมดที่มากกว่า 10,000 แถว ไม่มีความแตกต่างด้านประสิทธิภาพที่มีนัยสำคัญระหว่างเมธอดสำหรับรายงานขนาดเล็ก (<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

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

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

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

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

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 หน้า เช่น 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'

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

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

วันที่ที่กำหนดล่วงหน้า
`TODAY`	เฉพาะวันนี้
`YESTERDAY`	สำหรับเมื่อวานเท่านั้น
`LAST_7_DAYS`	7 วันก่อนหน้าไม่รวมวันนี้
`LAST_BUSINESS_WEEK`	สัปดาห์ทำการก่อนหน้า 5 วัน (จันทร์ถึงศุกร์)
`THIS_MONTH`	ทุกวันในเดือนปัจจุบัน
`LAST_MONTH`	ทุกวันในเดือนก่อนหน้า
`LAST_14_DAYS`	14 วันก่อนหน้านี้ ไม่รวมวันนี้
`LAST_30_DAYS`	30 วันก่อนหน้า ไม่รวมวันนี้
`THIS_WEEK_SUN_TODAY`	ระยะเวลาระหว่างวันอาทิตย์ที่ผ่านมากับวันปัจจุบัน
`THIS_WEEK_MON_TODAY`	ระยะเวลาระหว่างวันจันทร์ก่อนหน้าและวันปัจจุบัน
`LAST_WEEK_SUN_SAT`	ระยะเวลา 7 วันเริ่มตั้งแต่วันอาทิตย์ที่ผ่านมา
`LAST_WEEK_MON_SUN`	ระยะเวลา 7 วัน เริ่มจากวันจันทร์ก่อนหน้า

ตัวอย่าง

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