อ่านส่วนด้านล่างเพื่อดูวิธีสร้างรายงานการค้นหาใน Search Ads API การรายงาน 360
ค้นหาบริการ
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
ของ Google
คำขอประกอบด้วย 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
มีช่อง Selectable with ที่ขยายได้สำหรับช่อง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
ส่งคืนมาดูเหมือนจะเป็นอย่างอื่น
ดังนี้
{
"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
และ
value ของช่อง 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 ในคำค้นหา
ประเภท enum ที่ไม่รู้จัก
หากทรัพยากรส่งกลับมาพร้อมกับประเภทข้อมูล enum UNKNOWN
ก็หมายความว่า
ระบบไม่รองรับประเภทนี้อย่างสมบูรณ์ในเวอร์ชัน API แหล่งข้อมูลเหล่านี้อาจมี
สร้างขึ้นผ่านอินเทอร์เฟซอื่นๆ ตัวอย่างเช่น แคมเปญหรือโฆษณาใหม่
เปิดตัวใน UI ของ Search Ads 360 แต่ยังไม่รองรับในเวอร์ชัน API
ที่คุณกำลังสอบถาม
คุณยังเลือกเมตริกเมื่อทรัพยากรเป็นประเภท UNKNOWN
ได้ แต่
ให้คำนึงถึงสิ่งต่อไปนี้
- ระบบอาจรองรับทรัพยากรที่มีประเภท
UNKNOWN
ในภายหลัง แต่ทรัพยากรดังกล่าวจะยังคงอยู่UNKNOWN
โดยไม่มีกำหนด - วัตถุใหม่ที่เป็นประเภท
UNKNOWN
อาจปรากฏได้ตลอดเวลา วัตถุเหล่านี้ สามารถเข้ากันได้แบบย้อนหลังเพราะมีค่า enum อยู่แล้ว เราขอแนะนำ พร้อมการเปลี่ยนแปลงนี้ตามที่มีอยู่เพื่อให้คุณมี ของบัญชี ทรัพยากรUNKNOWN
อาจปรากฏขึ้นเนื่องจากรายการใหม่ กิจกรรมในบัญชีของคุณผ่านอินเทอร์เฟซอื่นๆ หรือเนื่องจากแหล่งข้อมูล ไม่ได้รับการสนับสนุนอย่างเป็นทางการอีกต่อไป - แหล่งข้อมูล
UNKNOWN
รายการอาจมีเมตริกโดยละเอียดแนบอยู่ ซึ่งคุณสามารถระบุได้ คำถาม - โดยทั่วไปทรัพยากร
UNKNOWN
รายการจะปรากฏโดยสมบูรณ์ใน UI ของ Search Ads 360