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 HTTP POST
đế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 mà không có mã nhận dạng tài nguyên theo sau.
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 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 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 theo sau 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
. Lần lượt, mỗi toán tử có thể là một trong các phép sau: create
, update
hoặc remove
. Đây là những thao tác biến đổi duy nhất có thể thực hiện.
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ướ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.
Các thao tác trong một yêu cầu API được thực thi dưới dạng một tập hợp hành động theo mặc định, 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 có 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 về việc thay đổi để 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 ra các thực thể mới và phải bao gồm JSON đầy đủ đại diện cho tài nguyên bạn định tạo.
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 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ó bản trình bày JSON được định dạng đầy đủ của một đối tượng (chẳng hạn 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 sửa đổi trong updateMask
và gửi toàn bộ đối tượng JSON.
Ví dụ bên dưới sẽ thay đổi name
và status
của một chiến dịch hiện tại có resourceName
cho sẵn.
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
Các thao tác sẽ 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" } ] }