โครงสร้างการเรียก Search Ads 360 Reporting API

โดยทั่วไป การเรียก 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 เป็นสตริงที่ระบุคำขอโดยไม่ซ้ำกัน