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