Cómo recuperar objetos

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 realizan las siguientes acciones:

  • Recuperar atributos específicos de los objetos
  • Recupera las métricas de rendimiento de los objetos según un período.
  • Ordenar objetos según sus atributos
  • Usa condiciones para indicar qué objetos quieres que se devuelvan en la respuesta.
  • Limita la cantidad de objetos que se devuelven.

GoogleAdsService puede devolver resultados de dos maneras:

  • GoogleAdsService.SearchStream devuelve 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). Se recomienda si tu aplicación descarga conjuntos de resultados completos o procesa filas como una transmisión.
  • GoogleAdsService.Search divide las respuestas grandes en páginas de resultados manejables. Esto es útil 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

GoogleAdsService.SearchStream espera un SearchGoogleAdsStreamRequest, y GoogleAdsService.Search espera un SearchGoogleAdsRequest. Ambos tipos de solicitudes incluyen lo siguiente:

  • A customer_id
  • Un query del 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 usar para restringir los objetos que se devuelven

Según el método, la solicitud también admite campos específicos del método:

  • SearchGoogleAdsStreamRequest (solo SearchStream):
    • Un summary_row_setting opcional para solicitar una fila de resumen que contenga métricas agregadas
  • SearchGoogleAdsRequest (solo Search):
    • Un page_token opcional para recuperar el siguiente lote de resultados cuando se usa la paginación (page_size se fija en 10,000 filas; configurar page_size en la solicitud arroja un error RequestError.PAGE_SIZE_NOT_SUPPORTED)
    • Un mensaje search_settings opcional para configurar return_summary_row, return_total_results_count y omit_results
    • Un booleano validate_only opcional para validar la consulta sin ejecutarla

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

Procesa una respuesta

GoogleAdsService devuelve una lista de objetos GoogleAdsRow (ya sea dentro de lotes SearchGoogleAdsStreamResponse transmitidos o en un SearchGoogleAdsResponse paginado).

Cada GoogleAdsRow representa un objeto que devuelve una consulta y consta de un conjunto de atributos que se completan 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 completa 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 atributos y métricas diferentes 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 y UNSPECIFIED

Los recursos que se devuelven con un valor de tipo enum de UNKNOWN no son totalmente compatibles con esa versión de la API, mientras que UNSPECIFIED indica que no se estableció un campo de tipo enum o que no se solicitó en la cláusula SELECT. Los recursos con un valor de tipo enum UNKNOWN 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 un tipo de campaña o tipo de anuncio disponible en la IU que no se admite en 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 con una versión posterior de la API o permanecer como UNKNOWN de forma indefinida.
  • En cualquier momento, pueden aparecer objetos nuevos con el tipo UNKNOWN. Estos objetos son retrocompatibles porque el valor de la enumeración UNKNOWN está presente en cada enumeración de la API. Los recursos se devuelven con UNKNOWN para que tengas una vista precisa de las métricas de rendimiento general de tu cuenta.
  • Los recursos de UNKNOWN pueden tener métricas detalladas adjuntas que se pueden consultar.
  • Los recursos de UNKNOWN suelen ser completamente visibles en la IU de Google Ads.
  • Por lo general, los recursos UNKNOWN no se pueden mutar a través de la API.

Segmentación

La respuesta contiene un GoogleAdsRow para cada combinación de lo siguiente:

  • Es la instancia del recurso principal especificado en la cláusula FROM.
  • Valor de cada campo segments seleccionado

Por ejemplo, la respuesta de una consulta que selecciona FROM campaign y tiene segments.ad_network_type y segments.date en la cláusula SELECT contiene una fila para cada combinación de los siguientes elementos:

  • 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.

Anterior
Cambiar objetos
Siguiente
Metadatos de recursos