Estructura de API

Video: Consulta 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. El La API de Google Ads consta de recursos y servicios. Un recurso representa una cuenta 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 cliente contiene uno o más contactos campañas.

• Cada campaña contiene uno o más grupos de anuncios, que se para agrupar los anuncios en colecciones lógicas.

• Un anuncio del grupo de anuncios representa un anuncio que en ejecución. Excepto en el caso de las campañas de aplicaciones que solo pueden tener un anuncio de un grupo de anuncios por anuncio grupo, cada grupo de anuncios contiene uno o más anuncios del grupo de anuncios.

Puedes adjuntar uno o más archivos AdGroupCriterion o CampaignCriterion a un grupo de anuncios o campaña. Estos representan los 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 afectará a todos los demás recursos dentro de la campaña. También puedes especificar presupuestos y fechas para toda la campaña.

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

Recursos

Los recursos representan las entidades que se encuentran dentro de tu cuenta de Google Ads. Campaign y AdGroup son dos ejemplos de recursos.

IDs de objeto

Cada objeto en Google Ads se identifica con su propio ID. Algunos de estos IDs son son únicas a nivel global en todas las cuentas de Google Ads, mientras que otras son únicas solo en un alcance limitado.

ID de objeto	Alcance de la singularidad	¿Es único a nivel global?
ID de presupuesto	Global	Sí
ID de la campaña	Global	Sí
ID del grupo de anuncios	Global	Sí
ID del anuncio	Grupo de anuncios	No, pero el par (AdGroupId, AdId) es único a nivel global
ID de AdGroupCriterion	Grupo de anuncios	No, pero el par (AdGroupId, CriterionId) es único a nivel global
ID de criterio de campaña	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 tu cuenta de Google Ads. objetos.

Algunos objetos se pueden usar para varios tipos de entidades. En esos casos, el objeto contiene un campo type que describe su contenido. Por ejemplo: AdGroupAd puede hacer referencia a un objeto, como un anuncio de texto. anuncio de hotel o anuncio local. Se puede acceder a este valor a través del AdGroupAd.ad.type y muestra un valor en el Enum AdType.

Nombres de recursos

Cada recurso se identifica de forma única con una cadena resource_name, que concatena el recurso y sus elementos superiores en una ruta de acceso. Por ejemplo, la campaña los nombres de los recursos 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, la resource_name sería la siguiente:

customers/1234567/campaigns/987654

Servicios

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

Modificar (mutar) objetos

Estos servicios modifican instancias de un tipo de recurso asociado mediante un mutate para cada solicitud. También proporcionan una solicitud get que recupera un solo recurso. lo que puede ser útil para examinar la estructura de un recurso.

Punto clave: Las solicitudes de get se limitan a 1,000 por día. Para la mayoría de los casos de uso casos, debes solicitar informes usando GoogleAdsService.

Ejemplos de servicios:

• CustomerService para modificar clientes.

• CampaignService para modificar campañas.

• AdGroupService para modificar grupos de anuncios.

Cada solicitud mutate debe incluir los objetos operation correspondientes. Para ejemplo, el método CampaignService.MutateCampaigns espera uno o más instancias de CampaignOperation. Consulta Cómo cambiar e inspeccionar objetos de un una discusión detallada de las operaciones.

Mutaciones simultáneas

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

La API no proporciona una manera de bloquear un objeto antes de actualizarlo. si dos fuentes mutar un objeto simultáneamente, la API genera un DatabaseError.CONCURRENT_MODIFICATION_ERROR

Mutaciones asíncronas en comparación con síncronos

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

Un enfoque alternativo consiste en mutar objetos de forma asíncrona utilizando BatchJobService, que realiza lotes de las operaciones en múltiples servicios sin esperar a su finalización. Una vez por el trabajo por lotes, los servidores de la API de Google Ads ejecutan operaciones de forma asíncrona liberar procesos para realizar otras operaciones. Puedes verificar periódicamente el el estado del trabajo para completarlo.

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

Validación de modificación

La mayoría de las solicitudes de mutación pueden validarse sin ejecutar la llamada con datos reales. Puedes probar la solicitud para ver si faltan parámetros y son incorrectos de campo sin ejecutar la operación.

Para usar esta función, establece el campo booleano validate_only opcional de la solicitud como true La solicitud será validada por completo como si fuera a pero se omite la ejecución final. Si no se encuentran errores, se abrirá un espacio respuesta. Si la validación falla, los mensajes de error en la respuesta para indicar los puntos de falla.

validate_only es particularmente útil para probar anuncios para políticas comunes. incumplimientos. Los anuncios se rechazan automáticamente si infringen políticas como las siguientes: palabras, puntuación, mayúsculas o longitud específicas. Un solo anuncio inapropiado podría hacer que un lote completo falle. Probar un anuncio nuevo en una validate_only puede revelar dichos incumplimientos. Consulta el ejemplo de código para manejar de incumplimientos de política para ver esto en acción.

Obtener objetos y estadísticas de rendimiento

GoogleAdsService es la única función unificada para recuperar objetos y estadísticas de rendimiento.

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

Cómo recuperar metadatos

GoogleAdsFieldService recupera metadatos acerca de los recursos en la API de Google Ads, tales como los atributos disponibles para una recurso y su tipo de datos.

Este servicio proporciona la información necesaria para crear una consulta para GoogleAdsService Para mayor comodidad, la información devuelta por GoogleAdsFieldService también está disponible en la documentación de referencia de campos.