Search Ads 360 Reporting API 结构
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
Search Ads 360 Reporting API 的主要组成部分是资源和服务。资源表示 Search Ads 360 实体，您可以使用服务检索 Search Ads 360 实体。
对象层次结构
Search Ads 360 账号是一种层次结构的对象。
资源
资源代表 Search Ads 360 账号中的实体。示例资源包括 Customer、Campaign 和 AdGroup。
对象 ID
Search Ads 360 中的每个对象都由其自身的 ID 进行标识。有些 ID 在全球范围内是唯一的，也就是说，在所有 Search Ads 360 账号中都是唯一的；而有些 ID 仅在特定范围内是唯一的。
| 对象 ID 唯一性范围 |
| 预算 ID |
全球 |
| 广告系列 ID |
全球 |
| 广告组 ID |
全球 |
| 广告 ID |
广告组每个 AdGroupId / AdId 对都是全局唯一的。 |
| AdGroupCriterion ID |
广告组每个 AdGroupId / CriterionId 对都是全局唯一的。 |
| CampaignCriterion ID |
广告系列每个 CampaignId / CriterionId 对都是全局唯一的。 |
| 广告附加信息 |
广告系列每个 CampaignId / AdExtensionId 对都是全局唯一的。 |
| Feed ID |
全球 |
| Feed Item ID |
全球 |
| Feed Attribute ID |
动态 |
| Feed Mapping ID |
全球 |
| 标签 ID |
全球 |
| 用户名单 ID |
全球 |
在为 Search Ads 360 对象设计本地存储空间时，这些 ID 规则会很有用。
对象类型
某些对象可用于多种实体类型。如果是这种情况，该对象将包含一个用于描述其内容的 type 字段。例如，AdGroupAd 可以是指文字广告、酒店广告或本地广告。您可以通过 AdGroupAd.ad.type 字段访问类型值。其值会在 AdType 枚举中返回。
资源名称
每个资源都由一个 resource_name 字符串唯一标识，该字符串将资源及其父项连接到路径中。
例如，广告系列资源名称的格式如下：
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
客户 ID 为 1234567 的 Search Ads 360 账号中，ID 为 987654 的广告系列具有以下 resource_name：
customers/1234567/campaigns/987654
服务
借助服务，您可以检索 Search Ads 360 实体和元数据。服务有三种类型：
- 搜索服务
SearchAds360Service 是一项统一的服务，用于同时检索所有资源对象和效果统计信息。它提供了两种方法：Search 和 SearchStream。这两种方法都需要一个查询，以指定要查询的资源、要检索的资源属性和效果指标、用于过滤请求的谓词，以及用于进一步细分效果统计信息的细分。如需了解详情，请参阅创建搜索报告和 Search Ads 360 查询语言。- 现场服务
SearchAds360FieldService 用于检索有关资源的元数据，例如资源的可用属性及其数据类型。您可以请求 SearchAds360Service 搜索方法中提供的资源、资源字段、细分键和指标的目录。如需了解详情，请参阅检索资源元数据。- 特定于实体的服务
这些服务提供了可检索单个资源实例的 GET 请求方法。这对于检查资源的结构非常有用。
实体专用服务的示例包括：
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-29。
[null,null,["最后更新时间 (UTC)：2025-08-29。"],[[["\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."]]
