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