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

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

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

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

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

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

ส่งคำขอ

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

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

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

• 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 ได้ที่คำแนะนำเกี่ยวกับภาษาการค้นหาของ Google Ads

ประมวลผลคำตอบ

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

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

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

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

ประเภทการแจงนับ 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 จะมี แถวหนึ่งแถวสำหรับชุดค่าผสมแต่ละชุดต่อไปนี้

• 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