โครงสร้างการเรียก 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 ด้วย ดูโครงสร้างได้ในชื่อทรัพยากรของอินเทอร์เฟซ REST

รหัสผสม

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

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

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

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

ส่วนหัว HTTP (หรือข้อมูลเมตา gRPC) ต่อไปนี้จะมาพร้อมกับ เนื้อหาในคำขอ

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

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

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

developer-token

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

login-customer-id

นี่คือรหัสลูกค้าของลูกค้าที่ได้รับอนุญาตให้ใช้ในคำขอ โดยไม่มีขีดกลาง (-) หากคุณเข้าถึงบัญชีลูกค้าผ่านบัญชีดูแลจัดการ ส่วนหัวนี้ จำเป็น และต้องตั้งค่าเป็นรหัสลูกค้าของบัญชีดูแลจัดการ หากคุณไม่ใส่ login-customer-id เมื่อตรวจสอบสิทธิ์ผ่านบัญชีดูแลจัดการ ระบบจะแสดงข้อผิดพลาด AuthorizationError.USER_PERMISSION_DENIED โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดประเภทนี้ในข้อผิดพลาดที่พบบ่อยสำหรับข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดประเภทนี้ โปรดดูคำอธิบายโดยละเอียดเกี่ยวกับวิธีแก้ไขการเข้าถึงบัญชีในคำแนะนำเกี่ยวกับ โมเดลการเข้าถึง OAuth

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

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

linked-customer-id

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

พิจารณาสถานการณ์ที่พาร์ทเนอร์ต้องเรียก API ไปยังบัญชี Google Ads ตามลิงก์ผลิตภัณฑ์

  • ผู้ลงโฆษณา: บัญชี Google Ads ที่ API กำลังจัดการหรืออัปเดต การเรียก รหัสบัญชีผู้ลงโฆษณาจะระบุไว้ในคำขอ ใน REST นี่คือพารามิเตอร์เส้นทาง customerId (เช่น customers/1111111111/...) และใน gRPC นี่คือช่อง customer_id ในคำขอ
  • พาร์ทเนอร์: บัญชีพาร์ทเนอร์ (เช่น ผู้ให้บริการวิเคราะห์แอปของบุคคลที่สาม หรือพาร์ทเนอร์ด้านข้อมูล)
  • บัญชีที่ลิงก์: บัญชี Google Ads ที่มี ลิงก์ผลิตภัณฑ์กับ พาร์ทเนอร์ ซึ่งให้สิทธิ์เข้าถึงผู้ลงโฆษณาแก่พาร์ทเนอร์

ผู้ใช้ที่มีสิทธิ์เข้าถึงพาร์ทเนอร์จะเรียก API เพื่อดำเนินการกับเอนทิตีในผู้ลงโฆษณา (เช่น อัปโหลด Conversion หรือจัดการรายชื่อผู้ใช้) บัญชีที่ลิงก์อาจเป็นผู้ลงโฆษณาเองหรือบัญชีดูแลจัดการของผู้ลงโฆษณา

คุณต้องตั้งค่าส่วนหัวของคำขอ ดังนี้

  • Authorization: โทเค็น OAuth2 สำหรับผู้ใช้ที่มีสิทธิ์เข้าถึงพาร์ทเนอร์
  • developer-token: โทเค็นของนักพัฒนาสำหรับแอปพลิเคชัน API ซึ่งโดยปกติจะเชื่อมโยงกับพาร์ทเนอร์
  • login-customer-id: รหัสลูกค้าของพาร์ทเนอร์ ผู้ใช้ที่ผ่านการตรวจสอบสิทธิ์แล้วต้องมีสิทธิ์เข้าถึงบัญชีนี้
  • linked-customer-id: รหัสลูกค้าของบัญชีที่ลิงก์ไว้ ส่วนหัวนี้บ่งชี้ว่าการให้สิทธิ์สำหรับคำขอนี้ขึ้นอยู่กับลิงก์ผลิตภัณฑ์ของบัญชีที่ลิงก์ไว้กับพาร์ทเนอร์

มีสถานการณ์การลิงก์ 2 แบบ

  • หากผู้ลงโฆษณามีลิงก์ผลิตภัณฑ์โดยตรงกับพาร์ทเนอร์ บัญชีที่ลิงก์ไว้จะเป็นผู้ลงโฆษณา และคุณต้องตั้งค่า linked-customer-id เป็นรหัสลูกค้าของผู้ลงโฆษณา
  • หากผู้ลงโฆษณาได้รับการจัดการโดยบัญชีดูแลจัดการที่มีลิงก์ผลิตภัณฑ์กับพาร์ทเนอร์ บัญชีที่ลิงก์ไว้จะเป็นบัญชีดูแลจัดการ และคุณต้องตั้งค่า linked-customer-id เป็นรหัสลูกค้าของบัญชีดูแลจัดการ

ตัวอย่างที่ 1: ลิงก์โดยตรง

หากผู้ลงโฆษณา 1111111111 มีลิงก์โดยตรงกับพาร์ทเนอร์ 2222222222 และ การเรียก API กำหนดเป้าหมายเป็น customers/1111111111/...

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

ตัวอย่างที่ 2: ลิงก์บัญชีดูแลจัดการ

หากผู้ลงโฆษณา 1111111111 ได้รับการจัดการโดยบัญชีดูแลจัดการ 3333333333 บัญชีดูแลจัดการ 3333333333 มีลิงก์กับพาร์ทเนอร์ 2222222222 และการเรียก API กำหนดเป้าหมายเป็น customers/1111111111/...

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

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

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

request-id

request-id คือสตริงที่ระบุคำขอนี้ที่ไม่ซ้ำกัน

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