A nova API Search Ads 360 Reporting já está disponível. Participe do grupo do Google
searchads-api-announcements para ficar por dentro das próximas melhorias e versões.
Estrutura da API Reporting do Search Ads 360
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Os principais componentes da API Search Ads 360 Reporting são recursos e serviços. Um recurso representa uma entidade do Search Ads 360, e você usa um serviço para recuperá-las.
Hierarquia de objetos
Uma conta do Search Ads 360 é uma hierarquia de objetos.
O recurso de nível superior de uma conta é o cliente.
Cada conta contém uma ou mais campanhas ativas.
Cada Campaign contém um ou mais grupos de anúncios que agrupam seus anúncios em
coleções lógicas.
Cada AdGroup contém um ou mais anúncios do grupo de anúncios.
É possível anexar um ou mais AdGroupCriterion ou CampaignCriterion
a um grupo de anúncios ou campanha. Os critérios definem como os anúncios são acionados.
- Existem muitos tipos de critério, como palavras-chave, faixas etárias e locais. Os critérios definidos no nível da campanha afetam todos os outros recursos dela. Também é possível especificar orçamentos e datas para toda a campanha.
Recursos
Os recursos representam as entidades na sua conta do Search Ads 360. Os recursos
de exemplo incluem Customer, Campaign e AdGroup.
IDs dos objetos
Cada objeto no Search Ads 360 é identificado por seu próprio código. Alguns IDs são exclusivos em nível global, ou seja, em todas as contas do Search Ads 360, enquanto outros são exclusivos apenas em um escopo limitado.
| Escopo de exclusividade do ID do objeto |
| ID do orçamento |
Global |
| ID da campanha |
Global |
| ID do Grupo de anúncios |
Global |
| ID do anúncio |
Grupo de anúnciosCada par AdGroupId / AdId é globalmente exclusivo. |
| AdGroupCriterion ID |
Grupo de anúnciosCada par de AdGroupId / CriterionId é globalmente exclusivo. |
| CampaignCriterion ID |
CampanhaCada par CampaignId / CriterionId é globalmente exclusivo. |
| Extensões de anúncio |
CampanhaCada par CampaignId / AdExtensionId é globalmente exclusivo. |
| ID de feed |
Global |
| Feed Item ID |
Global |
| Feed Attribute ID |
Feed |
| Feed Mapping ID |
Global |
| ID do rótulo |
Global |
| ID da lista de usuários |
Global |
Essas regras de ID podem ser úteis ao projetar o armazenamento local para seus objetos do Search Ads 360.
Tipos de objeto
Alguns objetos podem ser usados para vários tipos de entidade. Nesse caso, o
objeto contém um campo type que descreve o conteúdo. Por exemplo,
AdGroupAd pode se referir a um anúncio de texto, de hotel ou local.
É possível acessar o valor do tipo pelo campo AdGroupAd.ad.type. O
valor é retornado no tipo enumerado AdType.
Nomes de recursos
Cada recurso é identificado exclusivamente por uma string resource_name que
concatena o recurso e os pais em um caminho.
Os nomes dos recursos da campanha, por exemplo, têm o seguinte formato:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Uma campanha com o ID 987654 na conta do Search Ads 360 com o ID de cliente 1234567 tem o resource_name:
customers/1234567/campaigns/987654
Serviços
Com os serviços, você pode recuperar as entidades e os metadados do Search Ads 360. Há
três tipos de serviço:
- SearchService
SearchAds360Service é o serviço unificado para recuperar todos
os objetos de recursos e estatísticas de desempenho. Ele oferece dois métodos: Search
e SearchStream. Ambos os métodos exigem uma consulta que especifique o recurso a ser consultado, os atributos do recurso e as métricas de desempenho a serem recuperadas, os predicados a serem usados para filtrar a solicitação e os segmentos a serem usados para detalhar ainda mais as estatísticas de desempenho. Consulte Criar relatórios de pesquisa e Linguagem de consulta do Search Ads 360 para mais informações.- Serviço de campo
SearchAds360FieldService recupera metadados
sobre recursos, como os atributos disponíveis para um recurso e o tipo
de dados. É possível solicitar o catálogo de recursos, campos de recursos, chaves de segmentação e métricas disponíveis nos métodos de pesquisa SearchAds360Service. Consulte
Extrair metadados de recursos
para saber mais.- Serviços específicos da entidade
Esses serviços fornecem um método de solicitação GET que recupera uma única instância
de recurso. Isso é útil para examinar a estrutura de um recurso.
Confira alguns exemplos de serviços específicos da entidade:
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-08-29 UTC.
[null,null,["Última atualização 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."]]
