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

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

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

รหัสคอมโพสิต

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

ตัวอย่างเช่น เนื่องจากรหัสโฆษณาของกลุ่มโฆษณาไม่ซ้ำกันทั่วโลก เราจึงใส่รหัสออบเจ็กต์หลัก (กลุ่มโฆษณา) ไว้ข้างหน้าเพื่อสร้างรหัสผสมที่ไม่ซ้ำกัน ดังนี้

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

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

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

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

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

developer-token

โทเค็นนักพัฒนาคือสตริง 22 อักขระที่ระบุนักพัฒนา Google Ads API ได้อย่างไม่ซ้ำกัน ตัวอย่างสตริงโทเค็นของนักพัฒนาแอปคือ ABcdeFGH93KL-NOPQ_STUv โทเค็นนักพัฒนาแอปควรอยู่ในรูปแบบ developer-token : ABcdeFGH93KL-NOPQ_STUv

login-customer-id

รหัสลูกค้าที่ได้รับอนุญาตเพื่อใช้ในคําขอ โดยไม่มีขีดกลาง (-) หากการเข้าถึงบัญชีลูกค้าของคุณผ่านบัญชีดูแลจัดการ คุณต้องใช้ส่วนหัวนี้และต้องตั้งค่าเป็นรหัสลูกค้าของบัญชีดูแลจัดการ

https://googleads.googleapis.com/v20/customers/1234567890/campaignBudgets:mutate

การตั้งค่า login-customer-id เทียบเท่ากับการเลือกบัญชีใน UI ของ Google Ads หลังจากลงชื่อเข้าใช้หรือคลิกรูปโปรไฟล์ที่ด้านขวาบน หากคุณไม่ใส่ส่วนหัวนี้ ระบบจะใช้ค่าเริ่มต้นเป็น operating customer

linked-customer-id

ส่วนหัวนี้ใช้โดย [ผู้ให้บริการวิเคราะห์แอปของบุคคลที่สามเมื่ออัปโหลด Conversion ไปยังบัญชี Google Ads ที่ลิงก์เท่านั้น

พิจารณาสถานการณ์ที่ผู้ใช้ในบัญชี A ให้สิทธิ์อ่านและแก้ไขให้กับบัญชี B ผ่าน ThirdPartyAppAnalyticsLink เมื่อลิงก์แล้ว ผู้ใช้ในบัญชี B จะเรียก API กับบัญชี A ได้ โดยขึ้นอยู่กับสิทธิ์ที่ลิงก์ให้ ในกรณีนี้ สิทธิ์การเรียก API ไปยังบัญชี A จะกำหนดโดยลิงก์ของบุคคลที่สามกับบัญชี B ไม่ใช่ความสัมพันธ์ระหว่างบัญชีดูแลจัดการกับบัญชีที่ใช้ในการเรียก API อื่นๆ

ผู้ให้บริการวิเคราะห์แอปบุคคลที่สามจะเรียก API ดังนี้

• linked-customer-id: บัญชีการวิเคราะห์แอปของบุคคลที่สามที่อัปโหลดข้อมูล (บัญชี B)
• customer-id: บัญชี Google Ads ที่อัปโหลดข้อมูล (บัญชี A)
• ส่วนหัว login-customer-id และ Authorization: ชุดค่าผสมเพื่อระบุผู้ใช้ที่มีสิทธิ์เข้าถึงบัญชี B

ส่วนหัวการตอบกลับ

ระบบจะแสดงผลส่วนหัวต่อไปนี้ (หรือ grpc trailing-metadata) กับเนื้อหาการตอบกลับ เราขอแนะนําให้คุณบันทึกค่าเหล่านี้เพื่อวัตถุประสงค์ในการแก้ไขข้อบกพร่อง

request-id

request-id คือสตริงที่ระบุคำขอนี้โดยไม่ซ้ำกัน