Video: Xem bài nói chuyện về Dịch vụ và tài nguyên trong hội thảo năm 2019
Hướng dẫn này giới thiệu các thành phần chính tạo nên Google Ads API. API Google Ads bao gồm tài nguyên và dịch vụ. Tài nguyên đại diện cho một thực thể Google Ads, trong khi các dịch vụ truy xuất và thao tác với các thực thể Google Ads.
Hệ phân cấp đối tượng
Bạn có thể xem tài khoản Google Ads như một hệ phân cấp các đối tượng.
Tài nguyên cấp cao nhất của một tài khoản là khách hàng.
Mỗi khách hàng có một hoặc nhiều chiến dịch đang hoạt động.
Mỗi chiến dịch chứa một hoặc nhiều nhóm quảng cáo, được dùng để nhóm quảng cáo thành các bộ sưu tập hợp lý.
Quảng cáo trong nhóm quảng cáo là quảng cáo mà bạn đang chạy. Ngoại trừ chiến dịch quảng cáo ứng dụng chỉ có thể có một quảng cáo nhóm quảng cáo cho mỗi nhóm quảng cáo, mỗi nhóm quảng cáo đều chứa một hoặc nhiều quảng cáo nhóm quảng cáo.
Bạn có thể đính kèm một hoặc nhiều AdGroupCriterion hoặc CampaignCriterion vào một nhóm quảng cáo hoặc chiến dịch. Đây là những tiêu chí xác định cách quảng cáo được kích hoạt.
Có nhiều loại tiêu chí, chẳng hạn như từ khoá, độ tuổi và vị trí. Tiêu chí được xác định ở cấp chiến dịch sẽ ảnh hưởng đến tất cả các tài nguyên khác trong chiến dịch. Bạn cũng có thể chỉ định ngân sách và ngày trên toàn chiến dịch.
Cuối cùng, bạn có thể đính kèm phần mở rộng ở cấp tài khoản, chiến dịch hoặc nhóm quảng cáo. Phần mở rộng giúp bạn cung cấp thêm thông tin cho quảng cáo, chẳng hạn như số điện thoại, địa chỉ đường phố hoặc chương trình khuyến mãi.
Tài nguyên
Tài nguyên đại diện cho các thực thể trong tài khoản Google Ads. Campaign và AdGroup là hai ví dụ về tài nguyên.
Mã đối tượng
Mỗi đối tượng trong Google Ads đều được xác định bằng mã nhận dạng riêng. Một số mã nhận dạng này là duy nhất trên toàn cầu đối với tất cả tài khoản Google Ads, trong khi những mã nhận dạng khác chỉ duy nhất trong một phạm vi giới hạn.
| Mã đối tượng | Phạm vi của tính duy nhất | Có tính duy nhất trên toàn cầu? |
|---|---|---|
| ID ngân sách | Toàn cầu | Có |
| Mã chiến dịch | Toàn cầu | Có |
| ID Nhóm Quảng cáo | Toàn cầu | Có |
| ID Quảng cáo | Nhóm quảng cáo | Không, nhưng cặp (AdGroupId, AdId) là duy nhất trên toàn cầu |
| Mã AdGroupCriterion | Nhóm quảng cáo | Không, nhưng cặp (AdGroupId, CriterionId) là duy nhất trên toàn cầu |
| Mã nhận dạng CampaignCriterion | Chiến dịch | Không, nhưng cặp (CampaignId, CriterionId) là duy nhất trên toàn cầu |
| Phần mở rộng quảng cáo | Chiến dịch | Không, nhưng cặp (CampaignId, AdExtensionId) là duy nhất trên toàn cầu |
| ID nhãn | Toàn cầu | Có |
| Mã danh sách người dùng | Toàn cầu | Có |
| Mã tài sản | Toàn cầu | Có |
Các quy tắc về mã nhận dạng này có thể hữu ích khi thiết kế bộ nhớ cục bộ cho các đối tượng Google Ads của bạn.
Một số đối tượng có thể được dùng cho nhiều loại thực thể. Trong những trường hợp như vậy, đối tượng sẽ chứa một trường type mô tả nội dung của đối tượng. Ví dụ: AdGroupAd có thể đề cập đến một đối tượng như quảng cáo dạng văn bản, quảng cáo khách sạn hoặc quảng cáo địa phương. Bạn có thể truy cập vào giá trị này thông qua trường AdGroupAd.ad.type và trả về một giá trị trong enum AdType.
Tên tài nguyên
Mỗi tài nguyên được xác định riêng biệt bằng một chuỗi resource_name, chuỗi này nối tài nguyên và các tài nguyên mẹ của tài nguyên đó thành một đường dẫn. Ví dụ: tên tài nguyên chiến dịch có dạng:
customers/customer_id/campaigns/campaign_id
Vì vậy, đối với chiến dịch có mã 987654 trong tài khoản Google Ads có mã khách hàng 1234567, resource_name sẽ là:
customers/1234567/campaigns/987654
Dịch vụ
Các dịch vụ cho phép bạn truy xuất và sửa đổi các thực thể Google Ads. Có 3 loại dịch vụ: dịch vụ sửa đổi, dịch vụ truy xuất đối tượng và số liệu thống kê, và dịch vụ truy xuất siêu dữ liệu.
Sửa đổi (biến đổi) các đối tượng
Các dịch vụ này sửa đổi các thực thể của một loại tài nguyên được liên kết bằng cách sử dụng yêu cầu mutate. Chúng cũng cung cấp một yêu cầu get để truy xuất một thực thể tài nguyên duy nhất. Điều này có thể hữu ích khi kiểm tra cấu trúc của một tài nguyên.
Ví dụ về các dịch vụ:
CustomerServiceđể sửa đổi khách hàng.CampaignServiceđể sửa đổi chiến dịch.AdGroupServiceđể sửa đổi nhóm quảng cáo.
Mỗi yêu cầu mutate phải bao gồm các đối tượng operation tương ứng. Ví dụ: phương thức CampaignService.MutateCampaigns yêu cầu một hoặc nhiều phiên bản của CampaignOperation. Hãy xem phần Thay đổi và kiểm tra các đối tượng để biết nội dung thảo luận chi tiết về các thao tác.
Đột biến đồng thời
Không được phép có nhiều nguồn cùng sửa đổi một đối tượng Google Ads. Điều này có thể gây ra lỗi nếu bạn có nhiều người dùng cập nhật cùng một đối tượng bằng ứng dụng của mình hoặc nếu bạn đang biến đổi các đối tượng Google Ads song song bằng nhiều luồng. Điều này bao gồm việc cập nhật đối tượng từ nhiều luồng trong cùng một ứng dụng hoặc từ các ứng dụng khác nhau (ví dụ: ứng dụng của bạn và một phiên giao diện người dùng Google Ads đồng thời).
API không cung cấp cách khoá một đối tượng trước khi cập nhật; nếu hai nguồn cố gắng đồng thời thay đổi một đối tượng, API sẽ tạo ra một DatabaseError.CONCURRENT_MODIFICATION_ERROR.
Thao tác biến đổi không đồng bộ so với thao tác biến đổi đồng bộ
Các phương thức biến đổi của API Google Ads có tính đồng bộ. Các lệnh gọi API chỉ trả về một phản hồi sau khi các đối tượng bị thay đổi, yêu cầu bạn phải đợi phản hồi cho từng yêu cầu. Mặc dù phương pháp này tương đối đơn giản để mã hoá, nhưng có thể ảnh hưởng tiêu cực đến việc cân bằng tải và lãng phí tài nguyên nếu các quy trình buộc phải đợi các lệnh gọi hoàn tất.
Một phương pháp thay thế là biến đổi các đối tượng không đồng bộ bằng cách sử dụng BatchJobService. Phương pháp này thực hiện các lô thao tác trên nhiều dịch vụ mà không cần chờ hoàn thành. Sau khi bạn gửi một lô công việc, các máy chủ API Google Ads sẽ thực hiện các thao tác không đồng bộ, giải phóng các quy trình để thực hiện các thao tác khác. Bạn có thể định kỳ kiểm tra trạng thái của lệnh để biết lệnh đã hoàn tất hay chưa.
Hãy xem hướng dẫn Xử lý hàng loạt để biết thêm thông tin về quy trình xử lý không đồng bộ.
Xác thực thay đổi
Hầu hết các yêu cầu biến đổi đều có thể được xác thực mà không cần thực sự thực thi lệnh gọi đối với dữ liệu thực. Bạn có thể kiểm thử yêu cầu đối với các tham số bị thiếu và giá trị trường không chính xác mà không cần thực sự thực thi thao tác.
Để sử dụng tính năng này, hãy đặt trường boolean validate_only không bắt buộc của yêu cầu thành true. Sau đó, yêu cầu sẽ được xác thực đầy đủ như thể sẽ được thực thi, nhưng quá trình thực thi cuối cùng sẽ bị bỏ qua. Nếu không tìm thấy lỗi, hệ thống sẽ trả về một phản hồi trống. Nếu xác thực không thành công, thông báo lỗi trong phản hồi sẽ cho biết các điểm thất bại.
validate_only đặc biệt hữu ích trong việc kiểm thử quảng cáo để phát hiện các lỗi vi phạm chính sách thường gặp. Quảng cáo sẽ tự động bị từ chối nếu vi phạm các chính sách như có từ, dấu câu, cách viết hoa hoặc độ dài cụ thể. Một quảng cáo không hợp lệ có thể khiến toàn bộ lô quảng cáo không hợp lệ. Việc thử nghiệm một quảng cáo mới trong một yêu cầu validate_only
có thể cho thấy mọi trường hợp vi phạm như vậy. Hãy tham khảo ví dụ về mã để biết cách xử lý lỗi vi phạm chính sách để xem cách thực hiện.
Nhận các đối tượng và số liệu thống kê về hiệu suất
GoogleAdsService là dịch vụ duy nhất, hợp nhất để truy xuất các đối tượng và số liệu thống kê về hiệu suất.
Tất cả các yêu cầu Search và SearchStream cho GoogleAdsService đều yêu cầu một truy vấn chỉ định tài nguyên cần truy vấn, các thuộc tính tài nguyên và chỉ số hiệu suất cần truy xuất, các vị từ cần dùng để lọc yêu cầu và các phân đoạn cần dùng để phân tích thêm số liệu thống kê về hiệu suất. Để biết thêm thông tin về định dạng truy vấn, hãy xem hướng dẫn về Ngôn ngữ truy vấn Google Ads.
Truy xuất siêu dữ liệu
GoogleAdsFieldService truy xuất siêu dữ liệu về các tài nguyên trong Google Ads API, chẳng hạn như các thuộc tính có sẵn cho một tài nguyên và kiểu dữ liệu của tài nguyên đó.
Dịch vụ này cung cấp thông tin cần thiết để tạo một truy vấn đến GoogleAdsService. Để thuận tiện, thông tin do GoogleAdsFieldService trả về cũng có trong tài liệu tham khảo về các trường.