โครงสร้าง API

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

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

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

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

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

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

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

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

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

ประเภทเกณฑ์มีอยู่หลายประเภท เช่น คีย์เวิร์ด ช่วงอายุ และสถานที่ เกณฑ์ที่กำหนดไว้ที่ระดับแคมเปญ จะส่งผลต่อทรัพยากรอื่นๆ ทั้งหมดภายในแคมเปญ นอกจากนี้ คุณยังระบุ งบประมาณ รวมถึงวันที่และเวลาเริ่มต้นและสิ้นสุดของแคมเปญ หรือของ โฆษณาแต่ละรายการได้โดยใช้ 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 รายการ ดูรายละเอียดการดำเนินการได้ที่ ออบเจ็กต์การเปลี่ยนแปลง

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

แหล่งที่มามากกว่า 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 โดยค่าเริ่มต้น (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 แสดงจะอยู่ในเอกสารประกอบอ้างอิงฟิลด์ด้วย