โครงสร้างการเรียก API

คู่มือนี้จะอธิบายโครงสร้างทั่วไปของการเรียก API ทั้งหมด

หากใช้ไลบรารีของไคลเอ็นต์เพื่อโต้ตอบกับ API คุณจะไม่จําเป็นต้องกังวลเกี่ยวกับรายละเอียดคําขอพื้นฐาน อย่างไรก็ตาม การทราบข้อมูลคร่าวๆ เกี่ยวกับเหตุการณ์เหล่านี้จะมีประโยชน์เมื่อทำการทดสอบและการแก้ไขข้อบกพร่อง

Google Ads API เป็น gRPC API ที่มีการเชื่อมโยง REST ซึ่งหมายความว่าการเรียก API ทำได้ 2 วิธี

  1. [แนะนำ] สร้างเนื้อหาของคำขอเป็นบัฟเฟอร์โปรโตคอล ส่งไปยังเซิร์ฟเวอร์โดยใช้ HTTP/2 แปลงการตอบสนองเป็นบัฟเฟอร์โปรโตคอล และตีความผลลัพธ์ เอกสารประกอบส่วนใหญ่อธิบายการใช้ gRPC

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

ก่อนหน้า
ข้อมูลเมตาของทรัพยากร