โครงสร้างการเรียก 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) ที่มาพร้อมกับ เนื้อหาในคำขอมีดังนี้

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

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

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

login-customer-id

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

https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/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: โทเค็นเพื่อการเข้าถึง OAuth 2.0 สำหรับผู้ใช้ที่มีสิทธิ์เข้าถึงพาร์ทเนอร์
• login-customer-id: รหัสลูกค้าของพาร์ทเนอร์ ผู้ใช้ที่ผ่านการตรวจสอบสิทธิ์แล้วต้องมีสิทธิ์เข้าถึงบัญชีนี้
• linked-customer-id: รหัสลูกค้าของบัญชีที่ลิงก์ไว้ ส่วนหัวนี้ส่งสัญญาณว่าการให้สิทธิ์สำหรับคำขอนี้ขึ้นอยู่กับลิงก์ผลิตภัณฑ์ของบัญชีที่ลิงก์ไว้กับพาร์ทเนอร์

สถานการณ์การลิงก์มี 2 กรณีดังนี้

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

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

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

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

ตัวอย่างที่ 2: ลิงก์ผู้จัดการ

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

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

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

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

request-id

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