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