API Báo cáo Search Ads 360 mới hiện đã ra mắt. Tham gia nhóm Google
searchads-api-announcements để luôn được cập nhật về những cải tiến và bản phát hành sắp tới.
Cấu trúc API Báo cáo của Search Ads 360
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Các thành phần chính của API báo cáo Search Ads 360 là tài nguyên và dịch vụ. Tài nguyên đại diện cho một thực thể Search Ads 360 và bạn sử dụng một dịch vụ để truy xuất các thực thể Search Ads 360.
Hệ phân cấp đối tượng
Tài khoản Search Ads 360 là một hệ thống 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 giúp nhóm quảng cáo của bạn thành các tập hợp logic.
Mỗi AdGroup 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 hay CampaignCriterion
vào một nhóm quảng cáo hoặc chiến dịch. 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í. 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 trên toàn chiến dịch.
Tài nguyên
Tài nguyên đại diện cho các thực thể trong tài khoản Search Ads 360. Các tài nguyên mẫu bao gồm Customer, Campaign và AdGroup.
Mã đối tượng
Mỗi đối tượng trong Search Ads 360 được xác định bằng mã nhận dạng riêng. Một số mã nhận dạng là duy nhất trên toàn cầu, tức là trên tất cả tài khoản Search Ads 360, trong khi một số mã nhận dạng khác chỉ duy nhất trong một phạm vi giới hạn.
| Phạm vi duy nhất của mã đối tượng |
| ID ngân sách |
Toàn cầu |
| Mã chiến dịch |
Toàn cầu |
| ID Nhóm Quảng cáo |
Toàn cầu |
| ID Quảng cáo |
Nhóm quảng cáoMỗi cặp AdGroupId / AdId là duy nhất trên toàn hệ thống. |
| Mã AdGroupCriterion |
Nhóm quảng cáoMỗi cặp AdGroupId / CriterionId là duy nhất trên toàn hệ thống. |
| Mã CampaignCriterion |
Chiến dịchMỗi 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ịchMỗi cặp CampaignId / AdExtensionId là duy nhất trên toàn hệ thống. |
| ID nguồn cấp dữ liệu |
Toàn cầu |
| Mã mặt hàng trong nguồn cấp dữ liệu |
Toàn cầu |
| Mã thuộc tính nguồn cấp dữ liệu |
Nguồn cấp dữ liệu |
| Mã ánh xạ nguồn cấp dữ liệu |
Toàn cầu |
| ID nhãn |
Toàn cầu |
| Mã danh sách người dùng |
Toàn cầu |
Các quy tắc mã nhận dạng này có thể hữu ích khi bạn thiết kế bộ nhớ cục bộ cho các đối tượng Search Ads 360.
Các kiểu đối tượng
Một số đối tượng có thể được dùng cho nhiều loại thực thể. Nếu đúng như vậy, đối tượng sẽ chứa 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 hoặc quảng cáo địa phương.
Bạn có thể truy cập vào giá trị của loại thông qua trường AdGroupAd.ad.type. Giá trị của thuộc tính này được trả về 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 nối tài nguyên đó và tài nguyên mẹ 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
Một chiến dịch có mã 987654 trong tài khoản Search Ads 360 có mã khách hàng
1234567, có resource_name:
customers/1234567/campaigns/987654
Dịch vụ
Dịch vụ cho phép bạn truy xuất các thực thể và siêu dữ liệu của Search Ads 360. Có 3 loại dịch vụ:
- Dịch vụ tìm kiếm
SearchAds360Service là dịch vụ hợp nhất, duy nhất để truy xuất tất cả đối tượng tài nguyên và số liệu thống kê hiệu suất. Thư viện này cung cấp hai phương thức: Search và SearchStream. Cả hai phương thức đề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 mệ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. Hãy xem bài viết Tạo báo cáo tìm kiếm và Ngôn ngữ truy vấn Search Ads 360 để biết thêm thông tin.- Dịch vụ tại hiện trường
SearchAds360FieldService truy xuất siêu dữ liệu về tài nguyên, chẳng hạn như các thuộc tính có sẵn cho tài nguyên và loại dữ liệu của tài nguyên đó. Bạn có thể yêu cầu danh mục cho các tài nguyên, trường tài nguyên, khoá phân đoạn và chỉ số có sẵn trong phương thức tìm kiếm SearchAds360Service. Hãy xem phần Truy xuất siêu dữ liệu tài nguyên để tìm hiểu thêm.- Dịch vụ dành riêng cho thực thể
Các dịch vụ này cung cấp một phương thức yêu cầu GET để truy xuất một thực thể tài nguyên duy nhất. Điều này rất hữu ích khi kiểm tra cấu trúc của tài nguyên.
Sau đây là một số ví dụ về dịch vụ dành riêng cho pháp nhân:
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-08-29 UTC.
[null,null,["Cập nhật lần gần đây nhất: 2025-08-29 UTC."],[[["\u003cp\u003eThe Search Ads 360 Reporting API uses resources to represent Search Ads 360 entities and services to retrieve them, with the core being the SearchAds360Service for comprehensive data retrieval.\u003c/p\u003e\n"],["\u003cp\u003eSearch Ads 360 accounts are structured hierarchically, starting with the customer resource at the top, followed by campaigns, ad groups, ads, and criteria for targeting.\u003c/p\u003e\n"],["\u003cp\u003eEvery Search Ads 360 object has a unique ID, some globally and others within a specific scope like an ad group or campaign, which is important for data management.\u003c/p\u003e\n"],["\u003cp\u003eResources are identified by resource names, which are strings that combine the resource and its parent resources in a path format, such as customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID.\u003c/p\u003e\n"],["\u003cp\u003eThe Search Ads 360 Reporting API provides services like SearchAds360Service for data retrieval, SearchAds360FieldService for resource metadata, and entity-specific services for detailed information on individual resources like custom columns.\u003c/p\u003e\n"]]],["The Search Ads 360 Reporting API uses resources (entities) and services (retrieval methods). Resources, like `Customer`, `Campaign`, and `AdGroup`, are organized hierarchically. Each object has a unique ID with varying scopes and a `resource_name` for identification. Services include `SearchAds360Service` to retrieve resources and statistics, `SearchAds360FieldService` for metadata, and entity-specific services for individual resource instances. `SearchAds360Service` uses queries with attributes, metrics, predicates, and segments to filter data.\n"],null,["# Search Ads 360 Reporting API structure\n\nThe primary components of the Search Ads 360 Reporting API are *resources* and\n*services*. A resource represents a Search Ads 360 entity and you use a service\nto retrieve Search Ads 360 entities.\n\nObject hierarchy\n----------------\n\nA Search Ads 360 account is a hierarchy of objects.\n\n- The top-level resource of an account is the [customer](/search-ads/reporting/api/reference/fields/v0/customer).\n\n- Each account contains one or more active [campaigns](/search-ads/reporting/api/reference/fields/v0/campaign).\n\n- Each `Campaign` contains one or more [ad groups](/search-ads/reporting/api/reference/fields/v0/ad_group) that group your ads into\n logical collections.\n\n- Each `AdGroup` contains one or more [ad group ads](/search-ads/reporting/api/reference/rpc/ad_group_ad).\n\n- You can attach one or more [`AdGroupCriterion`](/search-ads/reporting/api/reference/fields/v0/ad_group_criterion) or [`CampaignCriterion`](/search-ads/reporting/api/reference/fields/v0/campaign_criterion)\n to an ad group or campaign. Criteria define how ads are triggered.\n\n - There are many [criterion types](), such as, keywords, age ranges, and locations. Criteria defined at the campaign level affect all other resources within the campaign. You can also specify campaign-wide budgets and dates.\n\nResources\n---------\n\nResources represent the entities in your Search Ads 360 account. Example\nresources include [`Customer`](/search-ads/reporting/api/reference/fields/v0/customer), [`Campaign`](/search-ads/reporting/api/reference/fields/v0/campaign) and [`AdGroup`](/search-ads/reporting/api/reference/fields/v0/ad_group).\n\n### Object IDs\n\nEvery object in Search Ads 360 is identified by its own ID. Some IDs are\nglobally unique, that is, across all Search Ads 360 accounts, while others\nare unique only within a confined scope.\n\n| Object ID uniqueness scope ||\n|----------------------|------------------------------------------------------------------------------|\n| Budget ID | Global |\n| Campaign ID | Global |\n| AdGroup ID | Global |\n| Ad ID | Ad Group \u003cbr /\u003e Each `AdGroupId` / `AdId` pair is globally unique. |\n| AdGroupCriterion ID | Ad Group \u003cbr /\u003e Each `AdGroupId` / `CriterionId` pair is globally unique. |\n| CampaignCriterion ID | Campaign \u003cbr /\u003e Each `CampaignId` / `CriterionId` pair is globally unique. |\n| Ad Extensions | Campaign \u003cbr /\u003e Each `CampaignId` / `AdExtensionId` pair is globally unique. |\n| Feed ID | Global |\n| Feed Item ID | Global |\n| Feed Attribute ID | Feed |\n| Feed Mapping ID | Global |\n| Label ID | Global |\n| UserList ID | Global |\n\nThese ID rules can be useful when designing local storage for your Search Ads\n360 objects.\n\n### Object types\n\nSome objects can be used for multiple entity types. If this is the case, the\nobject contains a `type` field that describes its contents. For example,\n[`AdGroupAd`](/search-ads/reporting/api/reference/rpc/ad_group_ad) can refer to a text ad, hotel ad, or local ad.\nYou can access the type value through the [`AdGroupAd.ad.type`](/search-ads/reporting/api/reference/rpc/add_group_ad) field. Its\nvalue is returned in the [`AdType`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.enums#adtypeenum) enum.\n\n### Resource names\n\nEach resource is uniquely identified by a `resource_name` string that\nconcatenates the resource and its parents into a path.\n\nCampaign resource names, for example, have the form: \n\n```scdoc\ncustomers/CUSTOMER_ID/campaigns/CAMPAIGN_ID\n```\n\nA campaign with ID `987654` in the Search Ads 360 account with customer ID\n`1234567`, has the `resource_name`: \n\n```text\ncustomers/1234567/campaigns/987654\n```\n\nServices\n--------\n\nServices let you retrieve your Search Ads 360 entities and metadata. There a\nthree service types:\n\nSearch service\n: [`SearchAds360Service`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchads360service) is the single, unified service for retrieving all\n resource objects and performance statistics. It provides two methods: *`Search`*\n and *`SearchStream`* . Both methods require require a query that specifies the\n resource to query, the resource attributes and performance metrics to retrieve,\n the predicates to use for filtering the request, and the segments to use to\n further break down performance statistics. See [Create search reports](/search-ads/reporting/concepts/search-reports) and [Search\n Ads 360 Query Language](/search-ads/reporting/concepts/query-language) for more\n information.\n\nField service\n: [`SearchAds360FieldService`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchads360fieldservice) retrieves metadata\n about resources, such as, the available attributes for a resource and its data\n type. You can request the catalog for resources, resource fields, segmentation\n keys, and metrics available in the `SearchAds360Service` search methods. See\n [Retrieve resource metadata](/search-ads/reporting/concepts/field-service)\n to learn more.\n\nEntity-specific services\n\n: These services provide a `GET` request method that retrieves a single resource\n instance. This is useful for examining the structure of a resource.\n\n Examples of entity-specific services include:\n\n - [CustomColumnService](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#customcolumnservice) that returns the requested custom column in full detail."]]
