โครงสร้าง API

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

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

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

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

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

• แต่ละแคมเปญประกอบด้วยกลุ่มโฆษณาอย่างน้อย 1 กลุ่ม ซึ่งใช้เพื่อจัดกลุ่มโฆษณาเป็นคอลเล็กชันที่สมเหตุสมผล

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

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

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

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

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

แหล่งข้อมูล

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

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

ออบเจ็กต์ทุกรายการใน 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 ต้องการอินสแตนซ์ CampaignOperation อย่างน้อย 1 รายการ ดูรายละเอียดเกี่ยวกับการดำเนินการได้ที่ออบเจ็กต์การเปลี่ยนแปลง

การเปลี่ยนแปลงพร้อมกัน

ออบเจ็กต์ 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 คำขอได้รับการตรวจสอบอย่างสมบูรณ์ราวกับว่าจะมีการดำเนินการ แต่ระบบจะข้ามการดำเนินการขั้นสุดท้าย หากไม่พบข้อผิดพลาด ระบบจะแสดงการตอบกลับโดยไม่มีผลลัพธ์ที่เปลี่ยนแปลง (results ว่างเปล่า) หากการตรวจสอบไม่สำเร็จ คำขอจะล้มเหลวโดยมีข้อผิดพลาด RPC GoogleAdsFailure โดยค่าเริ่มต้น (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 แสดงผลยังมีอยู่ในเอกสารอ้างอิงฟิลด์ด้วย