Новый API отчетов Search Ads 360 теперь доступен. Присоединяйтесь к группе Google
searchads-api-announcements , чтобы быть в курсе предстоящих улучшений и выпусков.
Структура API отчетов Search Ads 360
Оптимизируйте свои подборки
Сохраняйте и классифицируйте контент в соответствии со своими настройками.
Основными компонентами Search Ads 360 Reporting API являются ресурсы и сервисы . Ресурс представляет собой объект Search Ads 360, и вы используете службу для получения объектов Search Ads 360.
Иерархия объектов
Аккаунт Search Ads 360 – это иерархия объектов.
Ресурсом верхнего уровня аккаунта является клиент .
Каждая учетная запись содержит одну или несколько активных кампаний .
Каждая Campaign содержит одну или несколько групп объявлений , которые группируют ваши объявления в логические коллекции.
Каждая AdGroup содержит одно или несколько объявлений группы объявлений .
Вы можете прикрепить один или несколько AdGroupCriterion или CampaignCriterion к группе объявлений или кампании. Критерии определяют, как запускаются объявления.
- Существует множество типов критериев , таких как ключевые слова, возрастные диапазоны и местоположения. Критерии, определенные на уровне кампании, влияют на все остальные ресурсы в кампании. Вы также можете указать бюджеты и даты для всей кампании.
Ресурсы
Ресурсы представляют собой объекты в вашем аккаунте Search Ads 360. Примеры ресурсов: Customer , Campaign и AdGroup .
Идентификаторы объектов
Каждый объект в Search Ads 360 идентифицируется своим собственным идентификатором. Некоторые идентификаторы уникальны во всем мире, то есть во всех учетных записях Search Ads 360, тогда как другие уникальны только в ограниченной области.
| Область уникальности идентификатора объекта |
|---|
| Идентификатор бюджета | Глобальный |
| Идентификатор кампании | Глобальный |
| Идентификатор группы объявлений | Глобальный |
| Идентификатор объявления | Группа объявлений Каждая пара AdGroupId / AdId уникальна в глобальном масштабе. |
| Идентификатор AdGroupCriterion | Группа объявлений Каждая пара AdGroupId / CriterionId уникальна в глобальном масштабе. |
| Идентификатор критерия кампании | Кампания Каждая пара CampaignId / CriterionId уникальна в глобальном масштабе. |
| Расширения объявлений | Кампания Каждая пара CampaignId / AdExtensionId уникальна в глобальном масштабе. |
| Идентификатор фида | Глобальный |
| Идентификатор элемента фида | Глобальный |
| Идентификатор атрибута фида | Кормить |
| Идентификатор сопоставления фида | Глобальный |
| Идентификатор этикетки | Глобальный |
| Идентификатор списка пользователей | Глобальный |
Эти правила идентификаторов могут быть полезны при проектировании локального хранилища для объектов Поисковой рекламы 360.
Типы объектов
Некоторые объекты могут использоваться для нескольких типов сущностей. В этом случае объект содержит поле type , описывающее его содержимое. Например, AdGroupAd может относиться к текстовому объявлению, объявлению отеля или местному объявлению. Доступ к значению типа можно получить через поле AdGroupAd.ad.type . Его значение возвращается в перечислении AdType .
Имена ресурсов
Каждый ресурс уникально идентифицируется строкой resource_name , которая объединяет ресурс и его родителей в путь.
Например, имена ресурсов кампании имеют вид:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Кампания с идентификатором 987654 в аккаунте Search Ads 360 с идентификатором клиента 1234567 имеет resource_name :
customers/1234567/campaigns/987654
Услуги
Сервисы позволяют получать объекты и метаданные Search Ads 360. Существует три типа услуг:
- Служба поиска
-
SearchAds360Service — это единый унифицированный сервис для получения всех объектов ресурсов и статистики производительности. Он предоставляет два метода: Search и SearchStream . Для обоих методов требуется запрос, в котором указывается запрашиваемый ресурс, извлекаемые атрибуты ресурса и показатели производительности, предикаты, используемые для фильтрации запроса, и сегменты, которые следует использовать для дальнейшего разбивки статистики производительности. Дополнительные сведения см. в разделах «Создание поисковых отчетов» и «Язык запросов Search Ads 360» . - Выездное обслуживание
-
SearchAds360FieldService извлекает метаданные о ресурсах, например доступные атрибуты ресурса и его тип данных. Вы можете запросить каталог ресурсов, полей ресурсов, ключей сегментации и показателей, доступных в методах поиска SearchAds360Service . Дополнительные сведения см. в разделе Получение метаданных ресурса . - Специализированные услуги
Эти службы предоставляют метод запроса GET , который извлекает один экземпляр ресурса. Это полезно для изучения структуры ресурса.
Примеры услуг, специфичных для организации, включают:
- CustomColumnService , который возвращает запрошенный настраиваемый столбец с подробной информацией.
Если не указано иное, контент на этой странице предоставляется по лицензии Creative Commons "С указанием авторства 4.0", а примеры кода – по лицензии Apache 2.0. Подробнее об этом написано в правилах сайта. Java – это зарегистрированный товарный знак корпорации Oracle и ее аффилированных лиц.
Последнее обновление: 2025-08-29 UTC.
[null,null,["Последнее обновление: 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."]]
