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ụ cụ thể theo loại tài nguyên tương ứng hỗ trợ:
- Sửa đổi các thực thể của tài nguyên
- Truy xuất một thực thể của tài nguyên để kiểm tra
Hướng dẫn này sẽ sử dụng CampaignService
để minh hoạ việc sửa đổi và kiểm tra các đối tượng Campaign
, nhưng các khái niệm tương tự sẽ áp dụng cho tất cả các dịch vụ cụ thể theo loại tài nguyên khác.
Thay đổi đối tượng
Mỗi dịch vụ dành riêng cho từng loại tài nguyên sẽ có một phương thức mutate chấp nhận yêu cầu thay đổi. Yêu cầu này bao gồm:
- Một
customerId
- Tập hợp các phép toán
- Chế độ cài đặt loại nội dung phản hồi xác định liệu tài nguyên có thể thay đổi hay chỉ tên tài nguyên sẽ được trả về sau khi đột biến.
Ví dụ: phương thức MutateCampaigns
của CampaignService
chấp nhận MutateCampaignsRequest
bao gồm:
- Một
customerId
- Tập hợp đối tượng
CampaignOperation
- Trường
response_content_type
cho biết loại phản hồi ưu tiên.
Hoạt động tính toán
Đối tượng hoạt động 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 bằng cách đặt trường operation
của tài nguyên đó. Trường này là một trường bao gồm các thuộc tính sau, trong đó loại là loại tài nguyên:
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 đặtupdate_mask
của thao tác. Thao tác này sẽ cho API Google Ads biết những thuộc tính cần sửa đổi trong quá trình cập nhật. Mỗi thư viện ứng dụng đều có một phương thức tiện ích hoặc trình trợ giúp để tạoupdate_mask
cho bạn, như được minh hoạ trong thư viện ứng dụng của chúng tôi. remove
- Xoá tài nguyên.
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 bản sao của CampaignOperation
vào yêu cầu: một bản sao đã đặt create
và một bản sao khác đã đặt remove
.
Hoạt động gộp nhóm
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 biến đổi có thể chứa nhiều thao tác. Bạn nên kết hợp các hoạt động của mình thành một yêu cầu biến đổi duy nhất thay vì gửi nhiều yêu cầu biến đổi, trong đó mỗi yêu cầu chứa một hoạt động duy nhất.
Ví dụ: nếu muốn tạo 10 chiến dịch, bạn nên gửi một duy nhất MutateCampaignsRequest
có 10 đối tượng CampaignOperation
.
Thay đổi phản hồi
Nội dung được trả về trong phản hồi sẽ tuỳ thuộc vào nội dung được gửi trong 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ỉ chứa các trường có thể thay đổi trong chiến dịch. Sau đó, bạn có thể thực hiện các thay đổi tiếp theo trên đối tượng tài nguyên đó mà không cần phải tạo lại đối tượng đó.
Thay đổi lỗi
Các thao tác trong một yêu cầu thay đổi nhất định sẽ 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 thành công. Hãy xem hướng dẫn về các lỗi thường gặp để biết danh sách các lỗi phổ biến và cách khắc phục.
Kiểm tra các đối tượng bằng get (Không dùng nữa)
Ngoài việc thay đổi đối tượng, mỗi dịch vụ dành riêng cho từng loại tài nguyên cũng có một phương thức get để truy xuất tất cả thuộc tính của một tài nguyên duy nhất.
Phương thức này chấp nhận một yêu cầu lấy dữ liệu có thuộc tính duy nhất là resource_name
.
Các phương thức get rất tiện lợi do API Google Ads cung cấp để giúp bạn dễ dàng
truy xuất tất cả thuộc tính của một đối tượng duy nhất. Mặc dù đây là công cụ tuyệt vời để tìm hiểu API hoặc kiểm tra một đối tượng riêng lẻ cho mục đích gỡ lỗi hoặc giáo dục, nhưng ứng dụng của bạn không nên sử dụng phương thức get để truy xuất đối tượng cho mục đích xử lý hoặc báo cáo. Thay vào đó, hãy sử dụng GoogleAdsService
vì mã này chỉ cho phép bạn truy xuất các thuộc tính cụ thể của đối tượng, hỗ trợ truy xuất các chỉ số hiệu suất và cho phép truyền trực tuyến qua các tập hợp kết quả lớn. Nếu ứng dụng của bạn gửi một số lượng lớn yêu cầu nhận, bạn có thể gặp phải giới hạn số lượng yêu cầu.