Thay đổi đối tượng

Mục tiêu: Tìm hiểu cách sửa đổi đối tượng bằng Google Ads API.

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 theo 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ể sử dụng GoogleAdsService.Mutate để thay đổi nhiều loại tài nguyên một cách riêng biệ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.

Thuật ngữ chính: Tài nguyên cấp cao nhất là một tài nguyên có tên không chứa dấu chấm (.). Ví dụ: Campaign là tài nguyên cấp cao nhất, nhưng Campaign.NetworkSettings thì không.

Yêu cầu thay đổi tài nguyên

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 yêu cầu thay đổi tài nguyên. Yêu cầu này bao gồm:

• customer_id (hoặc customerId trong URL REST)
• Bộ sưu tập operations
• Các chế độ cài đặt thực thi không bắt buộc 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 một MutateCampaignsRequest bao gồm:

• customer_id
• Một tập hợp gồm CampaignOperation đối tượng (operations)
• 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)

Lưu ý: Các dịch vụ và phương thức có sẵn có thể khác nhau tuỳ theo phiên bản API. Ví dụ: để định cấu hình mục tiêu vòng đời của khách hàng và chiến dịch, hãy sử dụng các phương thức Mutate* trên GoalService và CampaignGoalConfigService trong phiên bản 25 trở lên, hoặc các phương thức Configure* trên CustomerLifecycleGoalService và CampaignLifecycleGoalService trong phiên bản 24 trở xuống.

Vận hành

Đối tượng thao tác 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à một 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. Thao tác này sẽ cho Google Ads API 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 hai thực thể của CampaignOperation vào yêu cầu của bạn: một thực thể có create và một thực thể có remove.

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 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.

Ví dụ: nếu muốn tạo 10 chiến dịch, bạn nên gửi một MutateCampaignsRequest 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 tài nguyên thay đổi.

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ó 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 tài nguyên 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ẽ thực hiện 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 theo thao tác cụ thể 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 các thay đổi đối với đố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 đố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à 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.