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 một 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 để thay đổi chiến dịch, hãy bỏ qua mã nhận dạng tài nguyên ở cuối và nối :mutate:
https://googleads.googleapis.com/v16/customers/CUSTOMER_ID/campaigns:mutate
Thông báo Mutate chứa đố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. Lần lượt mỗi toán tử có thể là một trong: 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 /v16/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. Phần Giới hạn hệ thống hướng dẫn 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 nhóm thao tác theo mặc định, nghĩa 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 bị lỗi. 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 chuyển đổi để biết thêm thông tin chi tiết về ngữ nghĩa hoạt động thay đổ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 đại diện JSON đầy đủ của tài nguyên bạn định tạo.
POST /v16/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 hoạt động cập nhật thực hiện việc cập nhật thưa thớt đối với một tài nguyên hiện có. Bạn chỉ cần chỉ định các trường 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 các 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 đối tượng biểu diễn JSON ở dạng đầy đủ (ví dụ: được trả về bởi lệnh gọi API trước đó), nhưng chỉ muốn thay đổi một số trường nhất định.
Thay vì cắt giảm đối tượng JSON, bạn có thể chỉ cần 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 có có
resourceName nhất định.
POST /v16/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
Xóa các hoạt động sẽ xóa 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 xoá resourceName.
POST /v16/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"
}
]
}