Cómo recuperar objetos

GoogleAdsService es el servicio unificado de recuperación y generación de informes de objetos de la API de Google Ads. El servicio tiene métodos que realizan las siguientes acciones:

• Recupera atributos específicos de objetos.
• Recupera métricas de rendimiento para 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.

El objeto 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 los conjuntos de resultados grandes (más de 10,000 filas). Esto 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 objeto query del lenguaje de consultas 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 los objetos que se devuelven

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

• SearchGoogleAdsStreamRequest (solo para SearchStream):
  • Es un summary_row_setting opcional para solicitar una fila de resumen que contenga métricas agregadas.
• SearchGoogleAdsRequest (solo para 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; si se establece page_size en la solicitud, se genera 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 valor 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

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

Cada GoogleAdsRow representa un objeto que devuelve una búsqueda 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 diferentes atributos y métricas que otra fila del 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 enumeración de UNKNOWN no se admiten por completo en esa versión de la API, mientras que UNSPECIFIED indica que no se estableció un campo de enumeración o que no se solicitó en la cláusula SELECT. Los recursos con un valor de enumeración 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 el tipo UNKNOWN, pero no puedes modificar el recurso a través de la API. Un ejemplo de esto sería un tipo de campaña o de anuncio disponible en la IU que no se admite en la versión de la API que consultas.

A continuación, se incluyen algunos aspectos 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.
• Pueden aparecer objetos nuevos de tipo UNKNOWN en cualquier momento. Estos objetos son compatibles con versiones anteriores porque el valor de 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 generales de tu cuenta.
• Los recursos de UNKNOWN pueden tener métricas detalladas asociadas que se pueden consultar.
• Por lo general, los recursos de UNKNOWN son completamente visibles en la IU de Google Ads.
• En general, los recursos UNKNOWN no se pueden modificar a través de la API.

Segmentación

La respuesta contiene un GoogleAdsRow para cada combinación de los siguientes elementos:

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

Por ejemplo, la respuesta para una búsqueda 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 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 cada valor distinto del campo campaign.status.