La nueva API de informes de Search Ads 360 ya está disponible. Únete al grupo de Google
searchads-api-announcements para mantenerte al tanto de las próximas mejoras y lanzamientos.
Estructura de la API de informes de Search Ads 360
Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
Los componentes principales de la API de Search Ads 360 Reporting son los recursos y los servicios. Un recurso representa una entidad de Search Ads 360 y usas un servicio para recuperar entidades de Search Ads 360.
Jerarquía de objetos
Una cuenta de Search Ads 360 es una jerarquía de objetos.
El recurso de nivel superior de una cuenta es el cliente.
Cada cuenta contiene una o más campañas activas.
Cada Campaign contiene uno o más grupos de anuncios que agrupan tus anuncios en colecciones lógicas.
Cada AdGroup contiene uno o más anuncios del grupo de anuncios.
Puedes adjuntar uno o más AdGroupCriterion o CampaignCriterion a un grupo de anuncios o una campaña. Los criterios definen cómo se activan los anuncios.
- Existen muchos tipos de criterios, como palabras clave, rangos de edad y ubicaciones. Los criterios definidos a nivel de la campaña afectan a todos los demás recursos de la campaña. También puedes especificar presupuestos y fechas para toda la campaña.
Recursos
Los recursos representan las entidades de tu cuenta de Search Ads 360. Entre los recursos de ejemplo, se incluyen Customer, Campaign y AdGroup.
IDs de objetos
Cada objeto de Search Ads 360 se identifica con su propio ID. Algunos IDs son únicos a nivel global, es decir, en todas las cuentas de Search Ads 360, mientras que otros son únicos solo dentro de un alcance limitado.
| Alcance de unicidad del ID de objeto |
| ID de presupuesto |
Global |
| ID de la campaña |
Global |
| ID del grupo de anuncios |
Global |
| ID del anuncio |
Grupo de anunciosCada par AdGroupId / AdId es único a nivel global. |
| ID de AdGroupCriterion |
Grupo de anunciosCada par AdGroupId / CriterionId es único a nivel global. |
| ID de criterio de campaña |
CampañaCada par CampaignId / CriterionId es único a nivel global. |
| Extensiones de anuncios |
CampañaCada par CampaignId / AdExtensionId es único a nivel global. |
| ID del feed |
Global |
| ID del elemento del feed |
Global |
| ID del atributo del feed |
Feed |
| ID de asignación de feeds |
Global |
| ID de etiqueta |
Global |
| ID de lista de usuarios |
Global |
Estas reglas de ID pueden ser útiles cuando diseñas el almacenamiento local para tus objetos de Search Ads 360.
Tipos de objetos
Algunos objetos se pueden usar para varios tipos de entidades. Si este es el caso, el objeto contiene un campo type que describe su contenido. Por ejemplo, AdGroupAd puede hacer referencia a un anuncio de texto, un anuncio de hotel o un anuncio local.
Puedes acceder al valor del tipo a través del campo AdGroupAd.ad.type. Su valor se muestra en la enumeración AdType.
Nombres de recursos
Cada recurso se identifica de forma única mediante una cadena resource_name que concatena el recurso y sus elementos superiores en una ruta de acceso.
Por ejemplo, los nombres de los recursos de la campaña tienen el siguiente formato:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Una campaña con el ID 987654 en la cuenta de Search Ads 360 con el ID de cliente 1234567 tiene el resource_name:
customers/1234567/campaigns/987654
Servicios
Los servicios te permiten recuperar tus entidades y metadatos de Search Ads 360. Existen tres tipos de servicios:
- Servicio de búsqueda
SearchAds360Service es el servicio único y unificado para recuperar todos los objetos de recursos y las estadísticas de rendimiento. Proporciona dos métodos: Search y SearchStream. Ambos métodos requieren una consulta que especifique el
recurso que se consultará, los atributos del recurso y las métricas de rendimiento que se recuperarán,
los predicados que se usarán para filtrar la solicitud y los segmentos que se usarán para
desglosar aún más las estadísticas de rendimiento. Consulta Cómo crear informes de búsqueda y Lenguaje de consulta de Search Ads 360 para obtener más información.- Servicio de campo
SearchAds360FieldService recupera metadatos sobre los recursos, como los atributos disponibles para un recurso y su tipo de datos. Puedes solicitar el catálogo de recursos, campos de recursos, claves de segmentación y métricas disponibles en los métodos de búsqueda de SearchAds360Service. Consulta Cómo recuperar metadatos de recursos para obtener más información.- Servicios específicos para entidades
Estos servicios proporcionan un método de solicitud GET que recupera una sola instancia de recurso. Esto es útil para examinar la estructura de un recurso.
Estos son algunos ejemplos de servicios específicos de entidades:
Salvo que se indique lo contrario, el contenido de esta página está sujeto a la licencia Atribución 4.0 de Creative Commons, y los ejemplos de código están sujetos a la licencia Apache 2.0. Para obtener más información, consulta las políticas del sitio de Google Developers. Java es una marca registrada de Oracle o sus afiliados.
Última actualización: 2025-08-29 (UTC)
[null,null,["Última actualización: 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."]]
