โดยทั่วไป การเรียก Search Ads 360 Reporting API จะทำผ่านไลบรารีของไคลเอ็นต์ โปรดดูข้อมูลเพิ่มเติมที่คำอธิบายไลบรารีของไคลเอ็นต์ อย่างไรก็ตาม ความรู้เกี่ยวกับโครงสร้างของรายละเอียดคำขอที่สำคัญอาจมีประโยชน์เมื่อทดสอบและแก้ไขข้อบกพร่อง
Search Ads 360 Reporting API คือ gRPC API ที่มีการเชื่อมโยง REST ซึ่งหมายความว่าคุณจะเรียกใช้ API ได้ 2 วิธีดังนี้
- วิธีที่ต้องการ
- ใช้ไลบรารีของไคลเอ็นต์
- สร้างเนื้อหาของคำขอเป็นบัฟเฟอร์โปรโตคอล
- ส่งคำขอไปยังเซิร์ฟเวอร์โดยใช้ HTTP/2
- ดีซีเรียลไลซ์การตอบสนองไปยังบัฟเฟอร์โปรโตคอล
- ตีความผลลัพธ์
- วิธีการทางเลือกที่ไม่บังคับ
- ใช้ REST
- สร้างเนื้อหาของคำขอเป็นออบเจ็กต์ JSON
- ส่งคำขอไปยังเซิร์ฟเวอร์โดยใช้ HTTP 1.1
- ดีซีเรียลไลซ์การตอบกลับเป็นออบเจ็กต์ JSON
- ตีความผลลัพธ์
โปรดดูที่ Google Cloud APIs สำหรับข้อมูลเพิ่มเติม
ส่วนต่อไปนี้ใช้กับทั้งโปรโตคอล gRPC และ REST
ชื่อทรัพยากร
ออบเจ็กต์ส่วนใหญ่ใน API จะระบุด้วยสตริงชื่อทรัพยากร สตริงเหล่านี้ยังทำหน้าที่เป็น URL เมื่อใช้อินเทอร์เฟซ REST ด้วย
ดูข้อมูลอ้างอิง > REST สำหรับข้อมูลเพิ่มเติม เกี่ยวกับทรัพยากรที่รองรับและการนำเสนอเส้นทางของทรัพยากรเหล่านั้น มีการใช้รูปแบบเดียวกันกับบริการอื่นๆ
รหัสผสม
หากรหัสของออบเจ็กต์ไม่ไม่ซ้ำกันทั่วโลก ระบบจะสร้างรหัสคอมโพสิตสำหรับออบเจ็กต์นั้นโดยใส่รหัสระดับบนสุดและเครื่องหมายทิลเดอ (~) ไว้ล่วงหน้า
เช่น เนื่องจากรหัสโฆษณาของกลุ่มโฆษณาซ้ำกันทั่วโลก รหัสออบเจ็กต์หลัก (กลุ่มโฆษณา) จะเพิ่มนำหน้าไป ซึ่งส่งผลให้ได้รหัสผสมที่ไม่ซ้ำกัน
ตัวอย่างเช่น AdGroupId จาก 123 + ~ + AdGroupAdId จาก 45678
= รหัสโฆษณาของกลุ่มโฆษณาแบบผสม 123~45678
ส่วนหัวของคำขอ
คุณควรใส่ส่วนหัว HTTP (หรือข้อมูลเมตา gRPC) ในส่วนต่อไปนี้ไว้ในเนื้อหาของคำขอ
การให้สิทธิ์
คุณต้องระบุโทเค็นเพื่อการเข้าถึง OAuth2 ในแบบฟอร์มดังนี้
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]
โทเค็นนี้ควรระบุว่าบัญชีดูแลจัดการทำหน้าที่ในนามของลูกค้าหรือผู้ลงโฆษณาที่จัดการบัญชีดูแลจัดการย่อยหรือบัญชีลูกค้าของตนโดยตรง ดูข้อมูลเพิ่มเติมได้ที่เกี่ยวกับบัญชีดูแลจัดการ Search Ads 360 และการตรวจสอบสิทธิ์
ส่วนหัวรหัสลูกค้าสำหรับเข้าสู่ระบบ
ต้องระบุส่วนหัว login-customer-id เมื่อใช้บัญชีดูแลจัดการเพื่อเข้าถึงบัญชีดูแลจัดการย่อยหรือบัญชีลูกค้า แต่ไม่จำเป็นต้องระบุเมื่อเข้าถึง
บัญชีดูแลจัดการย่อยหรือบัญชีลูกค้าโดยตรง เราขอแนะนำให้ระบุ login-customer-id สำหรับผู้ใช้ที่ตรวจสอบสิทธิ์แล้วซึ่งมีสิทธิ์เข้าถึงบัญชีมากกว่า 1 บัญชีเสมอแม้จะไม่จำเป็นก็ตาม เพื่อหลีกเลี่ยงความกำกวมและป้องกันไม่ให้
กำหนดบริบทกับบัญชีที่ไม่ถูกต้องโดยไม่ตั้งใจ
คำขอควรมีรหัสลูกค้าของผู้ใช้ที่ได้รับอนุญาต โดยไม่มีขีดกลางสั้น (-) เช่น
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/campaignBudgets
การตั้งค่า login-customer-id จะเทียบเท่ากับการเลือกบัญชีใน UI ของ Search Ads 360 หลังจากที่ลงชื่อเข้าใช้หรือคลิกรูปโปรไฟล์ที่ด้านขวาบน
ส่วนหัวการตอบกลับ
ส่วนหัวต่อไปนี้ (หรือ gRPC Trailing-metadata) จะแสดงพร้อมกับเนื้อหาการตอบกลับ เราขอแนะนำให้คุณบันทึกค่าเหล่านี้เพื่อจุดประสงค์ในการแก้ไขข้อบกพร่อง
รหัสคำขอ
ส่วนหัว request-id เป็นสตริงที่ระบุคำขอโดยไม่ซ้ำกัน