Như đã thảo luận trong hướng dẫn về cấu trúc API, mỗi tài nguyên cấp cao nhất trong Google Ads API đều có một dịch vụ tương ứng dành riêng cho loại tài nguyên, hỗ trợ việc sửa đổi các thực thể của tài nguyên. Bạn cũng có thể dùng GoogleAdsService.Mutate để thay đổi nhiều loại tài nguyên một cách riêng lẻ trong một yêu cầu duy nhất.
Hướng dẫn này sử dụng CampaignService để minh hoạ cách sửa đổi các đối tượng Campaign, nhưng các khái niệm tương tự cũng áp dụng cho tất cả các dịch vụ khác dành riêng cho loại tài nguyên.
Yêu cầu thay đổi
Mỗi dịch vụ dành riêng cho loại tài nguyên đều có một phương thức mutate chấp nhận một yêu cầu mutate. Yêu cầu này bao gồm:
customer_id(hoặccustomerIdtrong URL REST)- Bộ sưu tập
operations - Các chế độ cài đặt thực thi không bắt buộc, chẳng hạn như
partial_failure,validate_onlyvàresponse_content_type(xác định xem tài nguyên có thể thay đổi hay chỉ tên tài nguyên được trả về sau khi thay đổi)
Ví dụ: phương thức MutateCampaigns của CampaignService chấp nhận một MutateCampaignsRequest bao gồm:
customer_id- Một tập hợp các đối tượng
CampaignOperation(operations) - Các chế độ cài đặt thực thi không bắt buộc (
partial_failure,validate_onlyvàresponse_content_typecho biết loại phản hồi ưu tiên)
Vận hành
Một đối tượng thao tác như CampaignOperation cho phép bạn chỉ định thao tác mà bạn muốn thực hiện trên một tài nguyên duy nhất bằng cách đặt trường operation của tài nguyên đó.
Trường này là trường oneof bao gồm các thuộc tính sau:
create- Tạo một phiên bản mới của tài nguyên.
update- Cập nhật tài nguyên để khớp với các thuộc tính của tài nguyên
update. Khi đặt trường này, bạn cũng phải đặtupdate_maskcủa thao tác. Trường này cho biết API Google Ads cần sửa đổi những thuộc tính nào trong thao tác cập nhật. Mỗi thư viện ứng dụng đều có một tiện ích mặt nạ trường hoặc phương thức trợ giúp tạoupdate_maskcho bạn. remove- Xoá tài nguyên được chỉ định bằng chuỗi tên tài nguyên (ví dụ:
customers/1234567890/campaigns/987654321).
Vì trường operation là trường oneof, bạn không thể dùng một thao tác duy nhất để sửa đổi nhiều đối tượng. Ví dụ: nếu bạn muốn tạo một chiến dịch và xoá một chiến dịch khác, hãy thêm hai phiên bản của CampaignOperation vào yêu cầu của bạn: một phiên bản có create được đặt và một phiên bản khác có remove được đặt.
Thao tác theo đợt
Mặc dù một thao tác chỉ có thể tạo, cập nhật hoặc xoá một tài nguyên duy nhất, nhưng một yêu cầu thay đổi tài nguyên duy nhất có thể chứa nhiều thao tác. Bạn nên kết hợp các thao tác thành một yêu cầu thay đổi tài nguyên duy nhất thay vì gửi nhiều yêu cầu thay đổi tài nguyên, mỗi yêu cầu chứa một thao tác duy nhất.
Ví dụ: nếu muốn tạo 10 chiến dịch, bạn nên gửi một MutateCampaignsRequest duy nhất có 10 đối tượng CampaignOperation. Để nhóm các thao tác trên nhiều loại tài nguyên thành một yêu cầu duy nhất, hãy sử dụng GoogleAdsService.Mutate hoặc tài nguyên đột biến.
Thay đổi phản hồi
Nội dung được trả về trong phản hồi phụ thuộc vào nội dung được gửi trong trường response_content_type của yêu cầu thay đổi tài nguyên.
Ví dụ: nếu bạn chỉ định MUTABLE_RESOURCE, thì phản hồi sẽ chứa cả resource_name của tài nguyên và các trường có thể thay đổi của chiến dịch trong campaign. Theo mặc định (RESOURCE_NAME_ONLY), chỉ resource_name được điền sẵn trong mỗi MutateCampaignResult.
Lỗi thay đổi
Theo mặc định (partial_failure = false), các thao tác trong yêu cầu thay đổi tài nguyên chỉ được áp dụng cho tài khoản Google Ads của bạn nếu mọi thao tác trong yêu cầu đều thành công; nếu có thao tác nào không thành công, toàn bộ yêu cầu sẽ được khôi phục. Đối với các yêu cầu mutate hỗ trợ lỗi một phần (những yêu cầu có trường partial_failure trên thông báo yêu cầu), việc đặt partial_failure = true sẽ cam kết các thao tác hợp lệ trong khi các thao tác không thành công sẽ trả về các lỗi dành riêng cho thao tác trong trường partial_failure_error của phản hồi. Hãy xem hướng dẫn về lỗi một phần và hướng dẫn về các lỗi thường gặp để biết thông tin chi tiết về cách xử lý lỗi.
Theo dõi thay đổi
Để theo dõi những thay đổi đối với các đối tượng trong tài khoản Google Ads hoặc để truy xuất trạng thái hiện tại của các đối tượng, bạn có thể sử dụng tài nguyên change_status và change_event.
change_statuscung cấp thông tin tóm tắt về những tài nguyên đã thay đổi trong một khoảng thời gian nhất định.change_eventcung cấp nhật ký chi tiết về các thay đổi, bao gồm cả giá trị cũ và giá trị mới của các trường đã thay đổi.
Để truy vấn các tài nguyên này, hãy sử dụng phương thức GoogleAdsService.SearchStream hoặc GoogleAdsService.Search. Đọc thêm về báo cáo truyền trực tuyến bằng GoogleAdsService.