เปลี่ยนวัตถุ

ดังที่ได้กล่าวไว้ในคู่มือโครงสร้าง API ทรัพยากรระดับบนสุดแต่ละรายการใน Google Ads API มีบริการที่เฉพาะเจาะจงประเภททรัพยากรที่เกี่ยวข้อง ซึ่งรองรับการแก้ไขอินสแตนซ์ของทรัพยากร นอกจากนี้ คุณยังใช้ GoogleAdsService.Mutate เพื่อเปลี่ยนประเภททรัพยากรหลายรายการพร้อมกันในคำขอเดียวได้ด้วย

คู่มือนี้ใช้ CampaignService เพื่อแสดงการแก้ไขออบเจ็กต์ Campaign แต่แนวคิดเดียวกันนี้ใช้ได้กับบริการอื่นๆ ทั้งหมดที่เฉพาะเจาะจงประเภททรัพยากร

คำขอเปลี่ยนแปลง

บริการเฉพาะประเภททรัพยากรแต่ละรายการมีเมธอด mutate ที่ยอมรับคำขอ mutate คำขอนี้ประกอบด้วย

• customer_id (หรือ customerId ใน URL ของ REST)
• คอลเล็กชันของ operations
• การตั้งค่าการดำเนินการที่ไม่บังคับ เช่น partial_failure, validate_only และ response_content_type (ซึ่งกำหนดว่าจะแสดงทรัพยากรที่เปลี่ยนแปลงได้หรือ เฉพาะชื่อทรัพยากรหลังจากการเปลี่ยนแปลง)

ตัวอย่างเช่น เมธอด MutateCampaigns ของ CampaignService รับ MutateCampaignsRequest ซึ่งประกอบด้วย ข้อมูลต่อไปนี้

• A customer_id
• คอลเล็กชันของออบเจ็กต์ CampaignOperation รายการ (operations)
• การตั้งค่าการดำเนินการที่ไม่บังคับ (partial_failure, validate_only และ response_content_type ซึ่งระบุประเภทคำตอบที่ต้องการ)

การดำเนินการ

ออบเจ็กต์การดำเนินการ เช่น CampaignOperation ช่วยให้คุณระบุการดำเนินการ ที่ต้องการทำกับทรัพยากรเดียวได้โดยการตั้งค่าฟิลด์ operation ฟิลด์นี้คือoneofฟิลด์ซึ่งประกอบด้วยแอตทริบิวต์ต่อไปนี้

create

สร้างอินสแตนซ์ใหม่ของทรัพยากร

update

อัปเดตแหล่งข้อมูลให้ตรงกับแอตทริบิวต์ของแหล่งข้อมูล update เมื่อตั้งค่าฟิลด์นี้ คุณต้องตั้งค่า update_mask ของการดำเนินการด้วย ซึ่งจะ บอก Google Ads API ว่าจะแก้ไขแอตทริบิวต์ใดในระหว่างการดำเนินการอัปเดต ไลบรารีของไคลเอ็นต์แต่ละรายการจะมีเครื่องมือฟิลด์มาสก์หรือเมธอดตัวช่วย ที่สร้าง update_mask ให้คุณ

remove

นำทรัพยากรที่ระบุโดยสตริงชื่อทรัพยากรออก (เช่น customers/1234567890/campaigns/987654321)

เนื่องจากฟิลด์ operation เป็นฟิลด์ oneof คุณจึงใช้การดำเนินการเดียวเพื่อแก้ไขออบเจ็กต์หลายรายการไม่ได้ เช่น หากต้องการสร้างแคมเปญ 1 รายการและนําแคมเปญอื่นออก ให้เพิ่มอินสแตนซ์ 2 รายการของ CampaignOperation ลงในคําขอ โดยรายการหนึ่งมี create ตั้งค่าไว้ และอีกรายการหนึ่งมี remove ตั้งค่าไว้

การทำงานเป็นแบตช์

แม้ว่าการดำเนินการเดียวจะสร้าง อัปเดต หรือนำทรัพยากรเดียวออกได้เท่านั้น แต่คำขอเปลี่ยนแปลงเดียวอาจมีการดำเนินการหลายอย่าง คุณควร รวมการดำเนินการเป็นคำขอเปลี่ยนแปลงข้อมูลในเซิร์ฟเวอร์รายการเดียวแทนที่จะส่งคำขอเปลี่ยนแปลงข้อมูลในเซิร์ฟเวอร์หลายรายการ ซึ่งแต่ละรายการมีการดำเนินการเดียว

เช่น หากต้องการสร้างแคมเปญ 10 รายการ คุณควรส่ง single MutateCampaignsRequest ที่มีออบเจ็กต์ CampaignOperation 10 รายการ หากต้องการจัดกลุ่ม การดำเนินการในทรัพยากรประเภทต่างๆ ไว้ในคำขอเดียว ให้ใช้ GoogleAdsService.Mutate หรือ ทรัพยากรที่เปลี่ยนแปลง

การตอบกลับการเปลี่ยนแปลง

สิ่งที่แสดงในการตอบกลับจะขึ้นอยู่กับสิ่งที่ส่งในฟิลด์ response_content_type ของคำขอเปลี่ยนแปลงข้อมูลในเซิร์ฟเวอร์ เช่น หากระบุ MUTABLE_RESOURCE การตอบกลับจะมีทั้ง resource_name ของทรัพยากรและฟิลด์ที่เปลี่ยนแปลงได้ของแคมเปญใน campaign โดยค่าเริ่มต้น (RESOURCE_NAME_ONLY) ระบบจะป้อนข้อมูลเฉพาะ resource_name ในแต่ละMutateCampaignResult

ข้อผิดพลาดในการเปลี่ยนแปลง

โดยค่าเริ่มต้น (partial_failure = false) การดำเนินการในคำขอเปลี่ยนแปลงข้อมูลในเซิร์ฟเวอร์จะ มีผลกับบัญชี Google Ads ก็ต่อเมื่อการดำเนินการทุกรายการในคำขอ สําเร็จ หากการดำเนินการใดล้มเหลว ระบบจะย้อนกลับคำขอทั้งหมด สำหรับคำขอ mutate ที่รองรับความล้มเหลวบางส่วน (คำขอที่มีฟิลด์ partial_failure ใน ข้อความคำขอ) การตั้งค่า partial_failure = true จะส่งการดำเนินการที่ถูกต้อง ในขณะที่การดำเนินการที่ล้มเหลวจะแสดงข้อผิดพลาดเฉพาะการดำเนินการในการตอบกลับ ฟิลด์ partial_failure_error ดูรายละเอียดเกี่ยวกับการจัดการข้อผิดพลาดได้ในคำแนะนำเกี่ยวกับความล้มเหลวบางส่วนและคำแนะนำเกี่ยวกับข้อผิดพลาดที่พบบ่อย

ติดตามการเปลี่ยนแปลง

หากต้องการติดตามการเปลี่ยนแปลงที่เกิดขึ้นกับออบเจ็กต์ในบัญชี Google Ads หรือเรียกข้อมูล สถานะปัจจุบันของออบเจ็กต์ คุณสามารถใช้ทรัพยากร change_status และ change_event ได้

• change_status จะแสดงข้อมูลสรุปของทรัพยากรที่มีการเปลี่ยนแปลงภายในระยะเวลาที่กำหนด
• change_event จะแสดงประวัติการเปลี่ยนแปลงโดยละเอียด รวมถึงค่าเก่าและค่าใหม่ของช่องที่เปลี่ยนแปลง

หากต้องการค้นหาแหล่งข้อมูลเหล่านี้ ให้ใช้วิธี GoogleAdsService.SearchStream หรือ GoogleAdsService.Search อ่านเพิ่มเติมเกี่ยวกับการสตรีมรายงาน โดยใช้ GoogleAdsService