Thay đổi đối tượng

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 API Google Ads đều có một dịch vụ tương ứng dành riêng cho loại tài nguyên hỗ trợ sửa đổi các thực thể của tài nguyên. Bạn cũng có thể sử dụng GoogleAdsService.Mutate để thay đổi nhiều loại tài nguyên một cách nguyên tử trong một yêu cầu.

Hướng dẫn này sử dụng CampaignService để minh hoạ cách sửa đổi đố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 thay đổi chấp nhận yêu cầu thay đổi. Yêu cầu này bao gồm:

  • customer_id (hoặc customerId trong URL REST)
  • Một tập hợ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_only và 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 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_only và response_content_type cho biết loại phản hồi ưu tiên)

Vận hành

Đối tượng thao tác, chẳng hạn như CampaignOperation, cho phép bạn chỉ định hành động mà bạn muốn thực hiện trên một tài nguyên 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 thực thể 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 đặt update_mask của thao tác. Trường này cho API Google Ads biết những thuộc tính cần sửa đổi 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ạo update_mask cho 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, nên bạn không thể sử dụng một thao tác để 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 2 thực thể của CampaignOperation vào yêu cầu của bạn: một thực thể có create được đặt và một thực thể 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, nhưng một yêu cầu thay đổi tài nguyên có thể chứa nhiều thao tác. Bạn nên kết hợp các thao tác vào một yêu cầu thay đổi tài nguyên 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.

Ví dụ: nếu bạn 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 vào một yêu cầu, hãy sử dụng GoogleAdsService.Mutate hoặc thay đổi tài nguyên.

Phản hồi thay đổ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. Ví dụ: nếu MUTABLE_RESOURCE được chỉ định, 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 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 bất kỳ 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 thay đổi hỗ trợ lỗi một phần (các 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ề 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 các thay đổi

Để theo dõi các thay đổi được thực hiện đố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_status cung 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_event cung 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ề tính năng truyền trực tuyến báo cáo bằng GoogleAdsService.

Trước
Lập phiên bản
Tiếp
Truy xuất đối tượng