อ่านส่วนด้านล่างเพื่อดูวิธีสร้างรายงานการค้นหาใน 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