กลายพันธุ์

ทรัพยากรส่วนใหญ่จะแก้ไข (สร้าง อัปเดต หรือนําออก) โดยใช้Mutateวิธี ระบบจะเรียกใช้เมธอด Mutate เป็น HTTP POST ไปยัง URL ที่เจาะจงทรัพยากรซึ่งตรงกับรูปแบบชื่อทรัพยากร โดยไม่มีรหัสทรัพยากรต่อท้าย ระบบจะส่งรหัสของทรัพยากรที่จะเปลี่ยนแปลงในเนื้อหาคําขอ JSON แทน ซึ่งช่วยให้คุณส่งการเรียก API รายการเดียวที่มีการดำเนินการหลายรายการในทรัพยากรต่างๆ ได้

ตัวอย่างเช่น ชื่อทรัพยากรของแคมเปญจะใช้รูปแบบต่อไปนี้

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

หากต้องการสร้าง URL ที่ใช้สำหรับเปลี่ยนรูปแบบแคมเปญ ให้ละเว้นรหัสทรัพยากรต่อท้ายและใส่ :mutate ต่อท้าย

https://googleads.googleapis.com/v19/customers/CUSTOMER_ID/campaigns:mutate

ข้อความ Mutate มีออบเจ็กต์ JSON ระดับบนสุดที่มีอาร์เรย์ operations ซึ่งอาจมีออบเจ็กต์ operation หลายรายการ การดำเนินการแต่ละรายการอาจเป็น create, update หรือ remove การดำเนินการเปลี่ยนรูปแบบที่เป็นไปได้มีเพียงการดำเนินการเหล่านี้เท่านั้น

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    ...
  ]
}

บริการส่วนใหญ่รองรับการดำเนินการหลายพันรายการในการเรียก API ครั้งเดียว คู่มือขีดจํากัดของระบบจะระบุขีดจํากัดของขนาดคําขอ

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

สร้าง

การดำเนินการสร้างจะสร้างเอนทิตีใหม่และต้องระบุการนําเสนอ JSON แบบเต็มของทรัพยากรที่คุณต้องการสร้าง

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
    "create": {
        "name": "An example campaign",
        "status": "PAUSED",
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/CAMPAIGN_BUDGET_ID",
        "advertisingChannelType": "SEARCH",
        "networkSettings": {
          "targetGoogleSearch": true,
          "targetSearchNetwork": true,
          "targetContentNetwork": true,
          "targetPartnerSearchNetwork": false
        },
        "target_spend": {}
      }
    }
  ]
}

อัปเดต

การดำเนินการอัปเดตจะทำการอัปเดตทรัพยากรที่มีอยู่เป็นระยะๆ คุณเพียงต้องระบุช่องที่ต้องการแก้ไขเท่านั้น

หากต้องการระบุช่องที่ต้องการอัปเดต ให้ตั้งค่าแอตทริบิวต์ updateMask เป็นรายการชื่อช่องที่คั่นด้วยคอมมา ซึ่งจะมีประโยชน์อย่างยิ่งหากคุณมีการแสดงออบเจ็กต์ในรูปแบบ JSON ที่สมบูรณ์อยู่แล้ว (เช่น ข้อมูลที่แสดงผลจากการเรียก API ก่อนหน้านี้) แต่ต้องการเปลี่ยนเฉพาะบางช่อง แทนที่จะตัดออบเจ็กต์ JSON ให้เหลือเฉพาะข้อมูลที่จำเป็น คุณก็แค่ระบุชื่อช่องที่จะแก้ไขใน updateMask แล้วส่งออบเจ็กต์ JSON ทั้งหมดได้

ตัวอย่างด้านล่างจะเปลี่ยน name และ status ของแคมเปญที่มีอยู่ซึ่งมี resourceName ที่กำหนด

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
      "updateMask": "name,status",
      "update": {
        "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID",
        "name": "My renamed campaign",
        "status": "PAUSED",
      }
    }
  ]
}

นำออก

การดำเนินการนําออกจะลบออบเจ็กต์อย่างมีประสิทธิภาพ โดยตั้งค่าสถานะ Google Ads เป็น REMOVED ระบุเฉพาะ resourceName ที่จะนําออก

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
      "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID"
    }
  ]
}