โครงสร้าง API

ondemand_video วิดีโอ: ดูการบรรยายเรื่องบริการและแหล่งข้อมูลจากเวิร์กช็อปปี 2019

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

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

บัญชี Google Ads จะดูเป็นแบบลำดับชั้นของออบเจ็กต์ได้

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

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

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

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

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

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

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

แหล่งข้อมูล

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

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

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

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

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

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

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

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

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

เรียกดูข้อมูลเมตา

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

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