โครงสร้างการเรียก API

คำแนะนำนี้จะอธิบายโครงสร้างทั่วไปของการเรียก API ทั้งหมด

หากใช้ไลบรารีของไคลเอ็นต์เพื่อโต้ตอบกับ API คุณไม่จำเป็นต้องทราบรายละเอียดคำขอที่อยู่เบื้องหลัง อย่างไรก็ตาม ความรู้เกี่ยวกับโครงสร้างการเรียก API บางอย่างอาจมีประโยชน์เมื่อทดสอบและ แก้ไขข้อบกพร่อง

Google Ads API เป็น gRPC API ที่มีการเชื่อมโยง REST ซึ่งหมายความว่า คุณสามารถเรียก API ได้ 2 วิธี

แนะนำ:

  1. สร้างเนื้อหาของคำขอเป็นบัฟเฟอร์โปรโตคอล

  2. ส่งไปยังเซิร์ฟเวอร์โดยใช้ HTTP/2

  3. ยกเลิกการซีเรียลไลซ์การตอบกลับเป็นบัฟเฟอร์โปรโตคอล

  4. ตีความผลลัพธ์

เอกสารประกอบส่วนใหญ่ของเราอธิบายการใช้ gRPC

ไม่บังคับ

  1. สร้างเนื้อหาของคำขอเป็นออบเจ็กต์ JSON

  2. ส่งไปยังเซิร์ฟเวอร์โดยใช้ HTTP 1.1

  3. ยกเลิกการซีเรียลไลซ์การตอบกลับเป็นออบเจ็กต์ JSON

  4. ตีความผลลัพธ์

ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้ REST ได้ในคู่มืออินเทอร์เฟซ REST

ชื่อทรัพยากร

ออบเจ็กต์ส่วนใหญ่ใน API จะระบุด้วยสตริงชื่อทรัพยากร สตริงเหล่านี้ยังใช้เป็น URL เมื่อใช้ REST API ด้วย ดูโครงสร้างของชื่อทรัพยากรได้ในชื่อทรัพยากรของอินเทอร์เฟซ REST

รหัสแบบผสม

หากรหัสของออบเจ็กต์ไม่ซ้ำกันทั่วโลก ระบบจะสร้างรหัสแบบรวมสำหรับออบเจ็กต์นั้น โดยการนำหน้ารหัสของออบเจ็กต์หลักและเครื่องหมายตัวหนอน (~)

ตัวอย่างเช่น เนื่องจากรหัสโฆษณาของกลุ่มโฆษณาไม่ซ้ำกันทั่วโลก เราจึงเพิ่มรหัสออบเจ็กต์ระดับบนสุด (กลุ่มโฆษณา) ไว้ข้างหน้ารหัสโฆษณาเพื่อสร้างรหัสแบบผสมที่ไม่ซ้ำกัน

  • AdGroupId ของ 123 + ~ + AdGroupAdId ของ 45678 = รหัสโฆษณากลุ่มโฆษณาแบบรวมของ 123~45678

ส่วนหัวของคำขอ

ส่วนหัว HTTP (หรือข้อมูลเมตา grpc) ที่มาพร้อมกับเนื้อหาในคำขอมีดังนี้

การให้สิทธิ์

คุณต้องระบุโทเค็นการเข้าถึง OAuth2 ในรูปแบบ Authorization: Bearer YOUR_ACCESS_TOKEN ซึ่งระบุ บัญชีดูแลจัดการที่ดำเนินการในนามของลูกค้า หรือผู้ลงโฆษณาที่จัดการบัญชีของตนเองโดยตรง ดูวิธีการดึงโทเค็นเพื่อการเข้าถึงได้ในคู่มือ OAuth2 โทเค็นเพื่อการเข้าถึงจะ ใช้งานได้ 1 ชั่วโมงหลังจากที่คุณได้รับ เมื่อโทเค็นหมดอายุ ให้รีเฟรชโทเค็นเพื่อการเข้าถึง เพื่อรับโทเค็นใหม่ โปรดทราบว่าไลบรารีไคลเอ็นต์ของเราจะรีเฟรชโทเค็นที่หมดอายุโดยอัตโนมัติ

developer-token

โทเค็นของนักพัฒนาคือสตริงที่มีอักขระ 22 ตัวซึ่งระบุนักพัฒนา Google Ads API ที่ไม่ซ้ำกัน ตัวอย่างสตริงโทเค็นของนักพัฒนาแอปคือ ABcdeFGH93KL-NOPQ_STUv โทเค็นนักพัฒนาแอปควรอยู่ในรูปแบบ developer-token : ABcdeFGH93KL-NOPQ_STUv

login-customer-id

นี่คือรหัสลูกค้าของลูกค้าที่ได้รับอนุญาตให้ใช้ในคำขอ โดยไม่มีขีดกลาง (-) หากคุณเข้าถึงบัญชีลูกค้าผ่านบัญชีดูแลจัดการ ส่วนหัวนี้ต้องระบุและต้องตั้งค่าเป็นรหัสลูกค้าของ บัญชีดูแลจัดการ

https://googleads.googleapis.com/v20/customers/1234567890/campaignBudgets:mutate

การตั้งค่า login-customer-id เทียบเท่ากับการเลือกบัญชีใน UI ของ Google Ads หลังจากลงชื่อเข้าใช้หรือคลิกรูปโปรไฟล์ที่ด้านขวาบน หากไม่ระบุส่วนหัวนี้ ระบบจะใช้ค่าเริ่มต้นเป็น operating customer

linked-customer-id

ส่วนหัวนี้ใช้โดย [third-party app analytics providers when uploading conversions to a linked Google Ads account เท่านั้น

พิจารณาสถานการณ์ที่ผู้ใช้ในบัญชี A ให้สิทธิ์เข้าถึงระดับอ่านและแก้ไข เอนทิตีของบัญชีแก่บัญชี B ผ่าน ThirdPartyAppAnalyticsLink เมื่อลิงก์แล้ว ผู้ใช้ในบัญชี B จะเรียก API กับบัญชี A ได้ โดยขึ้นอยู่กับสิทธิ์ที่ลิงก์ให้ ในกรณีนี้ สิทธิ์ในการเรียก API ของบัญชี A จะกำหนดโดยลิงก์ของบุคคลที่สามไปยังบัญชี B แทนที่จะเป็นความสัมพันธ์ของบัญชีดูแลจัดการที่ใช้ในการเรียก API อื่นๆ

ผู้ให้บริการวิเคราะห์แอปบุคคลที่สามจะทำการเรียก API ดังนี้

  • linked-customer-id: บัญชีการวิเคราะห์แอปของบุคคลที่สามที่อัปโหลด ข้อมูล (บัญชี B)
  • customer-id: บัญชี Google Ads ที่อัปโหลดข้อมูล (บัญชี A)
  • login-customer-id และส่วนหัว Authorization: ค่าที่รวมกันเพื่อ ระบุผู้ใช้ที่มีสิทธิ์เข้าถึงบัญชี B

ส่วนหัวการตอบกลับ

ระบบจะแสดงส่วนหัวต่อไปนี้ (หรือ grpc trailing-metadata) พร้อมกับเนื้อหาการตอบกลับ เราขอแนะนำให้คุณบันทึกค่าเหล่านี้ เพื่อวัตถุประสงค์ในการแก้ไขข้อบกพร่อง

request-id

request-id เป็นสตริงที่ระบุคำขอนี้โดยเฉพาะ

ก่อนหน้า
ข้อมูลเมตาของทรัพยากร