Cómo recuperar objetos

El GoogleAdsService es el servicio unificado de recuperación de objetos y generación de informes de la API de Google Ads. El servicio tiene métodos que permiten hacer lo siguiente:

• Recuperar atributos específicos de objetos
• Recuperar métricas de rendimiento para objetos según un período
• Ordenar objetos según sus atributos
• Usar condiciones para indicar qué objetos deseas que se muestren en la respuesta
• Limitar la cantidad de objetos que se muestran

El GoogleAdsService puede mostrar resultados de dos maneras:

• GoogleAdsService.SearchStream muestra todas las filas en una sola respuesta de transmisión, lo que es más eficiente para conjuntos de resultados grandes (más de 10,000 filas). Esto podría ser más adecuado si tu aplicación por lotes desea descargar la mayor cantidad de datos posible lo más rápido posible.
• GoogleAdsService.Search divide las respuestas grandes en páginas de resultados administrables. Esto podría ser más adecuado si tu aplicación interactiva muestra una página de resultados a la vez.

Obtén más información sobre la paginación en comparación con la transmisión.

Haz una solicitud

El método de búsqueda requiere un SearchGoogleAdsRequest, que consta de los siguientes atributos:

• Un customer_id
• Una query del lenguaje de búsqueda de Google Ads que indica qué recurso consultar, los atributos, los segmentos y las métricas que se recuperarán, y las condiciones que se usarán para restringir qué objetos se muestran
• (GoogleAdsService.Search solo) Un opcional page_token para recuperar el siguiente lote de resultados cuando se usa paginación.

Para obtener más información sobre el lenguaje de búsqueda de Google Ads, consulta la guía del lenguaje de búsqueda de Google Ads.

Procesa una respuesta

El GoogleAdsService muestra una lista de GoogleAdsRow objetos.

Cada GoogleAdsRow representa un objeto que muestra una consulta y consta de un conjunto de atributos que se propagan según los campos solicitados en la cláusula SELECT. Los atributos que no se incluyen en la cláusula SELECT no se propagan en los objetos GoogleAdsRow de la respuesta.

Por ejemplo, aunque un 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 que 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 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 UNKNOWN, pero no puedes mutar el recurso a través de la API. Un ejemplo de esto sería una campaña o un anuncio nuevos que se introducen en la IU, pero que no son compatibles con la versión de la API que estás consultando.

Aquí encontrarás algunos factores que debes tener en cuenta:

• Un recurso con un tipo UNKNOWN puede ser compatible más adelante o permanecer UNKNOWN de forma indefinida.
• Los objetos nuevos con el tipo UNKNOWN pueden aparecer en cualquier momento. Estos objetos son retrocompatibles porque el valor de enumeración ya está disponible. Los recursos se introducen con este cambio a medida que están disponibles para que tengas una vista precisa de tu cuenta. El recurso UNKNOWN puede aparecer debido a actividades nuevas en tu cuenta a través de otras interfaces o cuando un recurso ya no es compatible.
• Los recursos UNKNOWN pueden tener métricas detalladas adjuntas que se pueden consultar.
• Los recursos UNKNOWN suelen ser 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 lo siguiente:

• Instancia del recurso principal especificado en la cláusula FROM
• Valor de cada campo 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

genera una fila por campaña, no una fila por valor distinto del campo campaign.status.