กลายพันธุ์

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

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

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

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

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

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

POST /v25/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 /v25/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 ก่อนหน้า) แต่ต้องการเปลี่ยนเฉพาะบางช่อง คุณเพียงแค่ระบุชื่อช่องที่จะแก้ไขใน updateMask แล้วส่งออบเจ็กต์ JSON ทั้งหมดแทนที่จะตัดออบเจ็กต์ JSON

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

POST /v25/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 /v25/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"
    }
  ]
}