วิดีโอ: ดูการบรรยายเรื่องบริการและแหล่งข้อมูลจากเวิร์กช็อปปี 2019
คู่มือนี้จะแนะนำคอมโพเนนต์หลักที่ประกอบกันเป็น Google Ads API Google Ads API ประกอบด้วยทรัพยากรและบริการ ทรัพยากรแสดงถึง Google Ads ขณะที่บริการจะดึงข้อมูลและแก้ไขเอนทิตี Google Ads
ลำดับชั้นของออบเจ็กต์
บัญชี Google Ads จะดูเป็นแบบลำดับชั้นของออบเจ็กต์ได้
ทรัพยากรระดับบนสุดของบัญชีคือ ลูกค้า
ลูกค้าแต่ละรายมีบัญชีที่ใช้งานอยู่ แคมเปญ
แต่ละแคมเปญประกอบด้วยกลุ่มโฆษณาอย่างน้อย 1 กลุ่มที่ใช้ เพื่อจัดกลุ่มโฆษณาเป็นคอลเล็กชันที่สมเหตุสมผล
โฆษณาระดับกลุ่มโฆษณา ซึ่งแสดงถึงโฆษณาที่คุณ วิ่งอยู่ ยกเว้น App Campaign ที่มีโฆษณาในกลุ่มโฆษณาได้เพียง 1 รายการต่อโฆษณา แต่ละกลุ่มจะมีโฆษณาของกลุ่มโฆษณาอย่างน้อยหนึ่งรายการ
คุณสามารถแนบ AdGroupCriterion อย่างน้อย 1 รายการ
หรือ CampaignCriterion ลงในกลุ่มโฆษณาหรือ
แคมเปญ โดยเป็นเกณฑ์ที่กำหนดวิธีที่โฆษณาแสดง
เกณฑ์ประเภทต่างๆ มีอยู่หลายประเภท เช่น คีย์เวิร์ด ช่วงอายุ และสถานที่ตั้ง เกณฑ์ที่กำหนดในแคมเปญ มีผลต่อทรัพยากรอื่นๆ ทั้งหมดภายในแคมเปญนั้น คุณสามารถระบุ งบประมาณและวันที่ของทั้งแคมเปญ
สุดท้าย คุณสามารถแนบส่วนขยายที่ ระดับบัญชี แคมเปญ หรือกลุ่มโฆษณา ส่วนขยายช่วยให้คุณเพิ่ม ลงในโฆษณาของคุณ เช่น หมายเลขโทรศัพท์ ที่อยู่ หรือการส่งเสริมการขาย
แหล่งข้อมูล
ทรัพยากรจะแสดงถึงเอนทิตีภายในบัญชี Google Ads Campaign และ AdGroup เป็น 2 ตัวอย่าง
ทรัพยากรจำนวนมาก
รหัสออบเจ็กต์
ออบเจ็กต์ทั้งหมดใน Google Ads จะระบุโดยใช้รหัสของออบเจ็กต์นั้น รหัสบางส่วนได้แก่ ที่ไม่ซ้ำกันทั่วโลกในบัญชี Google Ads ทั้งหมด ขณะที่บัญชีอื่นๆ จะไม่ซ้ำกันภายใน ขอบเขตที่จำกัด
| รหัสออบเจ็กต์ | ขอบเขตของความเป็นเอกลักษณ์ | ไม่เหมือนใคร |
|---|---|---|
| รหัสงบประมาณ | ทั่วโลก | ใช่ |
| รหัสแคมเปญ | ทั่วโลก | ใช่ |
| รหัส AdGroup | ทั่วโลก | ใช่ |
| รหัสโฆษณา | กลุ่มโฆษณา | ไม่ แต่คู่ (AdGroupId, AdId) ไม่ซ้ำกันทั่วโลก |
| รหัสเกณฑ์ของกลุ่มโฆษณา | กลุ่มโฆษณา | ไม่ แต่คู่ (AdGroupId, CriterionId) ไม่ซ้ำกันทั่วโลก |
| รหัสเกณฑ์แคมเปญ | แคมเปญ | ไม่ แต่คู่ (CampaignId, CriterionId) ไม่ซ้ำกันทั่วโลก |
| ส่วนขยายโฆษณา | แคมเปญ | ไม่ แต่คู่ (CampaignId, AdExtensionId) ไม่ซ้ำกันทั่วโลก |
| รหัสฟีด | ทั่วโลก | ใช่ |
| รหัสรายการฟีด | ทั่วโลก | ใช่ |
| รหัสแอตทริบิวต์ฟีด | ฟีด | ไม่ได้ |
| รหัสการแมปฟีด | ทั่วโลก | ใช่ |
| รหัสป้ายกำกับ | ทั่วโลก | ใช่ |
| รหัสรายการผู้ใช้ | ทั่วโลก | ใช่ |
กฎรหัสนี้จะมีประโยชน์เมื่อออกแบบพื้นที่เก็บข้อมูลในเครื่องสำหรับ Google Ads ออบเจ็กต์
ออบเจ็กต์บางอย่างใช้กับเอนทิตีได้หลายประเภท ในกรณีดังกล่าว ออบเจ็กต์
มีฟิลด์ type ที่อธิบายเนื้อหา ตัวอย่างเช่น
AdGroupAd อาจหมายถึงออบเจ็กต์ เช่น โฆษณาแบบข้อความ
โฆษณาโรงแรม หรือโฆษณาท้องถิ่น ค่านี้สามารถเข้าถึงได้ผ่านทาง
AdGroupAd.ad.type และแสดงผลค่าในช่อง
enum ของ AdType
ชื่อทรัพยากร
ทรัพยากรแต่ละรายการจะได้รับการระบุโดยไม่ซ้ำกันด้วยสตริง resource_name ซึ่ง
จะเชื่อมต่อทรัพยากรและระดับบนสุดของทรัพยากรเข้าในเส้นทาง ตัวอย่างเช่น แคมเปญ
ชื่อทรัพยากรจะมีรูปแบบดังนี้
customers/customer_id/campaigns/campaign_id
ดังนั้นสําหรับแคมเปญที่มีรหัส 987654 ในบัญชี Google Ads ที่มีรหัสลูกค้า
1234567 resource_name จะเป็น:
customers/1234567/campaigns/987654
บริการ
บริการช่วยให้คุณดึงข้อมูลและแก้ไขเอนทิตี Google Ads ได้ โดยมี 3 ประเภท ของบริการ: การแก้ไข การดึงข้อมูลวัตถุและสถิติ และการเรียกข้อมูลเมตา บริการต่างๆ
แก้ไข (เปลี่ยนแปลง) ออบเจ็กต์
บริการเหล่านี้แก้ไขอินสแตนซ์ของประเภททรัพยากรที่เชื่อมโยงโดยใช้ mutate
อีกครั้ง นอกจากนี้ ยังระบุคำขอ get ที่เรียกทรัพยากรรายการเดียวด้วย
ซึ่งอาจเป็นประโยชน์ในการตรวจสอบโครงสร้างของทรัพยากร
ตัวอย่างบริการ:
CustomerServiceสำหรับการแก้ไข ลูกค้าCampaignServiceสำหรับการแก้ไข แคมเปญAdGroupServiceสำหรับแก้ไขกลุ่มโฆษณา
คำขอ mutate แต่ละรายการต้องมีออบเจ็กต์ operation ที่เกี่ยวข้อง สำหรับ
ตัวอย่างเช่น เมธอด CampaignService.MutateCampaigns ควรมีอย่างน้อย 1 รายการ
อินสแตนซ์ของ CampaignOperation โปรดดู
การเปลี่ยนและตรวจสอบออบเจ็กต์สำหรับ
การพูดคุยอย่างละเอียดเกี่ยวกับการปฏิบัติงาน
การเปลี่ยนรูปแบบพร้อมกัน
ออบเจ็กต์ Google Ads ไม่สามารถแก้ไขพร้อมกันได้โดยแหล่งที่มามากกว่า 1 แห่ง ช่วงเวลานี้ อาจทำให้เกิดข้อผิดพลาดหากคุณมีผู้ใช้หลายคนอัปเดตออบเจ็กต์เดียวกัน กับแอปของคุณ หรือหากคุณกำลังเปลี่ยนแปลงออบเจ็กต์ Google Ads พร้อมกันโดยใช้หลายรายการ ชุดข้อความ ซึ่งรวมถึงการอัปเดตออบเจ็กต์จากชุดข้อความหลายรายการ หรือจากแอปพลิเคชันอื่น (เช่น แอปของคุณและ เซสชัน UI ของ Google Ads พร้อมกัน)
API ไม่ได้ให้วิธีล็อกออบเจ็กต์ก่อนที่จะอัปเดต หากมีแหล่งที่มา 2 แหล่ง
เพื่อเปลี่ยนรูปแบบวัตถุไปพร้อมๆ กัน API จะเพิ่ม
DatabaseError.CONCURRENT_MODIFICATION_ERROR
การกลายพันธุ์แบบไม่พร้อมกันหรือแบบพร้อมกัน
เมธอด Mutate ของ Google Ads API เป็นแบบพร้อมกัน การเรียก API จะแสดงผลการตอบกลับเท่านั้น หลังจากที่ออบเจ็กต์มีการเปลี่ยนแปลง คุณต้องรอการตอบสนองสำหรับ อีกครั้ง แม้ว่าวิธีนี้จะค่อนข้างตรงไปตรงมาในการเขียนโค้ด แต่ จะส่งผลกระทบด้านลบต่อการจัดสรรภาระงานและการใช้ทรัพยากรที่สูญเปล่าหากกระบวนการถูกบังคับให้ทำ รอให้การโทรเสร็จสิ้น
อีกวิธีหนึ่งคือการเปลี่ยนแปลงวัตถุแบบอะซิงโครนัสโดยใช้
BatchJobService ซึ่งดำเนินการกลุ่ม
การดำเนินงานของบริการหลายอย่างโดยไม่ต้องรอให้การดำเนินการเสร็จสิ้น เมื่อ
มีการส่งงานแบบกลุ่ม เซิร์ฟเวอร์ Google Ads API จะปฏิบัติการแบบไม่พร้อมกัน
ทำให้มีกระบวนการทำงานอื่นๆ มากขึ้น คุณสามารถตรวจสอบ
สถานะงานสำหรับการเสร็จสมบูรณ์
ดูคู่มือการประมวลผลเป็นกลุ่มสำหรับข้อมูลเพิ่มเติมเกี่ยวกับ การประมวลผลข้อมูลแบบไม่พร้อมกัน
เปลี่ยนแปลงการตรวจสอบ
การตรวจสอบคำขอการเปลี่ยนรูปแบบส่วนใหญ่ได้โดยไม่ต้องดำเนินการเรียกใช้จริง เทียบกับข้อมูลจริง คุณสามารถทดสอบคำขอเพื่อหาพารามิเตอร์ที่หายไปและ โดยไม่ต้องดำเนินการจริง
หากต้องการใช้ฟีเจอร์นี้ ให้ตั้งค่าช่องบูลีน validate_only ที่ไม่บังคับของคำขอเป็น
true คำขอจะได้รับการตรวจสอบอย่างสมบูรณ์เสมือนว่า
ระบบแต่ข้ามการดำเนินการขั้นสุดท้าย ถ้าไม่พบข้อผิดพลาด ฟิลด์
แสดงการตอบสนอง หากตรวจสอบไม่สำเร็จ ข้อความแสดงข้อผิดพลาดในการตอบกลับจะ
เพื่อระบุจุดล้มเหลว
validate_only มีประโยชน์อย่างยิ่งในการทดสอบโฆษณาสำหรับนโยบายทั่วไป
การละเมิดดังกล่าว โฆษณาถูกปฏิเสธโดยอัตโนมัติหากละเมิดนโยบาย เช่น
มีคำ เครื่องหมายวรรคตอน การใช้อักษรตัวพิมพ์ใหญ่ หรือความยาวที่เฉพาะเจาะจง โฆษณาที่ไม่ดีรายการเดียว
อาจทำให้ทั้งกลุ่มทำงานไม่สำเร็จ การทดสอบโฆษณาใหม่ภายใน validate_only
สามารถเปิดเผยการละเมิดใดๆ ก็ตาม ดูตัวอย่างโค้ดสำหรับ handling
ข้อผิดพลาดเกี่ยวกับการละเมิดนโยบายที่ควรดู
ของจริงครับ
รับออบเจ็กต์และสถิติประสิทธิภาพ
GoogleAdsService เป็นแท็กเดี่ยวแบบรวม
บริการสำหรับเรียกออบเจ็กต์และสถิติประสิทธิภาพ
คำขอ Search และ SearchStream ทั้งหมดสำหรับ GoogleAdsService ต้องใช้การค้นหาที่ระบุทรัพยากรเพื่อ
แอตทริบิวต์ทรัพยากรและเมตริกประสิทธิภาพที่จะดึงข้อมูล
ใช้เพื่อกรองคำขอ และกลุ่มที่จะใช้เพื่อ
แจกแจงสถิติประสิทธิภาพ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับรูปแบบคำค้นหา
โปรดดูคำแนะนำเกี่ยวกับภาษาของคำค้นหาของ Google Ads
เรียกดูข้อมูลเมตา
GoogleAdsFieldService เรียกข้อมูล
ข้อมูลเมตาเกี่ยวกับทรัพยากรใน Google Ads API เช่น แอตทริบิวต์ที่พร้อมใช้งานสำหรับ
แหล่งข้อมูลและประเภทข้อมูล
บริการนี้จะให้ข้อมูลที่จำเป็นในการสร้างข้อความค้นหาเพื่อ
GoogleAdsService เพื่อความสะดวก ฟิลด์
แสดงข้อมูลโดย
GoogleAdsFieldService พร้อมให้ใช้งานแล้ว
ในเอกสารอ้างอิงช่อง