คู่มือนี้จะอธิบายโครงสร้างทั่วไปของการเรียก API ทั้งหมด
หากใช้ไลบรารีของไคลเอ็นต์เพื่อโต้ตอบกับ API คุณจะไม่ต้องกังวลเกี่ยวกับรายละเอียดคำขอที่สำคัญ อย่างไรก็ตาม การรู้ข้อมูลเกี่ยวกับเครื่องมือเหล่านี้สักเล็กน้อยอาจเป็นประโยชน์ขณะทดสอบและแก้ไขข้อบกพร่อง
Google Ads API เป็น gRPC API ที่มีการเชื่อมโยง REST ซึ่งหมายความว่ามี 2 วิธีในการเรียก API
[ที่ต้องการ] สร้างเนื้อหาของคำขอเป็นบัฟเฟอร์โปรโตคอล ส่งไปยังเซิร์ฟเวอร์โดยใช้ 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/v17/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 คือสตริงที่ระบุคำขอนี้โดยไม่ซ้ำกัน