Autenticación y autorización

Al igual que otras APIs de Google, la API de Google Ads usa el protocolo OAuth 2.0 para la autenticación y la autorización. OAuth 2.0 permite que tu cliente de API de Google Ads acceda a la cuenta de Google Ads de un usuario sin tener que administrar ni almacenar su información de acceso.

En esta guía, se explica cómo configurar la biblioteca cliente de Java para la autenticación de la API de Google Ads con los tres flujos de OAuth 2.0 más comunes, además de explicar las credenciales necesarias.

Para obtener más información sobre el modelo de acceso de la API de Google Ads, consulta la guía del modelo de acceso de Google Ads.

Credenciales

El acceso a la API de Google Ads requiere un token de desarrollador, credenciales de OAuth 2.0 y, en algunos casos, un ID de cliente de acceso.

Token del desarrollador

El token de desarrollador está vinculado a una cuenta de administrador y se puede encontrar en la interfaz web de Google Ads.

Aunque el token de desarrollador está vinculado a una cuenta de administrador, no proporciona acceso a esa cuenta. En cambio, el token de desarrollador otorga acceso a la API en general, y el acceso a nivel de la cuenta se configura a través de OAuth 2.0.

En la biblioteca cliente, el token de desarrollador se especifica con la clave api.googleads.developerToken en el archivo ads.properties.

Credenciales de OAuth 2.0

Para autorizar a los usuarios de la Cuenta de Google con acceso a las cuentas de Google Ads, debes proporcionar un conjunto de credenciales de OAuth 2.0. El tipo de credenciales requeridas varía según el flujo de OAuth 2.0 que se use.

La biblioteca admite tres flujos:

  • Flujo de cuenta de servicio
  • Flujo de autenticación de un solo usuario
  • Flujo de autenticación multiusuario

Consulta la Descripción general de OAuth para obtener detalles sobre los flujos de OAuth de la API de Google Ads y sigue las instrucciones del flujo que mejor se adapte a tus necesidades para obtener las credenciales requeridas.

ID de cliente de acceso

De manera opcional, especifica el ID de cliente de una cuenta de administrador que proporcione acceso a la cuenta de publicación. Esto se debe especificar si tu acceso a la cuenta de cliente es a través de una cuenta de administrador. No es necesario especificar todas las cuentas de administrador en la ruta de acceso al ID de cliente, solo el ID de administrador superior que usas para los permisos de acceso. Para obtener más detalles, consulta la documentación relacionada.

En la biblioteca cliente, el ID de cliente de acceso se especifica con la clave api.googleads.loginCustomerId en el archivo ads.properties.

Configuración

Puedes configurar la biblioteca cliente con un archivo ads.properties, variables de entorno o de forma programática. Esta guía se centra en el uso de un archivo ads.properties. Consulta la guía de configuración para obtener detalles sobre todas las opciones.

Si usas un archivo ads.properties, colócalo en tu directorio principal: ~/ads.properties.

Flujos de trabajo de OAuth

Existen tres flujos de trabajo comunes que se usan cuando se trabaja con la API de Google Ads.

Flujo de cuenta de servicio

Este es el flujo de trabajo recomendado si tu flujo de trabajo no requiere ninguna interacción humana. Este flujo de trabajo requiere un paso de configuración, en el que el usuario agrega una cuenta de servicio a su cuenta de Google Ads. Luego, la app puede usar las credenciales de la cuenta de servicio para administrar la cuenta de Google Ads del usuario.

Una vez que tengas el archivo JSON de clave privada, agrega lo siguiente a tu archivo ads.properties:

api.googleads.serviceAccountSecretsPath=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

Consulta la guía del flujo de trabajo de la cuenta de servicio para obtener más información.

Flujo de autenticación de un solo usuario

Este flujo de trabajo se puede usar si no puedes usar cuentas de servicio. Este flujo de trabajo requiere dos pasos de configuración:

  1. Otorga acceso a un solo usuario a todas las cuentas que se administrarán con la API de Google Ads. Un enfoque común es otorgar acceso al usuario a una cuenta de administrador de la API de Google Ads y vincular todas las cuentas de Google Ads en esa cuenta de administrador.
  2. El usuario ejecuta una herramienta de línea de comandos, como gcloud o el GenerateUserCredentials ejemplo de código para autorizar a tu app a administrar todas sus cuentas de Google Ads en su nombre.

Una vez que tengas estas credenciales, agrega lo siguiente a tu archivo ads.properties:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

Consulta la guía del flujo de trabajo de autenticación de un solo usuario para obtener más información.

Flujo de autenticación multiusuario

Este es el flujo de trabajo recomendado si tu app permite que los usuarios accedan y autoricen tu app para administrar sus cuentas de Google Ads en su nombre. El GenerateUserCredentials es un ejemplo de código de línea de comandos que ilustra cómo obtener la autenticación del usuario en el tiempo de ejecución para administrar sus cuentas de Google Ads en su nombre. Puedes usar este ejemplo de código como referencia para compilar apps de escritorio que requieran la autenticación del usuario.

Agrega lo siguiente a tu archivo ads.properties:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

Consulta la guía del flujo de trabajo de autenticación multiusuario para obtener más información.

¿Qué sucede si mi usuario administra varias cuentas?

Es común que un usuario administre más de una cuenta de Google Ads, ya sea a través del acceso directo a las cuentas o a través de una cuenta de administrador de Google Ads. La biblioteca cliente de Java proporciona los siguientes ejemplos de código que ilustran cómo controlar estos casos.

  1. En el ejemplo de código GetAccountHierarchy, se muestra cómo recuperar la lista de todas las cuentas en una cuenta de administrador de Google Ads.
  2. En el ejemplo de código ListAccessibleCustomers, se muestra cómo recuperar la lista de todas las cuentas a las que un usuario tiene acceso directo. Luego, estas cuentas se pueden usar como valores válidos para la configuración LoginCustomerId.

Credenciales predeterminadas de la aplicación

La biblioteca cliente de Java también admite la autenticación con credenciales predeterminadas de la aplicación.

Esto es particularmente útil para el desarrollo local o para el desarrollo en diferentes APIs de Google, ya que puedes reutilizar las mismas credenciales, siempre que puedan acceder a los permisos de OAuth 2.0 correctos.

Para la API de Google Ads, asegúrate de que tus credenciales predeterminadas de la aplicación puedan acceder al permiso de OAuth 2.0 https://www.googleapis.com/auth/adwords.

Para usar las credenciales predeterminadas de la aplicación, configura la opción api.googleads.useApplicationDefaultCredentials como true en el archivo ads.properties. Cuando se usan las credenciales predeterminadas de la aplicación, no se deben configurar el ID de cliente, el secreto del cliente ni el token de actualización.