Estructura de llamadas 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 algunos conocimientos sobre la estructura de las llamadas a la API puede ser útil para realizar pruebas y depuraciones.

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.

Preferido:

1. Crea el cuerpo de la solicitud como un búfer de protocolo.
2. Enviarlo al servidor con HTTP/2
3. Deserializa la respuesta a un búfer de protocolo.
4. Interpreta los resultados.

La mayor parte de nuestra documentación describe cómo usar gRPC.

Opcional:

1. Crea el cuerpo de la solicitud como un objeto JSON.
2. Envíala 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 la estructura y los encabezados de transporte comunes a los protocolos gRPC y REST.

Identificadores de recursos

Los objetos de la API de Google Ads se direccionan con nombres de recursos estructurados y con identificadores compuestos.

Nombres de recursos

La mayoría de los objetos de la API se identifican por sus cadenas de nombres de recursos. Estas cadenas también sirven 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 (resource_name). Se usa el mismo formato para otros servicios.

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, un AdGroupAd tiene el patrón de nombre de recurso customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Debido a que su identificador compuesto combina el ID del grupo de anuncios superior (ad_group.id) y el ID del anuncio subyacente (ad_group_ad.ad.id), anteponemos el ID del grupo de anuncios al ID del anuncio:

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

Nota: No se permite compartir un AdId en varios grupos de anuncios. Si se crea un AdGroupAd nuevo que hace referencia a un AdId existente en otro grupo de anuncios, se produce un error con AdGroupAdError.AD_SHARING_NOT_ALLOWED.

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 OAuth 2.0 con 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 adquieres. Cuando venza, actualiza el token de acceso para recuperar uno nuevo. Ten en cuenta que nuestras bibliotecas cliente actualizan automáticamente los tokens vencidos.

Si encuentras 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. Si tu proyecto de Google Cloud solo se aprueba para el acceso a Test y envías una solicitud orientada a una cuenta de producción, la API devolverá AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION en la versión 25 y posteriores (o AuthorizationError.ACTION_NOT_PERMITTED en la versión 24 y anteriores). Consulta los niveles de acceso de Google Ads para obtener detalles sobre cómo administrar los permisos.

login-customer-id

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 se debe establecer 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. Revisa los errores comunes para obtener más información sobre este tipo de error. Para obtener una explicación detallada de cómo se resuelve el acceso a la cuenta, consulta la guía Modelo de acceso de OAuth.

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/v26/customers/1234567890/campaignBudgets:mutate

Establecer 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 emitiendo una solicitud CustomerService.ListAccessibleCustomers. 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 devuelve.

linked-customer-id

Este encabezado es obligatorio y lo usan los socios (como los proveedores de estadísticas de apps de terceros o los socios de datos) cuando realizan acciones en una cuenta de Google Ads vinculada. Este encabezado debe especificar el ID de cliente de la cuenta de Google Ads que tiene la vinculación de productos.

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 una vinculación de productos.

• Anunciante: Es la cuenta de Google Ads que se administra o actualiza con la llamada a la API. El ID de la cuenta de anunciante se especifica en la solicitud. En REST, este es el parámetro de ruta customerId (por ejemplo, customers/1111111111/...) y, en gRPC, este es el campo customer_id en la solicitud.
• Socio: Es la cuenta de 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 una vinculación de productos establecida con el Socio, lo que le otorga acceso al Anunciante.

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

Los encabezados de la solicitud se deben configurar de la siguiente manera:

• Authorization: Es un token de acceso de OAuth 2.0 para un usuario que tiene acceso al socio.
• login-customer-id: Es el ID de cliente de la cuenta de 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 se basa en la vinculación de productos de la cuenta vinculada con el socio.

Existen dos situaciones de vinculación:

• Si la cuenta del Anunciante tiene una vinculación directa de productos con la cuenta del Socio, la Cuenta vinculada es la del Anunciante, y linked-customer-id se debe establecer en el ID de cliente de la cuenta del Anunciante.
• Si la cuenta del Anunciante se administra con una cuenta de administrador que tiene una vinculación de producto con la cuenta del Socio, la Cuenta vinculada es la cuenta de administrador, y linked-customer-id se debe establecer en el ID de cliente del administrador.

Ejemplo 1: Vínculo directo

Si la cuenta de anunciante 1111111111 tiene un vínculo directo con la cuenta de socio 2222222222 y la llamada a la API se orienta a customers/1111111111/..., ocurrirá lo siguiente:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Ejemplo 2: Vinculación de administrador

Si la cuenta de anunciante 1111111111 está administrada por la cuenta de administrador 3333333333, la cuenta de administrador 3333333333 tiene una vinculación con la cuenta de socio 2222222222 y la llamada a la API se orienta a customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Encabezados de respuesta

Los siguientes encabezados (o metadatos finales de gRPC) se devuelven con el cuerpo de la respuesta. Te recomendamos que registres estos valores para depurar errores.

request-id

El request-id es una cadena que identifica de forma exclusiva esta solicitud. Proporciona este valor cuando te comuniques con el equipo de asistencia para solucionar problemas de solicitudes a la API fallidas o inesperadas.