Estructura de API

Video: Mira la charla sobre servicios y recursos del taller de 2019

En esta guía, se presentan los componentes principales de la API de Google Ads. La API de Google Ads consta de recursos y servicios. Un recurso representa una entidad de Google Ads, mientras que los servicios recuperan y manipulan entidades de Google Ads.

Jerarquía de objetos

Una cuenta de Google Ads se puede ver como 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 se usan para agrupar sus anuncios en colecciones lógicas.

  • Cada AdGroup contiene uno o más anuncios del grupo de anuncios. Un AdGroupAd representa un anuncio que estás publicando.

Puede adjuntar uno o más elementos AdGroupCriterion o CampaignCriterion a un grupo de anuncios o a una campaña. Representan criterios que 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.

Por último, puedes adjuntar extensiones a nivel de la cuenta, la campaña o el grupo de anuncios. Las extensiones le permiten proporcionar información adicional a sus anuncios, como el número de teléfono, la dirección o las promociones.

Recursos

Los recursos representan las entidades dentro de su cuenta de Google Ads. Campaign y AdGroup son dos ejemplos de recursos.

ID de objeto

Cada objeto en Google Ads se identifica por su propio ID. Algunos de estos ID son únicos a nivel global en todas las cuentas de Google Ads, mientras que otros son únicos solo dentro de un alcance limitado.

ID de objeto Alcance de la exclusividad ¿Es globalmente único?
ID de presupuesto Global Sí
ID de la campaña Global Sí
ID del grupo de anuncios Global Sí
ID del anuncio Ad Group No, pero el par (AdGroupId, AdId) es único a nivel global
ID del grupo de anuncios Ad Group No, pero el par (AdGroupId, CriterionId) es único a nivel global
ID de CampaignCriterion Campaña No, pero el par (CampaignId, CriterionId) es único a nivel global
Extensiones de anuncios Campaña No, pero el par (CampaignId, AdExtensionId) es único a nivel global
ID del feed Global Sí
ID de elemento del feed Global Sí
ID del atributo del feed Feed No
ID de asignación de feeds Global Sí
ID de etiqueta Global Sí
ID de lista de usuarios Global Sí

Estas reglas de ID pueden ser útiles a la hora de diseñar el almacenamiento local para tus objetos de Google Ads.

Algunos objetos se pueden usar para varios tipos de entidades. En estos casos, el objeto incluye un campo type que describe su contenido. Por ejemplo, AdGroupAd puede hacer referencia a un anuncio de texto, de anuncio de hoteles, de anuncio local, etc. Se puede acceder a este valor a través del campo AdGroupAd.ad.type y se muestra un valor en la enumeración AdType.

Nombres de recursos

Cada recurso se identifica de forma única con una string resource_name, que concatena el recurso y sus elementos superiores en una ruta de acceso. Por ejemplo, los nombres de los recursos de campaña tienen el siguiente formato:

customers/customer_id/campaigns/campaign_id

Por lo tanto, para una campaña con el ID 987654 en la cuenta de Google Ads con ID de cliente 1234567, sería resource_name:

customers/1234567/campaigns/987654

Servicios

Los servicios le permiten recuperar y modificar sus entidades de Google Ads. Existen tres tipos de servicios: modificación, recuperación de objetos y estadísticas, y servicios de recuperación de metadatos.

Modificar (mutar) objetos

Estos servicios modifican instancias de un tipo de recurso asociado con una solicitud mutate. También proporciona una solicitud get que recupera una sola instancia de recurso, que puede ser útil para examinar la estructura de un recurso.

Ejemplos de servicios:

Cada solicitud mutate debe incluir los objetos operation correspondientes. Por ejemplo, el método CampaignService.MutateCampaigns espera una o más instancias de CampaignOperation. Consulta Cómo inspeccionar y cambiar objetos para obtener una explicación detallada de las operaciones.

Mutaciones simultáneas

Un objeto de Google Ads no puede ser modificado en simultáneo por más de una fuente. Esto podría causar errores si varios usuarios actualizan el mismo objeto con tu app o si mutas objetos de Google Ads en paralelo con varios subprocesos. Esto incluye actualizar el objeto de varios subprocesos en la misma aplicación o desde diferentes aplicaciones (por ejemplo, tu app y una sesión simultánea de IU de Google Ads).

La API no proporciona una forma de bloquear un objeto antes de la actualización; si dos fuentes intentan mutar simultáneamente un objeto, la API genera un DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Mutaciones síncronas y asíncronas

Los métodos de modificación de la API de Google Ads son síncronos. Las llamadas a la API muestran una respuesta solo después de que los objetos mutan, lo que requiere que esperes una respuesta a cada solicitud. Si bien este enfoque es relativamente sencillo de codificar, podría afectar de forma negativa el balanceo de cargas y los recursos desperdiciados si los procesos se ven obligados a esperar que las llamadas se completen.

Un enfoque alternativo es mutar objetos de forma asíncrona con BatchJobService, que realiza lotes de operaciones en varios servicios sin esperar a que se completen. Una vez que se envía un trabajo por lotes, los servidores de la API de Google Ads ejecutan operaciones de manera asíncrona, lo que libera procesos para llevar a cabo otras operaciones. Puedes verificar de forma periódica el estado del trabajo para completarlo.

Consulta la Guía de procesamiento por lotes para obtener más información sobre el procesamiento asíncrono.

Modificar la validación

La mayoría de las solicitudes de mutación se pueden validar sin ejecutar la llamada con los datos reales. Puedes probar la solicitud de parámetros faltantes y valores de campo incorrectos sin ejecutar la operación.

Para usar esta función, establece el campo booleano validate_only opcional de la solicitud en true. Luego, la solicitud se validaría por completo como si fuera a ejecutarse, pero se omitirá la ejecución final. Si no se encuentran errores, se muestra una respuesta vacía. Si la validación falla, los mensajes de error en la respuesta indicarán los puntos de falla.

validate_only es especialmente útil para probar anuncios en busca de incumplimientos comunes de políticas. Los anuncios se rechazan automáticamente si infringen políticas, como tener palabras, signos de puntuación, mayúsculas o longitud específicos. Un solo anuncio inapropiado puede hacer que falle un lote completo. Probar un anuncio nuevo dentro de una solicitud validate_only puede revelar esos incumplimientos. Consulta el ejemplo de código para manejar errores de incumplimiento de política a fin de ver cómo funciona.

Obtén objetos y estadísticas de rendimiento

GoogleAdsService es el único servicio unificado para recuperar objetos y estadísticas de rendimiento.

Todas las solicitudes Search y SearchStream de GoogleAdsService requieren una consulta que especifique el recurso que se desea consultar, los atributos del recurso y las métricas de rendimiento que se recuperarán, los predicados que se usarán a fin de filtrar la solicitud y los segmentos que se usarán para desglosar aún más las estadísticas de rendimiento. Para obtener más información sobre el formato de las consultas, visita la Guía de lenguaje de consulta de Google Ads.

Recuperar metadatos

GoogleAdsFieldService recupera metadatos sobre los recursos de la API de Google Ads, como los atributos disponibles para un recurso y su tipo de datos.

Este servicio brinda información que necesitarás para construir una consulta a GoogleAdsService. Para mayor comodidad, la información que muestra GoogleAdsFieldService también está disponible en la documentación de referencia de campos.

Anterior
Descripción general
Siguiente
Relaciones de la entidad