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