โครงสร้างการเรียก 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

ตัวระบุทรัพยากร

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

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

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

รหัสแบบผสม

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

เช่น AdGroupAd มีรูปแบบชื่อทรัพยากร customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id} เนื่องจากตัวระบุแบบรวมประกอบด้วยรหัสกลุ่มโฆษณาหลัก (ad_group.id) และรหัสโฆษณาพื้นฐาน (ad_group_ad.ad.id) เราจึงเพิ่มรหัสกลุ่มโฆษณาไว้หน้า รหัสโฆษณา ดังนี้

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

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

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

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

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

หากพบข้อผิดพลาดในการให้สิทธิ์ โปรดตรวจสอบว่าคุณใช้ข้อมูลเข้าสู่ระบบที่ถูกต้องและมีสิทธิ์เพียงพอ USER_PERMISSION_DENIED ข้อผิดพลาด แสดงว่าผู้ใช้ที่ผ่านการตรวจสอบสิทธิ์อาจไม่มีสิทธิ์เข้าถึงบัญชีลูกค้า ที่ระบุในคำขอ หากโปรเจ็กต์ Google Cloud ได้รับอนุมัติสำหรับการเข้าถึง Test เท่านั้น และคุณส่งคำขอที่กำหนดเป้าหมายไปยังบัญชีที่ใช้งานจริง API จะแสดง AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION ใน v25 ขึ้นไป (หรือ AuthorizationError.ACTION_NOT_PERMITTED ใน v24 และก่อนหน้า) ดูรายละเอียดเกี่ยวกับการจัดการสิทธิ์ได้ที่ระดับการเข้าถึงของ Google Ads

login-customer-id

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

https://googleads.googleapis.com/v25/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: โทเค็นเพื่อการเข้าถึง 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 คือสตริงที่ระบุคำขอนี้อย่างไม่ซ้ำกัน ระบุค่านี้เมื่อติดต่อทีมสนับสนุนเพื่อช่วยแก้ปัญหาคำขอ API ที่ล้มเหลวหรือไม่คาดคิด