Estructura de la llamada a la API

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 subyacente. Sin embargo, conocer un poco sobre ellas puede ser útil durante las pruebas y la depuración.

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

1. [Preferido] Crea el cuerpo de la solicitud como un búfer de protocolo, envíalo al servidor mediante HTTP/2, deserializa la respuesta en 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 de REST para obtener más información sobre su uso.

Nota: En esta guía, se describen la estructura y los encabezados de transporte comunes a los protocolos gRPC y REST.

Nombres de recursos

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

Punto clave: Consulta la documentación de recursos para conocer todos los recursos compatibles y su representación de ruta de acceso (resource_name). El mismo formato se usa para otros servicios.

ID compuestos

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

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

• AdGroupId de 123 + ~ + AdGroupAdId de 45678 = ID de 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 de la solicitud:

Autorización

Debes incluir un token de acceso OAuth2 con 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 directamente su propia cuenta. Las instrucciones para recuperar un token de acceso se pueden encontrar en la guía de OAuth2. Un token de acceso es válido durante una hora después de que lo adquieras. Cuando venza, actualiza el token de acceso para recuperar uno nuevo. Ten en cuenta que nuestras bibliotecas cliente actualizan automáticamente los tokens vencidos.

token-de-desarrollador

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

login-customer-id

Este es el ID de cliente del cliente autorizado para usar en la solicitud, sin guiones (-). Si el acceso a la cuenta de cliente se realiza a través de una cuenta de administrador, este encabezado es obligatorio y se debe establecer como el ID de cliente de la cuenta de administrador.

Término clave: El cliente operativo es el ID de cliente en la carga útil de la solicitud. Por ejemplo, el cliente operativo en la siguiente solicitud CampaignBudgetService es 1234567890:

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

Configurar el login-customer-id equivale a elegir una cuenta en la IU de Google Ads después de acceder o hacer clic en tu imagen de perfil en la parte superior derecha. Si no incluyes este encabezado, la configuración predeterminada será el cliente operativo.

Nota: Para recuperar la lista de cuentas a las que se puede acceder directamente con tus credenciales de OAuth, emite una solicitud de CustomerService.ListAccessibleCustomers. El login-customer-id no es necesario para este tipo de solicitud y no tiene efecto en la lista de clientes que se muestra.

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 ThirdPartyAppAnalyticsLink. Una vez vinculado, un usuario de la cuenta B puede realizar llamadas a la API con la cuenta A, sujeto a los permisos que proporcione el vínculo. En este caso, los permisos de llamada a la API de la cuenta A están determinados por el vínculo de terceros a la cuenta B, en lugar de la relación de la cuenta de administrador que se utiliza en otras llamadas a la API.

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

• linked-customer-id: La cuenta de estadísticas de aplicaciones de terceros que sube los datos (cuenta B).
• customer-id: Es la cuenta de Google Ads a la que se suben los datos (cuenta A).
• Encabezados 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 encabezados siguientes (o grpc drag-metadata) se muestran con el cuerpo de la respuesta. Te recomendamos que registres estos valores con fines de depuración.

request-id

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