Cấu trúc API

ondemand_video 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. Chiến lược phát hành đĩa đơn API Google Ads bao gồm các tài nguyên và dịch vụ. Tài nguyên đại diện cho Google Ads trong khi các dịch vụ truy xuất và thao túng các đối tượng của 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 khách hàng đang hoạt động chiến dịch.

• Mỗi chiến dịch chứa một hoặc nhiều nhóm quảng cáo, được sử dụng để nhóm quảng cáo vào 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 quảng cáo mà bạn đang chạy. Ngoại trừ những 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 quảng cáo 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í. Tiêu chí được xác định trong chiến dịch ả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ày và ngân sách toàn chiến dịch.

Cuối cùng, bạn có thể đính kèm tiện ích ở 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 vào quảng cáo của bạ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 của bạn. Campaign và AdGroup là hai ví dụ 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à riêng biệt trên toàn cầu ở mọi tài khoản Google Ads, trong khi những tài khoản khác chỉ là duy nhất trong trong một phạm vi có giới hạn.

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 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. 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 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ối tài nguyên và phần tử mẹ của nó thành một đường dẫn. Ví dụ: chiến dịch tên tài nguyên 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 thì 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 của 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ư truy xuất siêu dữ liệu luôn miễn phí.

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 mutate của bạn. Các lớp này cũng cung cấp yêu cầu get để truy xuất một tài nguyên duy nhất Thực thể 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. Cho Ví dụ: phương thức CampaignService.MutateCampaigns yêu cầu một hoặc nhiều các bản sao của CampaignOperation. Xem Thay đổi và kiểm tra đối tượng cho một thảo luận chi tiết về 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. Chiến dịch này có thể khiến lỗi phát sinh nếu bạn có nhiều người dùng cập nhật cùng một đối tượng với ứng dụng của mình hoặc nếu bạn thay đổi song song các đối tượng Google Ads bằng cách sử dụ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 luồng hoặc từ các ứng dụng khác nhau (ví dụ: ứng dụng của bạn và 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, 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 chờ phản hồi cho mỗi của bạn. Mặc dù phương pháp này tương đối đơn giản về lập trình, nhưng cũng có thể tác động tiêu cực đến 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 chờ cuộc 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ô hoạt động trên nhiều dịch vụ mà không cần chờ hoàn tất. Khi gửi công việc hàng loạt, máy chủ API Google Ads thực thi các thao tác không đồng bộ, giải phóng 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ông việc để hoàn thành.

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 yêu cầu thay đổi đều có thể được xác thực mà không cần thực sự thực thi lệnh gọ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à 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ể nhưng lượt thực thi cuối cùng lại bị bỏ qua. Nếu không tìm thấy lỗi nào thì cột trống được trả về. Nếu xác thực không thành công thì các thông báo lỗi trong phản hồi sẽ chỉ ra các điểm lỗi.

validate_only đặc biệt hữu ích trong việc thử nghiệm quảng cáo theo chính sách chung vi phạm. Quảng cáo 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ô bị lỗi. Thử nghiệm một quảng cáo mới trong một validate_only có thể bộc lộ mọi vi phạm như vậy. Hãy tham khảo mã ví dụ để xử lý lỗi vi phạm chính sách để xem trong thực tế.

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

GoogleAdsService là phiên bản duy nhất, hợp nhất để truy xuất đối tượng và số liệu thống kê hiệu suất.

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