คู่มือนี้อธิบายโครงสร้างทั่วไปของการเรียก API ทั้งหมด
หากใช้ไลบรารีของไคลเอ็นต์เพื่อโต้ตอบกับ API คุณไม่จำเป็นต้อง ทราบรายละเอียดคำขอพื้นฐาน อย่างไรก็ตาม ความรู้บางอย่างเกี่ยวกับโครงสร้างการเรียก API อาจมีประโยชน์เมื่อทดสอบและแก้ไขข้อบกพร่อง
Google Ads API เป็น gRPC API ที่มีการเชื่อมโยง REST ซึ่งหมายความว่า คุณเรียกใช้ API ได้ 2 วิธี
แนะนำ:
สร้างเนื้อหาของคำขอเป็น บัฟเฟอร์โปรโตคอล
ส่งไปยังเซิร์ฟเวอร์โดยใช้ HTTP/2
ยกเลิกการซีเรียลไลซ์การตอบกลับเป็นบัฟเฟอร์โปรโตคอล
ตีความผลลัพธ์
เอกสารประกอบส่วนใหญ่ของเราอธิบายการใช้ gRPC
ไม่บังคับ
สร้างเนื้อหาของคำขอเป็นออบเจ็กต์ JSON
ส่งไปยังเซิร์ฟเวอร์โดยใช้ HTTP 1.1
ยกเลิกการซีเรียลไลซ์การตอบกลับเป็นออบเจ็กต์ JSON
ตีความผลลัพธ์
ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้ REST ได้ในคู่มืออินเทอร์เฟซ REST
ชื่อทรัพยากร
ออบเจ็กต์ส่วนใหญ่ใน API จะระบุด้วยสตริงชื่อทรัพยากร สตริงเหล่านี้ยังใช้เป็น URL เมื่อใช้ REST API ด้วย ดูโครงสร้างของชื่อทรัพยากรได้ในชื่อทรัพยากรของอินเทอร์เฟซ REST
รหัสแบบผสม
หากรหัสของออบเจ็กต์ไม่ซ้ำกันทั่วโลก ระบบจะสร้างรหัสแบบรวมสำหรับออบเจ็กต์นั้นโดยการนำหน้ารหัสหลักและเครื่องหมายตัวหนอน (~)
ตัวอย่างเช่น เนื่องจากรหัสโฆษณาของกลุ่มโฆษณาไม่ซ้ำกันทั่วโลก เราจึงเพิ่มรหัสออบเจ็กต์ระดับบนสุด (กลุ่มโฆษณา) ไว้ข้างหน้ารหัสโฆษณาเพื่อสร้างรหัสแบบผสมที่ไม่ซ้ำกัน
AdGroupIdของ123+~+AdGroupAdIdของ45678= รหัสโฆษณากลุ่มโฆษณาแบบรวมของ123~45678
ส่วนหัวของคำขอ
ส่วนหัว HTTP (หรือข้อมูลเมตา grpc) ที่มาพร้อมกับเนื้อหาในคำขอมีดังนี้
การให้สิทธิ์
คุณต้องระบุโทเค็นเพื่อการเข้าถึง OAuth2 ในรูปแบบ Authorization: Bearer
YOUR_ACCESS_TOKEN ซึ่งระบุบัญชีดูแลจัดการที่ดำเนินการในนามของลูกค้า หรือผู้ลงโฆษณาที่จัดการบัญชีของตนเองโดยตรง ดูวิธีการ
ดึงโทเค็นเพื่อการเข้าถึงได้ในคู่มือ
OAuth2 โทเค็นเพื่อการเข้าถึงจะใช้งานได้เป็นเวลา 1 ชั่วโมงหลังจากที่คุณ
ได้รับ เมื่อโทเค็นหมดอายุ ให้รีเฟรชโทเค็นเพื่อการเข้าถึงเพื่อรับโทเค็นใหม่
โปรดทราบว่าไลบรารีไคลเอ็นต์ของเราจะรีเฟรชโทเค็นที่หมดอายุโดยอัตโนมัติ
หากพบข้อผิดพลาดในการให้สิทธิ์ โปรดตรวจสอบว่าคุณใช้ข้อมูลเข้าสู่ระบบที่ถูกต้องและมีสิทธิ์เพียงพอ ข้อผิดพลาด USER_PERMISSION_DENIED
แสดงว่าผู้ใช้ที่ได้รับการตรวจสอบสิทธิ์อาจไม่มีสิทธิ์เข้าถึงบัญชีลูกค้า
ที่ระบุในคำขอ ดูรายละเอียดเกี่ยวกับการจัดการสิทธิ์ได้ที่ระดับการเข้าถึง Google Ads
developer-token
โทเค็นของนักพัฒนาคือสตริงที่มีอักขระ 22 ตัวซึ่งระบุนักพัฒนา Google Ads API
ที่ไม่ซ้ำกัน สตริงโทเค็นของนักพัฒนาแอปตัวอย่างคือ ABcdeFGH93KL-NOPQ_STUv โทเค็นของนักพัฒนาควรอยู่ในรูปแบบ developer-token :
ABcdeFGH93KL-NOPQ_STUv
login-customer-id
นี่คือรหัสลูกค้าของลูกค้าที่ได้รับอนุญาตให้ใช้ในคำขอ
โดยไม่มีขีดกลาง (-) หากคุณเข้าถึงบัญชีลูกค้าผ่านบัญชีดูแลจัดการ
ส่วนหัวนี้ต้องระบุและต้องตั้งค่าเป็นรหัสลูกค้าของ
บัญชีดูแลจัดการ หากคุณไม่ใส่ login-customer-id เมื่อ
ตรวจสอบสิทธิ์ผ่านบัญชีดูแลจัดการ จะทำให้เกิดข้อผิดพลาด AuthorizationError.USER_PERMISSION_DENIED ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดประเภทนี้ได้ที่ข้อผิดพลาดที่พบบ่อย
https://googleads.googleapis.com/v24/customers/1234567890/campaignBudgets:mutate
การตั้งค่า login-customer-id จะเทียบเท่ากับการเลือกบัญชีใน
UI ของ Google Ads หลังจากลงชื่อเข้าใช้หรือคลิกรูปโปรไฟล์ที่ด้านขวาบน
หากไม่ระบุส่วนหัวนี้ ระบบจะใช้ค่าเริ่มต้นเป็น operating
customer
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: โทเค็น OAuth2 สำหรับผู้ใช้ที่มีสิทธิ์เข้าถึงพาร์ทเนอร์developer-token: โทเค็นของนักพัฒนาสำหรับแอปพลิเคชัน API โดยปกติจะเชื่อมโยงกับพาร์ทเนอร์login-customer-id: รหัสลูกค้าของพาร์ทเนอร์ ผู้ใช้ที่ได้รับการตรวจสอบสิทธิ์ ต้องมีสิทธิ์เข้าถึงบัญชีนี้linked-customer-id: รหัสลูกค้าของบัญชีที่ลิงก์ ส่วนหัวนี้ ส่งสัญญาณว่าการให้สิทธิ์สำหรับคำขอนี้ขึ้นอยู่กับลิงก์ผลิตภัณฑ์ของบัญชีที่ลิงก์ กับพาร์ทเนอร์
สถานการณ์การลิงก์มี 2 แบบ ดังนี้
- หากผู้ลงโฆษณามีลิงก์ผลิตภัณฑ์โดยตรงกับพาร์ทเนอร์ บัญชีที่ลิงก์
คือผู้ลงโฆษณา และ
linked-customer-idต้องตั้งค่าเป็น รหัสลูกค้าของผู้ลงโฆษณา - หากผู้ลงโฆษณาได้รับการจัดการโดยบัญชีดูแลจัดการที่มีลิงก์ผลิตภัณฑ์กับ
พาร์ทเนอร์ บัญชีที่ลิงก์จะเป็นบัญชีดูแลจัดการ และ
linked-customer-idต้องตั้งค่าเป็นรหัสลูกค้าของบัญชีดูแลจัดการ
ตัวอย่างที่ 1: ลิงก์โดยตรง
หากผู้ลงโฆษณา 1111111111 มีลิงก์โดยตรงกับพาร์ทเนอร์ 2222222222 และ
การเรียก API กำหนดเป้าหมายเป็น customers/1111111111/...
Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111
ตัวอย่างที่ 2: ลิงก์บัญชีดูแลจัดการ
หากผู้ลงโฆษณา 1111111111 ได้รับการจัดการโดยผู้จัดการ 3333333333 ผู้จัดการ
3333333333 จะมีลิงก์กับพาร์ทเนอร์ 2222222222 และการเรียก API จะกำหนดเป้าหมายเป็น customers/1111111111/...
Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333
ส่วนหัวการตอบกลับ
ส่วนหัวต่อไปนี้ (หรือ grpc trailing-metadata) จะ แสดงพร้อมกับเนื้อหาการตอบกลับ เราขอแนะนำให้คุณบันทึกค่าเหล่านี้เพื่อ วัตถุประสงค์ในการแก้ไขข้อบกพร่อง
request-id
request-id เป็นสตริงที่ระบุคำขอนี้โดยไม่ซ้ำกัน