วิดีโอ: ดูการบรรยายเรื่องบริการและแหล่งข้อมูลจากเวิร์กช็อปปี 2019
คู่มือนี้จะแนะนำองค์ประกอบหลักที่ประกอบขึ้นเป็น Google Ads API Google Ads API ประกอบด้วยทรัพยากรและบริการ ทรัพยากรหมายถึงเอนทิตี Google Ads ในขณะที่บริการดึงและจัดการเอนทิตี Google Ads
ลำดับชั้นของออบเจ็กต์
บัญชี Google Ads จะดูเป็นลำดับชั้นของออบเจ็กต์ได้
ทรัพยากรระดับบนสุดของบัญชีคือลูกค้า
ลูกค้าแต่ละรายจะมีแคมเปญที่ใช้งานอยู่อย่างน้อย 1 รายการ
แต่ละแคมเปญจะมีกลุ่มโฆษณาอย่างน้อย 1 กลุ่ม ซึ่งใช้เพื่อจัดกลุ่มโฆษณาเป็นคอลเล็กชันที่สมเหตุสมผล
โฆษณาของกลุ่มโฆษณาแสดงถึงโฆษณาที่คุณใช้งานอยู่ กลุ่มโฆษณาแต่ละกลุ่มมีโฆษณาของกลุ่มโฆษณาอย่างน้อย 1 รายการ ยกเว้น App Campaign ที่มีโฆษณาในกลุ่มโฆษณาได้เพียง 1 รายการต่อกลุ่มโฆษณา
คุณสามารถแนบ AdGroupCriterion หรือ CampaignCriterion อย่างน้อย 1 รายการกับกลุ่มโฆษณาหรือแคมเปญ ข้อมูลเหล่านี้แสดงถึงเกณฑ์ที่กำหนดวิธีเรียกใช้โฆษณา
มีประเภทเกณฑ์มากมาย เช่น คีย์เวิร์ด ช่วงอายุ และสถานที่ตั้ง เกณฑ์ที่กำหนดในระดับแคมเปญ จะส่งผลต่อทรัพยากรอื่นๆ ทั้งหมดภายในแคมเปญนั้น นอกจากนี้ คุณยังสามารถระบุ งบประมาณและวันที่ของทั้งแคมเปญได้ด้วย
สุดท้าย คุณสามารถแนบส่วนขยายที่ระดับบัญชี แคมเปญ หรือกลุ่มโฆษณา ส่วนขยายช่วยให้คุณสามารถให้ข้อมูลเพิ่มเติมกับโฆษณาได้ เช่น หมายเลขโทรศัพท์ ที่อยู่ หรือโปรโมชัน
แหล่งข้อมูล
ทรัพยากรแสดงถึงเอนทิตีภายในบัญชี 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 ควรมีอินสแตนซ์ของ CampaignOperation อย่างน้อย 1 อินสแตนซ์ ดูการเปลี่ยนและตรวจสอบออบเจ็กต์สำหรับการสนทนาโดยละเอียดเกี่ยวกับการดำเนินการ
เปลี่ยนแปลงพร้อมกัน
แก้ไขออบเจ็กต์ Google Ads พร้อมกันในแหล่งที่มามากกว่า 1 รายการไม่ได้ ซึ่งอาจทำให้เกิดข้อผิดพลาดหากคุณมีผู้ใช้หลายคนอัปเดตออบเจ็กต์เดียวกันด้วยแอป หรือในกรณีที่คุณเปลี่ยนแปลงออบเจ็กต์ Google Ads พร้อมกันโดยใช้ชุดข้อความหลายชุด ซึ่งรวมถึงการอัปเดตออบเจ็กต์จากชุดข้อความหลายรายการในแอปพลิเคชันเดียวกันหรือจากแอปพลิเคชันอื่น (เช่น แอปและเซสชัน UI ของ Google Ads พร้อมกัน)
API ไม่ได้ให้วิธีล็อกออบเจ็กต์ก่อนการอัปเดต หากมีแหล่งที่มา 2 แหล่งพยายามเปลี่ยนแปลงออบเจ็กต์พร้อมกัน API จะเพิ่ม DatabaseError.CONCURRENT_MODIFICATION_ERROR
การเปลี่ยนแปลงแบบไม่พร้อมกันกับแบบพร้อมกัน
วิธีการเปลี่ยนแปลงของ Google Ads API เป็นแบบซิงโครนัส การเรียก API จะส่งคืนการตอบกลับหลังจากที่ออบเจ็กต์มีการเปลี่ยนแปลงเท่านั้น ซึ่งทำให้คุณต้องรอการตอบกลับของแต่ละคำขอ แม้ว่าวิธีนี้จะค่อนข้างตรงไปตรงมาในการเขียนโค้ด แต่ก็อาจส่งผลกระทบต่อการจัดสรรภาระงานและทำให้ทรัพยากรสิ้นเปลืองหากกระบวนการถูกบังคับให้รอให้การเรียกใช้เสร็จสิ้น
อีกแนวทางหนึ่งคือการเปลี่ยนรูปแบบออบเจ็กต์แบบไม่พร้อมกันโดยใช้ BatchJobService ซึ่งจะดำเนินการเป็นกลุ่มกับบริการต่างๆ โดยไม่ต้องรอให้ระบบดำเนินการเสร็จสิ้น เมื่อส่งงานแบบกลุ่ม เซิร์ฟเวอร์ Google Ads API จะดำเนินการต่างๆ แบบไม่พร้อมกันซึ่งจะทำให้กระบวนการทำงานอื่นๆ ง่ายขึ้น คุณสามารถตรวจสอบสถานะงานเพื่อดูการทำงานเสร็จเป็นระยะๆ ได้
ดูข้อมูลเพิ่มเติมเกี่ยวกับการประมวลผลแบบไม่พร้อมกันได้ในคู่มือการประมวลผลแบบกลุ่ม
เปลี่ยนแปลงการตรวจสอบ
คำขอเปลี่ยนแปลงส่วนใหญ่สามารถตรวจสอบได้โดยไม่ต้องเรียกใช้ข้อมูลจริง คุณสามารถทดสอบคำขอสำหรับพารามิเตอร์ที่หายไปและค่าฟิลด์ที่ไม่ถูกต้องได้โดยไม่ต้องดำเนินการ
หากต้องการใช้ฟีเจอร์นี้ ให้ตั้งค่าช่องบูลีน validate_only ของคำขอเป็น true จากนั้นคำขอจะได้รับการตรวจสอบอย่างสมบูรณ์ราวกับว่าจะดำเนินการ แต่การดำเนินการขั้นสุดท้ายจะถูกข้ามไป หากไม่พบข้อผิดพลาด ระบบจะแสดงผลการตอบกลับที่ว่างเปล่า หากตรวจสอบไม่สำเร็จ ข้อความแสดงข้อผิดพลาดในการตอบกลับจะระบุจุดที่ไม่สำเร็จ
validate_only มีประโยชน์อย่างยิ่งในการทดสอบโฆษณาที่ละเมิดนโยบายทั่วไป โฆษณาจะถูกปฏิเสธโดยอัตโนมัติหากละเมิดนโยบาย เช่น มีคำ เครื่องหมายวรรคตอน การใช้อักษรตัวพิมพ์ใหญ่ หรือความยาวที่เฉพาะเจาะจง โฆษณาที่ไม่ดีเพียงโฆษณาเดียว
อาจทำให้โฆษณาทั้งกลุ่มล้มเหลวได้ การทดสอบโฆษณาใหม่ภายในคําขอ validate_only สามารถเปิดเผยการละเมิดดังกล่าวได้ ดูตัวอย่างโค้ดสำหรับการจัดการข้อผิดพลาดเกี่ยวกับการละเมิดนโยบายเพื่อดูการทำงานจริง
รับออบเจ็กต์และสถิติประสิทธิภาพ
GoogleAdsService เป็นบริการเดียวที่ผสานรวมเป็นหนึ่งสำหรับการเรียกข้อมูลออบเจ็กต์และสถิติประสิทธิภาพ
คำขอ Search และ SearchStream ทั้งหมดสำหรับ GoogleAdsService ต้องมีการค้นหาที่ระบุทรัพยากรที่จะค้นหา แอตทริบิวต์ของทรัพยากรและเมตริกประสิทธิภาพที่จะดึง คำสั่งเพื่อใช้สำหรับการกรองคำขอ และกลุ่มที่จะใช้ในการแจกแจงสถิติประสิทธิภาพ ดูข้อมูลเพิ่มเติมเกี่ยวกับรูปแบบคำค้นหาได้ในคู่มือภาษาของคำค้นหาของ Google Ads
ดึงข้อมูลเมตา
GoogleAdsFieldService เรียกข้อมูลเมตาเกี่ยวกับทรัพยากรใน Google Ads API เช่น แอตทริบิวต์ที่มีให้สำหรับทรัพยากรและประเภทข้อมูล
บริการนี้จะให้ข้อมูลที่จำเป็นในการสร้างการค้นหาไปยัง GoogleAdsService นอกจากนี้ เพื่อความสะดวก ข้อมูลที่ GoogleAdsFieldService แสดงผลจะอยู่ในเอกสารอ้างอิงของช่องด้วย