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 Mutate . Phương thức Mutate được gọi dưới dạng HTTP POST đến một tài nguyên cụ thể URL khớp với mẫu tên tài nguyên không có mã tài nguyên theo sau. Mã của những tài nguyên cần thay đổi sẽ được gửi trong yêu cầu JSON nội dung. Nhờ vậy, bạn có thể gửi một lệnh gọi API 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 thay đổi, hãy bỏ qua mã tài nguyên ở cuối và thêm :mutate:

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

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

POST /v17/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ệ thống Các giới hạn trong tài liệu hướng dẫn về kích thước yêu cầu.

Các hoạt động trong một yêu cầu API được thực thi dưới dạng một tập hợp các hành động theo mặc định, nghĩa là tất cả đều thành công cùng nhau hoặc toàn bộ lô sẽ bị lỗi 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. Xem phần Tài nguyên ghép nối để biết thêm thông tin chi tiết về ngữ nghĩa thao tác biến đổi.

Tạo

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

POST /v17/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 thực hiện việ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 bạn muốn sửa đổi.

Để chỉ định những 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ó bản trình bày JSON được định dạng đầy đủ của một đối tượng (ví dụ: như được 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ó thể liệt kê các tên trường cần được sửa đổi trong updateMask và gửi toàn bộ đối tượng JSON.

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

POST /v17/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

Loại bỏ các thao tác giúp 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. Bạn chỉ cần xoá resourceName.

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