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