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

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

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

คำขอเปลี่ยนแปลงข้อมูลในเซิร์ฟเวอร์

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

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

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

• 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 รายการและนําแคมเปญอื่นออก ให้เพิ่ม CampaignOperation 2 อินสแตนซ์ลงในคําขอ โดยอินสแตนซ์หนึ่งตั้งค่าเป็น create และอีกอินสแตนซ์หนึ่งตั้งค่าเป็น remove

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

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

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

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

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

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

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

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

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

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

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