โครงสร้าง API

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

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