วิดีโอ: ดูการบรรยายเรื่องบริการและแหล่งข้อมูลจากเวิร์กช็อปปี 2019
คู่มือนี้จะแนะนำคอมโพเนนต์หลักที่ประกอบกันเป็น Google Ads API Google Ads API ประกอบด้วยทรัพยากรและบริการ ทรัพยากรแสดงถึงเอนทิตี Google Ads ขณะที่บริการจะดึงข้อมูลและแก้ไขเอนทิตี Google Ads
ลำดับชั้นของออบเจ็กต์
บัญชี Google Ads จะดูเป็นแบบลำดับชั้นของออบเจ็กต์ได้
ทรัพยากรระดับบนสุดของบัญชีคือ ลูกค้า
ลูกค้าแต่ละรายมีแคมเปญที่ใช้งานอยู่อย่างน้อย 1 รายการ
แต่ละแคมเปญประกอบด้วยกลุ่มโฆษณาอย่างน้อย 1 กลุ่ม ซึ่งใช้เพื่อจัดกลุ่มโฆษณาไว้ในคอลเล็กชันที่เหมาะสม
โฆษณาในกลุ่มโฆษณาแสดงถึงโฆษณาที่คุณกำลัง ใช้งานอยู่ กลุ่มโฆษณาแต่ละกลุ่มมีโฆษณาในกลุ่มโฆษณาอย่างน้อย 1 รายการ ยกเว้น App Campaign ซึ่งมีโฆษณาในกลุ่มโฆษณาได้เพียง 1 รายการต่อกลุ่มโฆษณา
คุณจะแนบ AdGroupCriterion หรือ CampaignCriterion อย่างน้อย 1 รายการไว้ในกลุ่มโฆษณาหรือแคมเปญได้ เมตริกเหล่านี้เป็นเกณฑ์ที่กำหนดวิธีที่ระบบจะเรียกให้โฆษณาแสดง
มีประเภทเกณฑ์หลายประเภท เช่น คีย์เวิร์ด ช่วงอายุ และสถานที่ตั้ง เกณฑ์ที่กำหนดในระดับแคมเปญจะมีผลต่อทรัพยากรอื่นๆ ทั้งหมดภายในแคมเปญ คุณยังสามารถระบุงบประมาณและวันที่ของทั้งแคมเปญได้ด้วย
สุดท้าย คุณแนบส่วนขยายที่ระดับบัญชี แคมเปญ หรือกลุ่มโฆษณาได้ ส่วนขยายให้คุณสามารถให้ข้อมูลเพิ่มเติมแก่โฆษณา เช่น หมายเลขโทรศัพท์ ที่อยู่ หรือการโปรโมต
แหล่งข้อมูล
ทรัพยากรจะแสดงถึงเอนทิตีภายในบัญชี Google Ads Campaign และ AdGroup เป็นตัวอย่างทรัพยากร 2 รายการ
รหัสออบเจ็กต์
ออบเจ็กต์ทั้งหมดใน Google Ads จะระบุโดยใช้รหัสของออบเจ็กต์นั้น รหัสบางรหัสจะไม่ซ้ำกันทั่วโลกในบัญชี Google Ads ทั้งหมด ในขณะที่รหัสบางรหัสจะไม่ซ้ำกันภายในขอบเขตที่จำกัดเท่านั้น
| รหัสออบเจ็กต์ | ขอบเขตของความเป็นเอกลักษณ์ | ไม่เหมือนใคร |
|---|---|---|
| รหัสงบประมาณ | ประเทศทั่วโลก | ได้ |
| รหัสแคมเปญ | ประเทศทั่วโลก | ได้ |
| รหัส AdGroup | ประเทศทั่วโลก | ได้ |
| รหัสโฆษณา | กลุ่มโฆษณา | ไม่ แต่คู่ (AdGroupId, AdId) ไม่ซ้ำกันทั่วโลก |
| รหัสเกณฑ์ของกลุ่มโฆษณา | กลุ่มโฆษณา | ไม่ แต่คู่ (AdGroupId, CriterionId) ไม่ซ้ำกันทั่วโลก |
| รหัสเกณฑ์แคมเปญ | แคมเปญ | ไม่ แต่คู่ (CampaignId, CriterionId) ไม่ซ้ำกันทั่วโลก |
| ส่วนขยายโฆษณา | แคมเปญ | ไม่ แต่คู่ (CampaignId, AdExtensionId) ไม่ซ้ำกันทั่วโลก |
| รหัสฟีด | ประเทศทั่วโลก | ได้ |
| รหัสรายการฟีด | ประเทศทั่วโลก | ได้ |
| รหัสแอตทริบิวต์ฟีด | ฟีด | ไม่ได้ |
| รหัสการแมปฟีด | ประเทศทั่วโลก | ได้ |
| รหัสป้ายกำกับ | ประเทศทั่วโลก | ได้ |
| รหัสรายการผู้ใช้ | ประเทศทั่วโลก | ได้ |
กฎรหัสเหล่านี้จะมีประโยชน์เมื่อออกแบบพื้นที่เก็บข้อมูลในเครื่องสำหรับออบเจ็กต์ 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 อินสแตนซ์ โปรดดูการเปลี่ยนและการตรวจสอบออบเจ็กต์สำหรับการสนทนาโดยละเอียดเกี่ยวกับการดำเนินการ
การเปลี่ยนรูปแบบพร้อมกัน
ออบเจ็กต์ 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 อาจเผยให้เห็นการละเมิดใดๆ ที่เกิดขึ้น ดูตัวอย่างโค้ดสำหรับการจัดการข้อผิดพลาดการละเมิดนโยบายเพื่อดูการทำงาน
รับออบเจ็กต์และสถิติประสิทธิภาพ
GoogleAdsService เป็นบริการแบบรวมรายการเดียวสำหรับการเรียกข้อมูลออบเจ็กต์และสถิติประสิทธิภาพ
คำขอ Search และ SearchStream ทั้งหมดสำหรับ GoogleAdsService ต้องใช้การค้นหาที่ระบุทรัพยากรที่จะค้นหา แอตทริบิวต์ทรัพยากรและเมตริกประสิทธิภาพที่จะดึงข้อมูล การคาดการณ์ที่จะใช้สำหรับการกรองคำขอ และกลุ่มที่จะใช้เพื่อแจกแจงสถิติประสิทธิภาพเพิ่มเติม ดูข้อมูลเพิ่มเติมเกี่ยวกับรูปแบบคำค้นหาได้ในคำแนะนำเกี่ยวกับภาษาของคำค้นหาของ Google Ads
เรียกดูข้อมูลเมตา
GoogleAdsFieldService จะดึงข้อมูลเมตาเกี่ยวกับทรัพยากรใน Google Ads API เช่น แอตทริบิวต์ที่พร้อมใช้งานสำหรับทรัพยากรและประเภทข้อมูล
บริการนี้ให้ข้อมูลที่จําเป็นในการสร้างการค้นหาไปยัง GoogleAdsService เพื่อความสะดวก คุณสามารถดูข้อมูลที่ GoogleAdsFieldService ส่งคืนได้ในเอกสารอ้างอิงช่อง