Hầu hết 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 POST HTTP cho một URL dành riêng cho tài nguyên khớp với mẫu tên tài nguyên, không có mã tài nguyên ở cuối.
Thay vào đó, giá trị nhận dạng của các tài nguyên cần được thay đổi sẽ được gửi trong phần 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 duy nhất 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ã tài nguyên ở cuối và thêm :mutate:
https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/campaigns:mutate
Thông báo Mutate chứa một đối tượng JSON cấp cao nhất có mảng operations có thể chứa nhiều đối tượng operation. Mỗi thao tác có thể là một trong các thao tác sau: create, update hoặc remove. Đây là những thao tác thay đổi duy nhất có thể thực hiện.
POST /v26/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_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 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.
Theo mặc định, 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 các hành động, nghĩa là tất cả các thao tác đều thành công 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. Hãy xem bài viết Thay đổi tài nguyên để 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 một bản trình bày JSON đầy đủ của tài nguyên mà bạn định tạo.
POST /v26/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_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
Thao tác cập nhật sẽ thực hiện các bản 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 mà 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 được phân tách bằng dấu phẩy của tên trường. Điều này đặc biệt hữu ích nếu bạn đã có một bản trình bày JSON hoàn chỉnh của một đối tượng (ví dụ: do một 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 tỉa đối tượng JSON, bạn chỉ cần liệt kê tên trường cần sửa đổi trong updateMask và gửi toàn bộ đối tượng JSON.
Ví dụ sau đây thay đổi name và status của một chiến dịch hiện có
có resourceName đã cho.
POST /v26/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN { "operations": [ { "updateMask": "name,status", "update": { "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID", "name": "My renamed campaign", "status": "PAUSED", } } ] }
Xoá
Thao tác xoá sẽ 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 /v26/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN { "operations": [ { "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID" } ] }