GoogleAdsService
es el servicio unificado de informes y recuperación de objetos de la API de Google Ads. El servicio tiene métodos que hacen lo siguiente:
- Recupera atributos específicos de objetos.
- Recuperar métricas de rendimiento de objetos basadas en un período
- Ordena los objetos según sus atributos.
- Usa condiciones para indicar qué objetos quieres que se muestren en la respuesta.
- Limita la cantidad de objetos que se muestran.
GoogleAdsService
puede mostrar resultados de las siguientes dos maneras:
GoogleAdsService.SearchStream
muestra todas las filas en una sola respuesta de transmisión que es más eficiente para conjuntos de resultados grandes (más de 10,000 filas). Esto puede ser más apropiado si tu aplicación por lotes desea descargar la mayor cantidad de datos posible.GoogleAdsService.Search
divide las respuestas grandes en páginas de resultados manejables. Esto podría ser más apropiado si tu aplicación interactiva muestra una página de resultados a la vez.
Obtén más información sobre la paginación y la transmisión.
Haz una solicitud
El método de búsqueda requiere un SearchGoogleAdsRequest
, que consta de los siguientes atributos:
- A
customer_id
- Un
query
de lenguaje de consulta de Google Ads que indica qué recurso consultar, los atributos, los segmentos y las métricas que se deben recuperar, y las condiciones que se deben utilizar para restringir los objetos que se muestran - (Solo
GoogleAdsService.Search
) Unpage_size
para indicar cuántos objetos se mostrarán en una sola respuesta cuando se use la paginación. - (Solo
GoogleAdsService.Search
) Unpage_token
opcional para recuperar el siguiente lote de resultados cuando se usa la paginación.
Para obtener más información sobre el lenguaje de consulta de Google Ads, revisa la guía del lenguaje de consulta de Google Ads.
Cómo procesar una respuesta
GoogleAdsService
muestra una lista de objetos GoogleAdsRow
.
Cada GoogleAdsRow
representa un objeto que muestra una consulta y consta de un conjunto de atributos que se propagan en función de los campos solicitados en la cláusula SELECT
. Los atributos no incluidos en la cláusula SELECT
no se propagan en los objetos GoogleAdsRow
de la respuesta.
Por ejemplo, aunque ad_group_criterion
tiene un atributo status
, el campo status
del atributo ad_group_criterion
de la fila no se propaga en una respuesta para una consulta en la que la cláusula SELECT
no incluye ad_group_criterion.status
. Del mismo modo, el atributo campaign
de la fila no se propaga si la cláusula SELECT
no incluye ningún campo del recurso campaign
.
Cada GoogleAdsRow
puede tener diferentes atributos y métricas de otra fila en el mismo conjunto de resultados; por lo tanto, las filas deben verse como objetos en lugar de filas fijas de una tabla.
Tipos de enumeración UNKNOWN
Los recursos que se muestran con un tipo de UNKNOWN
no son totalmente compatibles con esa versión de la API. Estos recursos podrían haberse creado a través de otras
interfaces como la IU de Google Ads. Puedes seleccionar métricas cuando un recurso tiene un tipo de UNKNOWN
, pero no puedes mutar el recurso a través de la API. Un ejemplo de esto sería una nueva campaña o un anuncio que se presenta en la IU, pero que no es compatible con la versión de la API que estás consultando.
A continuación, se incluyen algunas consideraciones que debes tener en cuenta:
- Un recurso con un tipo
UNKNOWN
puede ser compatible más adelante o permanecerUNKNOWN
de forma indefinida. - Los objetos nuevos con el tipo
UNKNOWN
pueden aparecer en cualquier momento. Estos objetos son retrocompatibles porque el valor enum ya está disponible. Los recursos se presentan con este cambio a medida que están disponibles para que tengas una visión precisa de tu cuenta. El recursoUNKNOWN
puede aparecer debido a nuevas actividades en tu cuenta a través de otras interfaces o cuando un recurso ya no se admite. - Los recursos
UNKNOWN
pueden tener métricas detalladas adjuntas que se pueden consultar. - Por lo general, los recursos de
UNKNOWN
son completamente visibles en la IU de Google Ads. - Por lo general, los recursos
UNKNOWN
no se pueden mutar.
Segmentación
La respuesta contendrá un GoogleAdsRow
para cada combinación de las siguientes opciones:
- Instancia del recurso principal especificado en la cláusula
FROM
- Valor de cada campo de
segment
seleccionado
Por ejemplo, la respuesta para una consulta que selecciona FROM campaign
y tiene segments.ad_network_type
y segments.date
en la cláusula SELECT
contendrá una fila para cada combinación de lo siguiente:
campaign
segments.ad_network_type
segments.date
Los resultados se segmentan de forma implícita por cada instancia del recurso principal, no por los valores de los campos individuales seleccionados. Por ejemplo:
SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
da como resultado una fila por campaña, no una fila por valor distinto del campo campaign.status
.