Cấu trúc API

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 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 trên các thực thể của Google Ads.

Hệ phân cấp đối tượng

Tài khoản Google Ads có thể được xem là 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 tài khoản chứa một hoặc nhiều chiến dịch đang hoạt động.

  • Mỗi Campaign 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 logic.

  • Mỗi AdGroup chứa một hoặc nhiều quảng cáo cấp nhóm quảng cáo. AdGroupAd đại diện cho quảng cáo mà bạn đang chạy.

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 mục hàng này đại diện cho các tiêu chí xác định cách kích hoạt quảng cáo.

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 cho 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 cho phép bạn cung cấp thêm thông tin cho quảng cáo, như số điện thoại, địa chỉ đường phố hoặc chương trình khuyến mãi.

Nguồn tham khảo

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.

ID đối tượng

Mỗi đối tượng trong Google Ads được xác định bằng mã riêng. Một số mã này là riêng biệt trên toàn cầu trên tất cả các tài khoản Google Ads, trong khi các mã khác chỉ là duy nhất trong một phạm vi hạn chế.

ID đối tượng Phạm vi độc nhất Toàn cầu là duy nhất?
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
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 cầu
ID chiến dịch 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 nguồn cấp dữ liệu Toàn cầu Có
ID mục nguồn cấp dữ liệu Toàn cầu Có
ID thuộc tính nguồn cấp dữ liệu Nguồn cấp dữ liệu Không
ID bản đồ nguồn cấp dữ liệu Toàn cầu Có
ID nhãn Toàn cầu Có
ID danh sách người dùng Toàn cầu 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.

Bạn có thể dùng một số đối tượng cho nhiều loại thực thể. Trong những trường hợp như vậy, đối tượng chứa một trường type mô tả nội dung của đối tượng. Ví dụ: AdGroupAd có thể tham chiếu đến quảng cáo dạng văn bản, quảng cáo khách sạn, quảng cáo địa phương, v.v. 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 giá trị 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, liên kết tài nguyên này và tài nguyên mẹ vào một đường dẫn. Ví dụ: tên tài nguyên chiến dịch có dạng như sau:

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ủa mình. Có ba loại dịch vụ: sửa đổi, 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 (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. Họ cũng cung cấp yêu cầu get truy xuất một phiên bản tài nguyên duy nhất. Điều này có thể hữu ích cho việc kiểm tra cấu trúc của một tài nguyên.

Ví dụ về dịch vụ:

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 dự kiến có một hoặc nhiều bản sao của CampaignOperation. Vui lòng xem phần Thay đổi và kiểm tra đối tượng để biết nội dung thảo luận chi tiết về các thao tác.

Thay đổi đồng thời

Bạn không thể sửa đổi đồng thời một đối tượng Google Ads bằng 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 hoặc nếu bạn thay đổi các đối tượng Google Ads song song với nhau bằng nhiều luồng. Quá trình này bao gồm việc cập nhật đối tượng từ nhiều chuỗi 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á một đố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, API sẽ tăng DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Đột biến không đồng bộ so với không đồng bộ

Phương pháp thay đổi API Google Ads là đồng bộ. Các lệnh gọi API chỉ trả về phản hồi sau khi các đối tượng bị thay đổi, yêu cầu bạn phải chờ phản hồi cho mỗi yêu cầu. Mặc dù phương pháp này tương đối đơn giản để lập trình, nhưng nó 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 lệnh gọi hoàn tất.

Một phương pháp thay thế là thay đổi các đối tượng không đồng bộ bằng cách sử dụng BatchJobService. Phương thức này thực hiện nhiều thao tác trên nhiều dịch vụ mà không cần chờ hoàn tất. Sau khi gửi lệnh hàng loạt, máy chủ API Google Ads sẽ thực thi các thao tác một cách không đồng bộ, giúp 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ủa công việc để hoàn thành.

Xem Hướng dẫn xử lý hàng loạt để biết thêm về cách 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 thiếu các tham số 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 hoàn toàn như thể 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 nào, hệ thống sẽ trả về 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 điểm lỗi.

validate_only đặc biệt hữu ích trong việc kiểm tra các quảng cáo để biết 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 chính sách, chẳng hạn như có cá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 thành công. Việc thử nghiệm quảng cáo mới trong yêu cầu validate_only có thể cho thấy mọi lỗi vi phạm như vậy. Hãy tham khảo ví dụ về mã để xử lý các lỗi vi phạm chính sách để xem cách xử lý này trong thực tế.

Nhận đối tượng và số liệu thống kê hiệu suất

GoogleAdsService là dịch vụ 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ả yêu cầu Search và SearchStream cho GoogleAdsService yêu cầu truy vấn chỉ định tài nguyên để truy vấn, các thuộc tính tài nguyên và chỉ số hiệu suất để truy xuất, các điều kiện để sử dụng cho việc lọc yêu cầu và các phân đoạn sẽ sử dụng để phân tích thêm thống kê 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 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 bạn cần khi tạo một truy vấn đến GoogleAdsService. Để thuận tiện, thông tin mà GoogleAdsFieldService trả về cũng có trong tài liệu tham khảo về các trường.

Trước
Tổng quan
Tiếp
Mối quan hệ của thực thể