คู่มือนี้จะอธิบายโครงสร้างทั่วไปของการเรียก API ทั้งหมด
หากคุณใช้ไลบรารีของไคลเอ็นต์เพื่อโต้ตอบกับ API คุณก็ไม่จำเป็นต้องกังวลเกี่ยวกับรายละเอียดคำขอที่สำคัญ อย่างไรก็ตาม การรู้เกี่ยวกับตัวแปรเหล่านี้สักเล็กน้อยจะมีประโยชน์เมื่อทำการทดสอบและแก้ไขข้อบกพร่อง
Google Ads API คือ gRPC API ที่มีการเชื่อมโยง REST ซึ่งหมายความว่ามี 2 วิธีในการเรียก API
[Preferred] สร้างเนื้อหาของคำขอเป็นบัฟเฟอร์โปรโตคอล ส่งไปยังเซิร์ฟเวอร์โดยใช้ HTTP/2 ดีซีเรียลรีลีสการตอบกลับไปยังบัฟเฟอร์โปรโตคอล และตีความผลลัพธ์ เอกสารประกอบส่วนใหญ่อธิบายการใช้ gRPC
[ไม่บังคับ] สร้างเนื้อหาของคำขอเป็นออบเจ็กต์ 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 ชั่วโมงหลังจากที่คุณได้รับ เมื่อโทเค็นนั้นหมดอายุ ให้รีเฟรชโทเค็นเพื่อการเข้าถึงใหม่เพื่อเรียกข้อมูลโทเค็นใหม่ โปรดทราบว่าไลบรารีของไคลเอ็นต์จะรีเฟรชโทเค็นที่หมดอายุโดยอัตโนมัติ
โทเค็นของนักพัฒนา
โทเค็นของนักพัฒนาคือสตริงที่มีอักขระ 22 ตัวที่ระบุนักพัฒนาซอฟต์แวร์ Google Ads API ได้อย่างไม่ซ้ำกัน ตัวอย่างสตริงโทเค็นของนักพัฒนาคือ ABcdeFGH93KL-NOPQ_STUv โทเค็นของนักพัฒนาควรรวมอยู่ในรูปแบบ developer-token : ABcdeFGH93KL-NOPQ_STUv
login-customer-id
นี่คือรหัสลูกค้าของลูกค้าที่ได้รับสิทธิ์สำหรับใช้ในคำขอโดยไม่มีขีดกลางสั้น (-) หากคุณเข้าถึงบัญชีลูกค้าผ่านบัญชีดูแลจัดการ ส่วนหัวนี้จะต้องระบุและต้องตั้งค่าเป็นรหัสลูกค้าของบัญชีดูแลจัดการ
https://googleads.googleapis.com/v16/customers/1234567890/campaignBudgets:mutate
การตั้งค่า login-customer-id เทียบเท่ากับการเลือกบัญชีใน UI ของ Google Ads หลังจากลงชื่อเข้าใช้หรือคลิกรูปโปรไฟล์ที่ด้านขวาบน หากคุณไม่ใส่ส่วนหัวนี้ ส่วนหัวตามค่าเริ่มต้นจะเป็นลูกค้าที่ใช้งานอยู่
รหัสลูกค้าที่ลิงก์
ส่วนหัวนี้จะใช้โดยผู้ให้บริการวิเคราะห์แอปบุคคลที่สามเมื่ออัปโหลด 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 เป็นสตริงที่ระบุคำขอนี้โดยไม่ซ้ำกัน