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