โดยปกติการเรียกใช้ Search Ads 360 Reporting API จะทําผ่านคลังลูกค้าที่ติดตั้งไว้ ดูข้อมูลเพิ่มเติมได้ในคำอธิบายไลบรารีของไคลเอ็นต์ อย่างไรก็ตาม ความรู้เกี่ยวกับโครงสร้างของรายละเอียดคําขอพื้นฐานจะมีประโยชน์เมื่อทดสอบและแก้ไขข้อบกพร่อง
Search Ads 360 Reporting API เป็น gRPC API ที่มี REST การเชื่อมโยง ซึ่งหมายความว่าคุณจะเรียก API ได้ 2 วิธีดังนี้
- วิธีที่ต้องการ
- ใช้คลังลูกค้า
- สร้างเนื้อหาของคําขอเป็น Protocol Buffer
- ส่งคําขอไปยังเซิร์ฟเวอร์โดยใช้ HTTP/2
- แปลงค่าการตอบกลับเป็นบัฟเฟอร์โปรโตคอล
- ตีความผลลัพธ์
- วิธีอื่นที่ไม่บังคับ
- ใช้ REST
- สร้างเนื้อหาของคำขอเป็นออบเจ็กต์ JSON
- ส่งคำขอไปยังเซิร์ฟเวอร์โดยใช้ HTTP 1.1
- แปลงค่าการตอบกลับเป็นออบเจ็กต์ JSON
- ตีความผลลัพธ์
ดูข้อมูลเพิ่มเติมได้ที่ Google Cloud API
ส่วนต่อไปนี้มีผลกับทั้งโปรโตคอล 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 คือสตริงที่ระบุค่าเฉพาะของคำขอที่ไม่ซ้ำกัน