Estructura de la llamada a la API

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

En esta guía, se describe la estructura común de todas las llamadas a la API.

Si usas una biblioteca cliente para interactuar con la API, no tendrás que preocuparte por los detalles de la solicitud subyacentes. Sin embargo, conocer un poco sobre ellas puede resultar útil cuando realizas pruebas y depuraciones.

La API de Google Ads es una API de gRPC con vinculaciones de REST. Esto significa que existen dos maneras de realizar llamadas a la API.

  1. [Preferred] Crea el cuerpo de la solicitud como un búfer de protocolo, envíalo al servidor mediante HTTP/2, deserializa la respuesta a un búfer de protocolo y, luego, interpreta los resultados. La mayor parte de nuestra documentación describe el uso de gRPC.

  2. [Opcional] Crea el cuerpo de la solicitud como un objeto JSON, envíalo al servidor mediante HTTP 1.1, deserializa la respuesta como un objeto JSON y, luego, interpreta los resultados. Consulta la guía de la interfaz REST para obtener más información.

Nombres de recursos

La mayoría de los objetos de la API se identifican por sus strings de nombres de recursos. Estas strings también sirven como URL cuando se usa la interfaz REST. Consulta la estructura de nombres de los recursos de la interfaz de REST para conocer su estructura.

ID compuestos

Si el ID de un objeto no es único a nivel global, se crea un ID compuesto para ese objeto anteponiendo su ID superior y una virgulilla (~).

Por ejemplo, dado que un ID de anuncio de un grupo de anuncios no es único a nivel global, le antepón su ID de objeto superior (grupo de anuncios) para crear un ID compuesto único:

  • AdGroupId de 123 + ~ + AdGroupAdId de 45678 = ID del anuncio del grupo de anuncios compuesto de 123~45678.

Encabezados de la solicitud

Estos son los encabezados HTTP (o metadatos de grpc) que acompañan al cuerpo en la solicitud:

Autorización

Debes incluir un token de acceso de OAuth2 en forma de Authorization: Bearer YOUR_ACCESS_TOKEN que identifique una cuenta de administrador que actúa en nombre de un cliente o un anunciante que administra su propia cuenta directamente. Las instrucciones para recuperar un token de acceso se encuentran en la guía de OAuth2. Un token de acceso es válido por una hora después de adquirirlo; cuando vence, actualiza el token de acceso para recuperar uno nuevo. Ten en cuenta que nuestras bibliotecas cliente actualizan de manera automática los tokens vencidos.

token de desarrollador

Un token de desarrollador es una string de 22 caracteres que identifica de forma única a un desarrollador de la API de Google Ads. Una string de token de desarrollador de ejemplo es ABcdeFGH93KL-NOPQ_STUv. El token de desarrollador debe incluirse en el formato developer-token : ABcdeFGH93KL-NOPQ_STUv.

id-cliente-acceso

Este es el ID de cliente del cliente autorizado que se usará en la solicitud, sin guiones (-). Si tu acceso a la cuenta de cliente es a través de una cuenta de administrador, este encabezado es obligatorio y debe establecerse con el ID de cliente de la cuenta de administrador.

https://googleads.googleapis.com/v11/customers/1234567890/campaignBudgets:mutate

Configurar login-customer-id es equivalente a elegir una cuenta en la IU de Google Ads después de acceder o hacer clic en la imagen de perfil que se encuentra en la parte superior derecha. Si no incluyes este encabezado, se usará de forma predeterminada el cliente operativo.

ID de cliente vinculado

Solo los proveedores de estadísticas de aplicaciones de terceros utilizan este encabezado cuando suben conversiones a una cuenta de Google Ads vinculada.

Considera la situación en la que los usuarios de la cuenta A proporcionan acceso de lectura y edición a sus entidades para la cuenta B a través de una ThirdPartyAppAnalyticsLink. Una vez que se vincula, un usuario de la cuenta B puede realizar llamadas a la API en la cuenta A, sujeto a los permisos que proporciona el vínculo. En este caso, el permiso de llamada a la API A está determinado por el vínculo de terceros a la cuenta B, en lugar de la relación de cuenta de administrador que se usa en otras llamadas a la API.

El proveedor de estadísticas de apps de terceros realiza una llamada a la API de la siguiente manera:

  • linked-customer-id: Es la cuenta de estadísticas de apps de terceros que sube los datos (cuenta B).
  • customer-id: La cuenta de Google Ads a la que se suben los datos (cuenta A).
  • Encabezado login-customer-id y Authorization: Es una combinación de valores para identificar a un usuario que tiene acceso a la cuenta B.

Encabezados de respuesta

Los siguientes encabezados (o grpc back-metadata) se muestran con el cuerpo de la respuesta. Te recomendamos que registres estos valores para fines de depuración.

ID de solicitud

El request-id es una string que identifica de forma única esta solicitud.