โครงสร้าง API

คู่มือนี้จะแนะนำคอมโพเนนต์หลักๆ ที่ประกอบกันเป็น Google Ads API โดย Google Ads API ประกอบด้วย ทรัพยากรและ บริการ ทรัพยากรแสดงถึงเอนทิตีของ Google Ads ขณะที่บริการจะดึงและจัดการเอนทิตีของ Google Ads

ลำดับชั้นของออบเจ็กต์

คุณสามารถดูบัญชี Google Ads เป็นลำดับชั้นของออบเจ็กต์ได้

• ทรัพยากรระดับบนสุดของบัญชีคือ ลูกค้า

• ลูกค้าแต่ละรายมีแคมเปญที่ทำงานอยู่อย่างน้อย 1 รายการ campaigns

• แต่ละแคมเปญมีกลุ่มโฆษณาอย่างน้อย 1 กลุ่ม ซึ่งใช้ จัดกลุ่มโฆษณาเป็นคอลเล็กชันเชิงตรรกะ

• โฆษณาของ กลุ่มโฆษณา แสดงถึงโฆษณาที่คุณ แสดงในกลุ่มโฆษณา กลุ่มโฆษณาแต่ละกลุ่มมีโฆษณาของกลุ่มโฆษณาอย่างน้อย 1 รายการ ยกเว้น App Campaign ซึ่งมีโฆษณาของกลุ่มโฆษณาได้เพียงรายการเดียวต่อกลุ่มโฆษณา

แคมเปญ Performance Max ใช้ โครงสร้างที่แตกต่างจากแคมเปญประเภทอื่นๆ โดยแคมเปญ Performance Max จะมีกลุ่มชิ้นงานแทนกลุ่มโฆษณาและโฆษณาของกลุ่มโฆษณา คุณ ลิงก์ชิ้นงานครีเอทีฟโฆษณากับกลุ่มชิ้นงานโดยใช้ AssetGroupAsset และแนบสัญญาณกลุ่มเป้าหมายหรือธีมการค้นหา โดยใช้ AssetGroupSignal

คุณสามารถแนบทรัพยากร AdGroupCriterion หรือ CampaignCriterion อย่างน้อย 1 รายการกับกลุ่มโฆษณาหรือแคมเปญ ซึ่งแสดงถึงเกณฑ์ที่กำหนดวิธีเรียกให้แสดงโฆษณา

เกณฑ์มีหลายประเภท เช่น คีย์เวิร์ด ช่วงอายุ และสถานที่ตั้ง เกณฑ์ที่กำหนดไว้ที่ระดับแคมเปญจะส่งผลต่อทรัพยากรอื่นๆ ทั้งหมดภายในแคมเปญ นอกจากนี้ คุณยังระบุงบประมาณ รวมถึงวันที่และเวลาเริ่มต้นและสิ้นสุดของแคมเปญ หรือของโฆษณาเดี่ยวแต่ละรายการโดยใช้ AdGroupAd.start_date_time และ AdGroupAd.end_date_time ได้ด้วย

สุดท้าย คุณสามารถแนบชิ้นงานที่ระดับบัญชี แคมเปญ กลุ่มโฆษณา หรือกลุ่มชิ้นงาน ชิ้นงานช่วยให้คุณให้ข้อมูลเพิ่มเติมแก่โฆษณา เช่น หมายเลขโทรศัพท์ ที่อยู่ หรือโปรโมชัน ดูภาพรวมของชิ้นงาน

แหล่งข้อมูล

ทรัพยากรแสดงถึงเอนทิตีภายในบัญชี Google Ads Campaign และ AdGroup เป็น ตัวอย่างของทรัพยากร

รหัสออบเจ็กต์

ออบเจ็กต์ทุกรายการใน Google Ads จะระบุด้วยรหัสของตัวเอง รหัสบางรายการไม่ซ้ำกันทั่วโลกในบัญชี Google Ads ทั้งหมด ขณะที่รหัสอื่นๆ จะไม่ซ้ำกันเฉพาะภายในขอบเขตที่จำกัด

กฎรหัสเหล่านี้มีประโยชน์เมื่อออกแบบพื้นที่เก็บข้อมูลในเครื่องสำหรับออบเจ็กต์ Google Ads

ออบเจ็กต์บางรายการใช้ได้กับเอนทิตีหลายประเภท ในกรณีดังกล่าว ออบเจ็กต์จะมีช่อง type ที่อธิบายเนื้อหาของออบเจ็กต์ ตัวอย่างเช่น AdGroupAd สามารถอ้างอิงถึงออบเจ็กต์ เช่น โฆษณา Search ที่ปรับเปลี่ยนตามบริบท โฆษณาโรงแรม หรือโฆษณา Demand Gen คุณเข้าถึงค่านี้ได้ ผ่านช่อง AdGroupAd.ad.type และระบบจะแสดง ค่าใน Enum AdType โปรดทราบว่า ความสามารถในการเปลี่ยนแปลงได้อาจแตกต่างกันไปตามเวอร์ชัน (เช่น VideoResponsiveAdInfo ใน Ad เปลี่ยนแปลงได้ใน v24 ขึ้นไป)

ชื่อทรัพยากร

ทรัพยากรแต่ละรายการจะระบุด้วยสตริง resource_name ที่ไม่ซ้ำกัน ซึ่งจะรวมทรัพยากรและทรัพยากรระดับบนเข้าด้วยกันเป็นเส้นทาง ตัวอย่างเช่น ชื่อทรัพยากรของแคมเปญจะมีรูปแบบดังนี้

customers/customer_id/campaigns/campaign_id

ดังนั้น สำหรับแคมเปญที่มีรหัส 987654 ในบัญชี Google Ads ที่มีรหัสลูกค้า 1234567 resource_name จะเป็นดังนี้

customers/1234567/campaigns/987654

บริการ

บริการช่วยให้คุณดึงและแก้ไขเอนทิตีของ Google Ads ได้ บริการมี 3 ประเภท ได้แก่ บริการแก้ไข บริการดึงออบเจ็กต์และสถิติ และบริการดึงข้อมูลเมตา

แก้ไข (เปลี่ยนแปลง) ออบเจ็กต์

บริการเฉพาะทรัพยากรจะแก้ไขอินสแตนซ์ของประเภททรัพยากรที่เชื่อมโยงโดยใช้คำขอ mutate นอกจากนี้ คุณยังใช้ GoogleAdsService.Mutate เพื่อทำการเปลี่ยนแปลงแบบอะตอมมิก ในทรัพยากรหลายประเภทในคำขอเดียวได้ (เช่น การสร้าง งบประมาณแคมเปญ แคมเปญ และกลุ่มโฆษณาพร้อมกัน)

ตัวอย่างบริการเฉพาะทรัพยากร

• 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 ระบบจะตรวจสอบคำขออย่างละเอียดราวกับว่ากำลังจะดำเนินการ แต่จะข้ามการดำเนินการขั้นสุดท้าย หากไม่พบข้อผิดพลาด ระบบจะแสดงการตอบกลับโดยไม่มีผลการเปลี่ยนแปลง (results ว่างเปล่า) หากการตรวจสอบล้มเหลว คำขอจะล้มเหลวโดยมีข้อผิดพลาด GoogleAdsFailure RPC error เป็นค่าเริ่มต้น (partial_failure = false) หรือแสดงการตอบกลับปกติโดยมีข้อผิดพลาดเฉพาะการดำเนินการใน partial_failure_error เมื่อ partial_failure = true

validate_only มีประโยชน์อย่างยิ่งในการทดสอบโฆษณาเพื่อดูว่ามีการละเมิดนโยบายที่พบบ่อยหรือไม่ ระบบจะปฏิเสธโฆษณาโดยอัตโนมัติหากโฆษณานั้นละเมิดนโยบาย เช่น มีคำ เครื่องหมายวรรคตอน การใช้อักษรตัวพิมพ์ใหญ่ หรือความยาวที่เฉพาะเจาะจง โฆษณาที่ไม่ดีเพียงรายการเดียวอาจทำให้ชุดโฆษณาทั้งหมดล้มเหลว การทดสอบโฆษณาใหม่ภายในคำขอ validate_only จะเผยให้เห็นการละเมิดดังกล่าว ดูตัวอย่างโค้ดสำหรับการจัดการ ข้อผิดพลาดการละเมิดนโยบายเพื่อดู การทำงานของฟีเจอร์นี้

รับออบเจ็กต์และสถิติประสิทธิภาพ

GoogleAdsService เป็นบริการเดียวแบบครบวงจรสำหรับการดึงออบเจ็กต์และสถิติประสิทธิภาพ

คำขอ Search และ SearchStream ทั้งหมดสำหรับ GoogleAdsService ต้องมีการค้นหาที่ ระบุทรัพยากรที่จะค้นหา แอตทริบิวต์ทรัพยากรและเมตริกประสิทธิภาพที่จะ ดึง ข้อมูลที่ใช้กรองคำขอ และเซกเมนต์ที่จะ ใช้เพื่อแยกย่อยสถิติประสิทธิภาพเพิ่มเติม ดูข้อมูลเพิ่มเติมเกี่ยวกับ รูปแบบการค้นหาได้ที่ คู่มือภาษาการค้นหาของ Google Ads

ดึงข้อมูลเมตา

GoogleAdsFieldService จะดึงข้อมูลเมตาเกี่ยวกับทรัพยากรใน Google Ads API เช่น แอตทริบิวต์ที่ใช้ได้สำหรับทรัพยากรและประเภทข้อมูลของทรัพยากร ดูรายละเอียดเกี่ยวกับการค้นหาบริการนี้ได้ที่คู่มือข้อมูลเมตาของทรัพยากร

บริการนี้ให้ข้อมูลที่จำเป็นในการสร้างการค้นหาสำหรับ GoogleAdsService นอกจากนี้ ข้อมูลที่แสดงผลโดย GoogleAdsFieldService ยังมีอยู่ใน เอกสารประกอบอ้างอิงฟิลด์ด้วย