Thay đổi

Lưu ý: Hãy xem phần Thay đổi trong các ví dụ đi kèm để biết thêm ví dụ đầy đủ.

Hầu hết các tài nguyên đượ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 đó, mã 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 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 có định dạng sau:

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

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

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

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

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

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 về 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 được thực thi dưới dạng một nhóm thao tác, nghĩa là tất cả các thao tác đều thành công hoặc toàn bộ lô đều không thành công nếu một thao tác 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 Thay đổi tài nguyên để biết thêm thông tin chi tiết về ngữ nghĩa của thao tác thay đổi.

Tạo

Thao tác tạo sẽ tạo các thực thể mới và phải bao gồm nội dung đại diện JSON đầy đủ của tài nguyên mà bạn dự định tạo.

Lưu ý quan trọng: Thao tác tạo không chỉ định resourceName hoặc mã nhận dạng. Khi lệnh gọi API thành công, phản hồi sẽ bao gồm resourceName được tạo cho đối tượng mới tạo.

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

Cập nhật

Thao tác cập nhật thực hiện các 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 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 bớt đối tượng JSON, bạn chỉ cần liệt kê tên trường cần chỉnh sửa trong updateMask và gửi toàn bộ đối tượng JSON.

Lưu ý quan trọng: update_mask là một trường chuẩn được dùng trên các API của Google để hỗ trợ việc cập nhật một phần trên một tài nguyên nhất định. Hãy xem tài liệu tham khảo FieldMask để biết đầy đủ thông tin chi tiết.

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

Xóa

Thao tác xoá sẽ xoá một đối tượng một cách hiệu quả, đặt trạng thái của đối tượng đó trên Google Ads thành REMOVED. Chỉ cần resourceName cần xoá là bắt buộc.

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"
    }
  ]
}