กําลังเรียกออบเจ็กต์

GoogleAdsService คือบริการดึงข้อมูลและรายงานออบเจ็กต์แบบรวมของ Google Ads API บริการนี้มีวิธีการที่ทำสิ่งต่อไปนี้

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

GoogleAdsService สามารถแสดงผลลัพธ์ได้ 2 วิธี ดังนี้

• GoogleAdsService.SearchStream จะแสดงผลแถวทั้งหมดในการตอบกลับแบบสตรีมมิงรายการเดียว ซึ่งมีประสิทธิภาพมากกว่าสำหรับชุดผลลัพธ์ขนาดใหญ่ (มากกว่า 10,000 แถว) เราขอแนะนำให้ใช้วิธีนี้หากแอปพลิเคชันของคุณดาวน์โหลดชุดผลลัพธ์แบบเต็มหรือประมวลผลแถวเป็นสตรีม
• GoogleAdsService.Search จะแบ่งคำตอบขนาดใหญ่ออกเป็นหน้าผลลัพธ์ที่จัดการได้ วิธีนี้มีประโยชน์หากแอปพลิเคชันแบบอินเทอร์แอกทีฟแสดงผลการค้นหาทีละหน้า

ดูข้อมูลเพิ่มเติมเกี่ยวกับการแบ่งหน้าเทียบกับการสตรีม

ส่งคำขอ

GoogleAdsService.SearchStream ต้องการ SearchGoogleAdsStreamRequest และ GoogleAdsService.Search ต้องการ SearchGoogleAdsRequest คำขอทั้ง 2 ประเภทประกอบด้วยข้อมูลต่อไปนี้

• customer_id
• query ของ Google Ads Query Language ที่ระบุแหล่งข้อมูลที่จะค้นหา แอตทริบิวต์ กลุ่ม และเมตริกที่จะดึงข้อมูล รวมถึงเงื่อนไขที่จะใช้เพื่อจำกัดออบเจ็กต์ที่แสดงผล

คำขอยังรองรับช่องเฉพาะเมธอดด้วย ทั้งนี้ขึ้นอยู่กับเมธอด

• SearchGoogleAdsStreamRequest (SearchStream เท่านั้น):
  • summary_row_setting ที่ไม่บังคับเพื่อขอแถวสรุปที่มีเมตริกที่รวบรวมไว้
• SearchGoogleAdsRequest (Search เท่านั้น):
  • page_token ที่ไม่บังคับเพื่อดึงข้อมูลผลลัพธ์ชุดถัดไปเมื่อใช้การแบ่งหน้า (page_size คงที่ที่ 10,000 แถว การตั้งค่า page_size ในคำขอจะแสดงข้อผิดพลาด RequestError.PAGE_SIZE_NOT_SUPPORTED)
  • ข้อความ search_settings ที่ไม่บังคับเพื่อกำหนดค่า return_summary_row, return_total_results_count และ omit_results
  • บูลีน validate_only ที่ไม่บังคับเพื่อตรวจสอบการค้นหาโดยไม่ต้องเรียกใช้

ดูข้อมูลเพิ่มเติมเกี่ยวกับ Google Ads Query Language ได้ที่คู่มือ Google Ads Query Language

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

GoogleAdsService จะแสดงรายการออบเจ็กต์ GoogleAdsRow (ภายในกลุ่ม SearchGoogleAdsStreamResponse ที่สตรีมหรือใน SearchGoogleAdsResponse ที่แบ่งหน้า)

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

ตัวอย่างเช่น แม้ว่า ad_group_criterion จะมีแอตทริบิวต์ status แต่ระบบจะไม่ป้อนข้อมูลในช่อง status ของแอตทริบิวต์ ad_group_criterion ของแถวในการตอบกลับคำค้นหาที่ส่วนคำสั่ง SELECT ไม่มี ad_group_criterion.status ในทำนองเดียวกัน ระบบจะไม่ป้อนข้อมูลแอตทริบิวต์ campaign ของแถวหากส่วนคำสั่ง SELECT ไม่มีช่องใดๆ จากทรัพยากร campaign

GoogleAdsRow แต่ละรายการอาจมีแอตทริบิวต์และเมตริกที่แตกต่างจากแถวอื่นในชุดผลลัพธ์เดียวกัน ดังนั้นจึงควรมองแถวเป็นออบเจ็กต์แทนที่จะเป็นแถวคงที่ของตาราง

ประเภท enum UNKNOWN และ UNSPECIFIED

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

ข้อควรพิจารณาที่ต้องคำนึงถึงมีดังนี้

• ทรัพยากรที่มีประเภท UNKNOWN อาจได้รับการรองรับใน API เวอร์ชันที่ใหม่กว่าหรือยังคงเป็น UNKNOWN อย่างไม่มีกำหนด
• ออบเจ็กต์ใหม่ที่มีประเภท UNKNOWN อาจปรากฏขึ้นได้ทุกเมื่อ ออบเจ็กต์เหล่านี้เข้ากันได้แบบย้อนหลังเนื่องจากค่า enum UNKNOWN มีอยู่ในทุก enum ใน API ระบบจะแสดงผลทรัพยากรพร้อมกับ UNKNOWN เพื่อให้คุณมีมุมมองที่ถูกต้องเกี่ยวกับเมตริกประสิทธิภาพโดยรวมของบัญชี
• ทรัพยากร UNKNOWN อาจมีเมตริกโดยละเอียดที่แนบมาด้วยซึ่งสามารถค้นหาได้
• โดยปกติแล้ว แหล่งข้อมูล UNKNOWN จะแสดงอย่างครบถ้วนใน UI ของ Google Ads
• โดยทั่วไปแล้ว ทรัพยากร UNKNOWN จะเปลี่ยนแปลงผ่าน API ไม่ได้

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

การตอบกลับจะมี GoogleAdsRow 1 รายการสําหรับชุดค่าผสมแต่ละชุดของรายการต่อไปนี้

• อินสแตนซ์ของทรัพยากรหลักที่ระบุไว้ในส่วนคำสั่ง FROM
• ค่าของช่อง segments ที่เลือกแต่ละช่อง

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

• campaign
• segments.ad_network_type
• segments.date

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

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

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