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 necesitarás conocer los detalles de la solicitud subyacente. Sin embargo, tener conocimientos sobre la estructura de las llamadas a la API puede ser útil cuando se realizan pruebas y se depura el código.

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

Preferida:

1. Crea el cuerpo de la solicitud como un búfer de protocolo.

2. Envíalo al servidor con HTTP/2.

3. Deserializa la respuesta a un búfer de protocolo.

4. Interpreta los resultados.

En la mayor parte de nuestra documentación, se describe el uso de gRPC.

Opcional:

1. Crea el cuerpo de la solicitud como un objeto JSON.

2. Envíalo al servidor con HTTP 1.1.

3. Deserializa la respuesta como un objeto JSON.

4. Interpreta los resultados.

Consulta la guía de la interfaz de REST para obtener más información sobre el uso de REST.

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

Nombres de recursos

La mayoría de los objetos de la API se identifican con sus cadenas de nombres de recursos. Estas cadenas también funcionan como URLs cuando se usa la interfaz de 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 admitidos y su representación de ruta de acceso (). Se usa el mismo formato para otros servicios.

resource_name

IDs 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 tilde (~).

Por ejemplo, como el ID de un anuncio de 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 compuesto ID de grupo de anuncios 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 de OAuth2 en el formato Authorization: Bearer YOUR_ACCESS_TOKEN que identifique una cuenta de administrador que actúe en nombre de un cliente o un anunciante que administre directamente su propia cuenta. Puedes encontrar instrucciones para recuperar un token de acceso en la guía de OAuth2. Un token de acceso es válido durante una hora después de que lo obtienes. Cuando vence, actualízalo para recuperar uno nuevo. Ten en cuenta que nuestras bibliotecas cliente actualizan automáticamente los tokens vencidos.

Si tienes errores de autorización, asegúrate de usar las credenciales correctas y de tener los permisos suficientes. Un error USER_PERMISSION_DENIED indica que es posible que el usuario autenticado no tenga acceso a la cuenta de cliente especificada en la solicitud. Consulta Niveles de acceso de Google Ads para obtener detalles sobre la administración de permisos.

developer-token

Un token de desarrollador es una cadena de 22 caracteres que identifica de forma única a un desarrollador de la API de Google Ads. Un ejemplo de cadena de token de desarrollador es ABcdeFGH93KL-NOPQ_STUv. El token de desarrollador debe incluirse en el formato 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 accedes a la cuenta de cliente a través de una cuenta de administrador, este encabezado es obligatorio y debe establecerse en el ID de cliente de la cuenta de administrador. Si no incluyes login-customer-id cuando te autenticas a través de una cuenta de administrador, se produce un error AuthorizationError.USER_PERMISSION_DENIED. Consulta Errores comunes para obtener más información sobre este tipo de error.

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 CampaignBudgetService solicitud es 1234567890:

https://googleads.googleapis.com/v24/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, se establece de forma predeterminada en el cliente operativo.

Nota: Puedes recuperar la lista de cuentas a las que se puede acceder directamente con tus credenciales de OAuth si emites una CustomerService.ListAccessibleCustomers solicitud. El login-customer-id no es obligatorio para este tipo de solicitud y no tiene ningún efecto en la lista de clientes que se muestra.

linked-customer-id

Este encabezado es obligatorio y lo usan los socios (como los proveedores de estadísticas de app de terceros o los socios de datos) cuando actúan en una cuenta de Google Ads vinculada. Este encabezado debe especificar el ID de cliente de la cuenta de Google Ads que tiene el vínculo de producto.

Considera la situación en la que un socio necesita realizar llamadas a la API a una cuenta de Google Ads en función de un vínculo de producto.

• Anunciante: Es la cuenta de Google Ads que se administra o actualiza con la llamada a la API. El ID de la cuenta del anunciante se especifica en la solicitud. En REST, este es el parámetro de ruta de acceso customerId (por ejemplo, customers/1111111111/...), y en gRPC, este es el campo customer_id en la solicitud.
• Socio: Es la cuenta del socio (por ejemplo, un proveedor de estadísticas de aplicaciones de terceros o un socio de datos).
• Cuenta vinculada: Es la cuenta de Google Ads que tiene un vínculo de producto establecido con el socio, lo que le otorga acceso al anunciante.

Un usuario que tiene acceso al socio realiza llamadas a la API para actuar sobre entidades en el anunciante (por ejemplo, para subir conversiones o administrar listas de usuarios). La cuenta vinculada puede ser el anunciante en sí o una cuenta de administrador del anunciante.

Los encabezados de la solicitud deben configurarse de la siguiente manera:

• Authorization: Es un token de OAuth2 para un usuario que tiene acceso al socio.
• developer-token: Es el token de desarrollador de la aplicación de la API, que suele estar asociado con el socio.
• login-customer-id: Es el ID de cliente del socio. El usuario autenticado debe tener acceso a esta cuenta.
• linked-customer-id: Es el ID de cliente de la cuenta vinculada. Este encabezado indica que la autorización para esta solicitud depende del vínculo de producto de la cuenta vinculada con el socio.

Existen dos situaciones de vinculación:

• Si el anunciante tiene un vínculo de producto directo con el socio, la cuenta vinculada es el anunciante y linked-customer-id debe establecerse en el ID de cliente del anunciante.
• Si el anunciante está administrado por una cuenta de administrador que tiene un vínculo de producto con el socio, la cuenta vinculada es la cuenta de administrador y linked-customer-id debe establecerse en el ID de cliente del administrador.

Ejemplo 1: Vínculo directo

Si el anunciante 1111111111 tiene un vínculo directo con el socio 2222222222 y la llamada a la API se dirige a customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Ejemplo 2: Vínculo de administrador

Si el anunciante 1111111111 está administrado por el administrador 3333333333, el administrador 3333333333 tiene un vínculo con el socio 2222222222 y la llamada a la API se dirige a customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Encabezados de respuesta

Los siguientes encabezados (o metadatos finales de gRPC) se muestran con el cuerpo de la respuesta. Te recomendamos que registres estos valores para la depuración.

request-id

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