Thay đổi

Hầu hết các tài nguyên đều được sửa đổi (tạo, cập nhật hoặc xoá) bằng phương thức Mutate. Phương thức Mutate được gọi dưới dạng POST HTTP đến một URL dành riêng cho tài nguyên khớp với mẫu tên tài nguyên, không có mã nhận dạng tài nguyên ở cuối. Thay vào đó, giá trị nhận dạng của các tài nguyên cần thay đổi sẽ được gửi trong phần nội dung của yêu cầu JSON. Điều này cho phép bạn gửi một lệnh gọi API duy nhất chứa nhiều thao tác trên các tài nguyên khác nhau.

Ví dụ: tên tài nguyên của chiến dịch sử dụng định dạng sau:

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

Để lấy URL dùng cho các chiến dịch đột biến, hãy bỏ qua mã tài nguyên ở cuối và thêm :mutate:

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

Thông báo Mutate chứa một đối tượng JSON cấp cao nhất có mảng operations có thể chứa nhiều đối tượng operation. Đến lượt mỗi thao tác có thể là một trong các thao tác sau: create, update hoặc remove. Đây là các thao tác biến đổi duy nhất có thể có.

POST /v20/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": [
    ...
  ]
}

Hầu hết các dịch vụ đều hỗ trợ hàng nghìn thao tác trong một lệnh gọi API. Hướng dẫn Giới hạn hệ thống ghi lại các giới hạn về kích thước yêu cầu.

Theo mặc định, các thao tác trong một yêu cầu API duy nhất sẽ được thực thi dưới dạng một nhóm hành động, tức là tất cả các thao tác đều thành công cùng nhau hoặc toàn bộ lô sẽ không thành công nếu bất kỳ thao tác nào không thành công. Một số dịch vụ hỗ trợ thuộc tính partialFailure để thay đổi hành vi này. Hãy xem phần Tài nguyên biến đổi để biết thêm thông tin chi tiết về ngữ nghĩa của thao tác biến đổi.

Tạo

Các thao tác tạo sẽ tạo ra các thực thể mới và phải bao gồm một bản trình bày JSON đầy đủ về tài nguyên mà bạn dự định tạo.

POST /v20/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": {}
      }
    }
  ]
}

Cập nhật

Các thao tác cập nhật sẽ thực hiện các bản cập nhật thưa thớt cho một tài nguyên hiện có. Bạn chỉ cần chỉ định các trường mà bạn muốn sửa đổi.

Để chỉ định các trường mà bạn muốn cập nhật, hãy đặt thuộc tính updateMask thành danh sách tên trường được phân tách bằng dấu phẩy. Điều này đặc biệt hữu ích nếu bạn đã có một bản trình bày JSON hoàn chỉnh của một đối tượng (ví dụ: do một lệnh gọi API trước đó trả về), nhưng chỉ muốn thay đổi một số trường nhất định. Thay vì cắt tỉa đối tượng JSON, bạn chỉ cần liệt kê tên trường cần sửa đổi trong updateMask và gửi toàn bộ đối tượng JSON.

Ví dụ dưới đây thay đổi name và status của một chiến dịch hiện có có resourceName đã cho.

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

Xóa

Các thao tác xoá sẽ xoá một đối tượng một cách hiệu quả, đặt trạng thái Google Ads của đối tượng đó thành REMOVED. Bạn chỉ cần cung cấp resourceName cần xoá.

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