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