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