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