Video: Xem bài nói chuyện về Các 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 API Google Ads. API Google Ads bao gồm các 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
Tài khoản Google Ads có thể được xem là một hệ phân cấp các đối tượng.
Tài nguyên cấp cao nhất của tài khoản là khách hàng.
Mỗi khách hàng chứa 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, dùng để nhóm quảng cáo của bạn thành các bộ sưu tập hợp lý.
Quảng cáo trong nhóm quảng cáo đại diện cho một 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 trong nhóm quảng cáo trong mỗi nhóm quảng cáo, mỗi nhóm quảng cáo chứa một hoặc nhiều quảng cáo trong 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. Các giá trị này đại diện cho các 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í. Các 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 cho toàn bộ 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. Tiện ích cho phép bạn cung cấp thêm thông tin cho quảng cáo của mình, 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 của bạn. Campaign và AdGroup là hai ví dụ về tài nguyên.
Mã đối tượng
Mỗi đối tượng trong Google Ads được xác định theo mã nhận dạng riêng của đối tượng đó. Một số mã trong số này là duy nhất trên toàn cầu trên tất cả các tài khoản Google Ads, trong khi một số khác chỉ là duy nhất trong một phạm vi có giới hạn.
| Mã đối tượng | Phạm vi của tính duy nhất | Độc đáo trên toàn cầu? |
|---|---|---|
| ID ngân sách | Các khu vực nói tiếng Anh | Có |
| Mã chiến dịch | Các khu vực nói tiếng Anh | Có |
| ID Nhóm Quảng cáo | Các khu vực nói tiếng Anh | 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 hệ thống |
| ID tiêu chí nhóm quảng cáo | Nhóm Quảng cáo | Không, nhưng cặp (AdGroupId, CriterionId) là duy nhất trên toàn hệ thống |
| ID tiêu chí chiến dịch | Chiến dịch | Không, nhưng cặp (CampaignId, CriterionId) là duy nhất trên toàn hệ thống |
| 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 hệ thống |
| ID nguồn cấp dữ liệu | Các khu vực nói tiếng Anh | Có |
| Mã mục nguồn cấp dữ liệu | Các khu vực nói tiếng Anh | Có |
| Mã thuộc tính nguồn cấp dữ liệu | Nguồn cấp dữ liệu | Không |
| ID mối liên kết nguồn cấp dữ liệu | Các khu vực nói tiếng Anh | Có |
| ID nhãn | Các khu vực nói tiếng Anh | Có |
| ID danh sách người dùng | Các khu vực nói tiếng Anh | Có |
Các quy tắc 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.
Một số đối tượng có thể dùng cho nhiều loại thực thể. Trong những trường hợp như vậy, đối tượng chứa 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 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 duy nhất bằng một chuỗi resource_name, chuỗi này nối tài nguyên và phần tử mẹ của 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ể của mình trên Google Ads. Có 3 loại dịch vụ: sửa đổi, truy xuất đối tượng và truy xuất số liệu thống kê, cũng như dịch vụ truy xuất siêu dữ liệu.
Sửa đổi (thay đổi) đối tượng
Các dịch vụ này sửa đổi các bản sao của một loại tài nguyên liên kết bằng cách sử dụng yêu cầu mutate. Các lớp này cũng cung cấp yêu cầu get truy xuất một thực thể tài nguyên. Điều này có thể hữu ích cho việc kiểm tra cấu trúc của 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 thực thể của CampaignOperation. Vui lòng xem phần Thay đổi và kiểm tra đối tượng để nắm được nội dung thảo luận chi tiết về các hoạt động.
Thay đổi đồng thời
Bạn không thể sửa đổi đồng thời một đối tượng Google Ads qua nhiều nguồn. Đ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 bạn hoặc nếu bạn thay đổi song song các đối tượng Google Ads 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ừ nhiều ứng dụng (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á đối tượng trước khi cập nhật; nếu hai nguồn cố gắng thay đổi đồng thời một đối tượng, thì API sẽ đưa ra DatabaseError.CONCURRENT_MODIFICATION_ERROR.
Thay đổi không đồng bộ so với đồng bộ
Các phương thức thay đổi API Google Ads có tính đồng bộ. Lệnh gọi API chỉ trả về phản hồi sau khi các đối tượng bị thay đổi, đòi hỏi bạn phải đợi phản hồi cho từng yêu cầu. Mặc dù việc viết mã theo phương pháp này tương đối đơn giản, nhưng nó có thể tác độ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 bắt buộc phải chờ các lệnh gọi hoàn tất.
Một phương pháp thay thế là thay đổi các đối tượng một cách không đồng bộ bằng cách sử dụng BatchJobService, thực hiện các lô thao tác trên nhiều dịch vụ mà không cần chờ các dịch vụ đó hoàn tất. Sau khi gửi một tác vụ hàng loạt, các máy chủ API Google Ads sẽ thực thi các thao tác một cách 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ể kiểm tra định kỳ trạng thái công việc để biết trạng thái hoàn thành.
Xem hướng dẫn về Xử lý theo lô để biết thêm thông tin về quá trình xử lý không đồng bộ.
Xác thực thay đổi
Hầu hết các yêu cầu thay đổi đều có thể được xác thực mà không 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 về các tham số bị thiếu và giá trị trường không chính xác mà không 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 lượt 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, các thông báo lỗi trong phản hồi sẽ chỉ ra điểm lỗi.
validate_only đặc biệt hữu ích trong việc kiểm tra quảng cáo để phát hiện các lỗi vi phạm chính sách phổ biến. 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ừ ngữ, 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ô không hoạt động. Việc thử nghiệm một quảng cáo mới trong yêu cầu validate_only
có thể phát hiện mọi lỗi vi phạm như vậy. Hãy tham khảo mã ví dụ để xử lý các lỗi vi phạm chính sách để xem ví dụ thực tế.
Nhận đối tượng và số liệu thống kê về hiệu suất
GoogleAdsService là dịch vụ hợp nhất và đơn 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ả yêu cầu Search và SearchStream cho GoogleAdsService đều yêu cầu 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à các chỉ số hiệu suất cần truy xuất, các thuộc tính dùng để lọc yêu cầu và các phân đoạ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 trên Google Ads.
Truy xuất siêu dữ liệu
GoogleAdsFieldService truy xuất siêu dữ liệu về tài nguyên trong API Google Ads, chẳng hạn như các thuộc tính có sẵn cho một tài nguyên và loại dữ liệu của tài nguyên đó.
Dịch vụ này cung cấp thông tin cần thiết trong việc tạo truy vấn tới GoogleAdsService. Để thuận tiện, thông tin do GoogleAdsFieldService trả về cũng có trong tài liệu tham khảo về trường.