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. Google Ads API 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 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 dưới dạng 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 các quảng cáo của bạn thành các tập hợ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 trong một nhóm quảng cáo. 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 cho 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.
Chiến dịch Tối đa hoá hiệu suất sử dụng một cấu trúc khác với các loại chiến dịch khác: thay vì nhóm quảng cáo và quảng cáo trong nhóm quảng cáo, chiến dịch Tối đa hoá hiệu suất chứa nhóm thành phần. Bạn liên kết thành phần mẫu quảng cáo với một nhóm thành phần bằng cách sử dụng AssetGroupAsset và đính kèm tín hiệu về đối tượng hoặc chủ đề tìm kiếm bằng cách sử dụng AssetGroupSignal.
Bạn có thể đính kèm một hoặc nhiều tài nguyên AdGroupCriterion hoặc CampaignCriterion vào một nhóm quảng cáo hoặc chiến dịch. Các tiêu chí này 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á, nhóm 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 cũng như ngày và giờ bắt đầu và kết thúc cho chiến dịch hoặc cho từng quảng cáo riêng lẻ bằng cách sử dụng AdGroupAd.start_date_time và AdGroupAd.end_date_time.
Cuối cùng, bạn có thể đính kèm thành phần ở cấp tài khoản, chiến dịch, nhóm quảng cáo hoặc nhóm thành phần. Thành phần 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. Xem bài viết Tổng quan về thành phần.
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 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 trong tất cả tài khoản Google Ads, trong khi một số mã nhận dạng khác chỉ là duy nhất trong một phạm vi hạn chế.
| Mã đối tượng | Phạm vi của tính duy nhất | 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. Bạn không được phép dùng chung một AdId cho nhiều nhóm quảng cáo. |
| 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 |
| CampaignCriterion ID | Chiến dịch | Không, nhưng cặp (CampaignId, CriterionId) là duy nhất trên toàn cầu |
| ID nhãn | Khách hàng | Không, nhưng cặp (CustomerId, LabelId) là duy nhất trên toàn cầu |
| 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ể tham chiếu đến một đối tượng như
quảng cáo tìm kiếm thích ứng, quảng cáo khách sạn hoặc quảng cáo Tạo nhu cầu. 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. Xin lưu ý rằng khả năng biến đổi có thể khác nhau tuỳ theo phiên bản (ví dụ: VideoResponsiveAdInfo trên Ad có thể biến đổi trong phiên bản 24 trở lên).
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 nối tài nguyên và 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 như sau:
customers/customer_id/campaigns/campaign_id
Vì vậy, đối với một chiến dịch có mã 987654 trong tài khoản Google Ads có mã khách hàng là 1234567, thì resource_name sẽ là:
customers/1234567/campaigns/987654
Dịch vụ
Dịch vụ cho phép bạn truy xuất và sửa đổi các thực thể Google Ads. Có ba 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 (thay đổi) đối tượng
Các dịch vụ dành riêng cho tài nguyên sẽ 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. Bạn cũng có thể sử dụng GoogleAdsService.Mutate để thực hiện các phép biến đổi nguyên tử trên nhiều loại tài nguyên trong một yêu cầu (chẳng hạn như tạo ngân sách chiến dịch, chiến dịch và nhóm quảng cáo cùng nhau).
Ví dụ về các dịch vụ dành riêng cho tài nguyên:
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. Xem phần Thay đổi đố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
Nhiều nguồn không thể sửa đổi một đối tượng Google Ads cùng một lúc. Đ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 thay đổ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 này 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 một đối tượng cùng lúc, thì API sẽ đưa ra lỗi DatabaseError.CONCURRENT_MODIFICATION_ERROR.
Thao tác đột biến không đồng bộ so với đồng bộ
Các phương thức thay đổi của Google Ads API là đồng bộ. Các lệnh gọi API chỉ trả về phản hồi sau khi các đối tượng được thay đổi, yêu cầu bạn phải đợi phản hồi cho mỗi yêu cầu. Mặc dù phương pháp này tương đối dễ lập trình, 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 lệnh gọi hoàn tất.
Một phương pháp khác là thay đổi đố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 các lô thao tác trên nhiều dịch vụ mà không cần chờ hoàn tất. Sau khi bạn gửi một công việc theo lô, máy chủ Google Ads API 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ủa công việc để biết khi nào công việc hoàn tất.
Hãy xem Hướng dẫn xử lý hàng loạt để 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 tài nguyên đề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 tra 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 cần thực sự thực hiện 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. Yêu cầu được xác thực đầy đủ như thể nó sẽ được thực thi, nhưng
quá trình thực thi cuối cùng bị bỏ qua. Nếu không tìm thấy lỗi, hệ thống sẽ trả về phản hồi mà không có kết quả đột biến nào được điền sẵn (results trống). Nếu không xác thực được, thì theo mặc định, yêu cầu sẽ không thành công và trả về lỗi RPC GoogleAdsFailure (partial_failure = false) hoặc trả về phản hồi bình thường kèm theo lỗi cụ thể của thao tác trong partial_failure_error khi partial_failure = true.
validate_only đặc biệt hữu ích trong việc thử nghiệm 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 chính sách, chẳng hạn 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ô quảng cáo không được phê duyệt. 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 những lỗi vi phạm như vậy. Hãy tham khảo mã ví dụ về cách xử lý lỗi vi phạm chính sách để xem cách hoạt động của mã này.
Nhận đố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ả yêu cầu Search và SearchStream cho GoogleAdsService đều cần có một truy vấn chỉ định tài nguyên cần truy vấn, thuộc tính tài nguyên và chỉ số hiệu suất cần truy xuất, vị từ cần dùng để lọc yêu cầu và 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 của 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à loại dữ liệu của tài nguyên đó. Hãy xem Hướng dẫn về siêu dữ liệu tài nguyên để biết thông tin chi tiết về cách truy vấn dịch vụ này.
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.