Las solicitudes a la API de Gmail deben autorizarse con credenciales de OAuth 2.0. Debes usar el flujo del servidor cuando tu aplicación necesite acceder a las APIs de Google en nombre del usuario, por ejemplo, cuando el usuario no esté conectado. Este enfoque requiere que pases un código de autorización único de tu cliente a tu servidor. Este código se usa para adquirir un token de acceso y tokens de actualización para tu servidor.
Si deseas obtener más información sobre la implementación de Google OAuth 2.0 del servidor, consulta Usa OAuth 2.0 para aplicaciones de servidor web.
Contenido
Crea un ID de cliente y un secreto de cliente
Para comenzar a usar la API de Gmail, primero debes emplear la herramienta de configuración, que te guiará para crear un proyecto en la Consola de APIs de Google, habilitar la API y crear credenciales.
- En la página Credenciales, haz clic en Crear credenciales > ID de cliente de OAuth para crear tus credenciales de OAuth 2.0 o en Crear credenciales > Clave de cuenta de servicio para crear una cuenta de servicio.
- Si creaste un ID de cliente de OAuth, selecciona el tipo de aplicación.
- Completa el formulario y haz clic en Crear.
Los IDs de cliente y las claves de cuenta de servicio de tu aplicación ahora aparecen en la página Credenciales. Para obtener más detalles, haz clic en un ID de cliente. Los parámetros varían según el tipo de ID, pero pueden incluir la dirección de correo electrónico, el secreto del cliente, los orígenes de JavaScript o los URIs de redireccionamiento.
Toma nota del ID de cliente, ya que deberás agregarlo a tu código más adelante.
Cómo controlar solicitudes de autorización
Cuando un usuario carga tu aplicación por primera vez, se le muestra un diálogo para que otorgue permiso a tu aplicación para acceder a su cuenta de Gmail con los alcances de permisos solicitados. Después de esta autorización inicial, solo se le mostrará el diálogo de permisos al usuario si cambia el ID de cliente de tu app o si cambiaron los alcances solicitados.
Autentica al usuario
Si el acceso inicial se realiza correctamente, se devuelve un objeto de resultado de autorización que contiene un código de autorización.
Intercambia el código de autorización por un token de acceso
El código de autorización es un código de un solo uso que tu servidor puede intercambiar por un token de acceso. Este token de acceso se pasa a la API de Gmail para otorgarle a tu aplicación acceso a los datos del usuario por un tiempo limitado.
Si tu aplicación requiere acceso a offline, la primera vez que intercambia el código de autorización, también recibe un token de actualización que usa para recibir un token de acceso nuevo después de que vence un token anterior. Tu aplicación almacena este token de actualización (generalmente en una base de datos en tu servidor) para usarlo más adelante.
En los siguientes ejemplos de código, se muestra cómo intercambiar un código de autorización por un token de acceso con acceso a offline y cómo almacenar el token de actualización.
Python
Reemplaza el valor de CLIENTSECRETS_LOCATION por la ubicación de tu archivo credentials.json.
import logging
from oauth2client.client import flow_from_clientsecrets
from oauth2client.client import FlowExchangeError
from oauth2client.client import Credentials # Needed for type hinting/usage in comments
from googleapiclient.discovery import build
from googleapiclient import errors as google_api_errors
import httplib2
# Path to credentials.json which should contain a JSON document such as:
# {
# "web": {
# "client_id": "[[YOUR_CLIENT_ID]]",
# "client_secret": "[[YOUR_CLIENT_SECRET]]",
# "redirect_uris": [],
# "auth_uri": "https://accounts.google.com/o/oauth2/auth",
# "token_uri": "https://accounts.google.com/o/oauth2/token"
# }
# }
CLIENTSECRETS_LOCATION = '<PATH/TO/CLIENT_SECRETS.JSON>'
REDIRECT_URI = '<YOUR_REGISTERED_REDIRECT_URI>'
SCOPES = [
'https://www.googleapis.com/auth/gmail.readonly',
'https://www.googleapis.com/auth/userinfo.email',
'https://www.googleapis.com/auth/userinfo.profile',
# Add other requested scopes.
]
class GetCredentialsException(Exception):
"""Error raised when an error occurred while retrieving credentials.
Attributes:
authorization_url: Authorization URL to redirect the user to in order to
request offline access.
"""
def __init__(self, authorization_url):
"""Construct a GetCredentialsException."""
super().__init__(f"Authorization URL: {authorization_url}")
self.authorization_url = authorization_url
class CodeExchangeException(GetCredentialsException):
"""Error raised when a code exchange has failed."""
pass
class NoRefreshTokenException(GetCredentialsException):
"""Error raised when no refresh token has been found."""
pass
class NoUserIdException(Exception):
"""Error raised when no user ID could be retrieved."""
pass
def get_stored_credentials(user_id):
"""Retrieved stored credentials for the provided user ID.
Args:
user_id: User's ID.
Returns:
Stored oauth2client.client.OAuth2Credentials if found, None otherwise.
Raises:
NotImplementedError: This function has not been implemented.
"""
# TODO: Implement this function to work with your database.
# To instantiate an OAuth2Credentials instance from a Json
# representation, use the oauth2client.client.Credentials.new_from_json
# class method. (oauth2client.client.Credentials needs to be imported)
# Example:
# from oauth2client.client import Credentials
# json_creds = load_from_db(user_id)
# if json_creds:
# return Credentials.new_from_json(json_creds)
# return None
raise NotImplementedError()
def store_credentials(user_id, credentials):
"""Store OAuth 2.0 credentials in the application's database.
This function stores the provided OAuth 2.0 credentials using the user ID as
key.
Args:
user_id: User's ID.
credentials: OAuth 2.0 credentials to store.
Raises:
NotImplementedError: This function has not been implemented.
"""
# TODO: Implement this function to work with your database.
# To retrieve a Json representation of the credentials instance, call the
# credentials.to_json() method.
# Example:
# save_to_db(user_id, credentials.to_json())
raise NotImplementedError()
def exchange_code(authorization_code):
"""Exchange an authorization code for OAuth 2.0 credentials.
Args:
authorization_code: Authorization code to exchange for OAuth 2.0
credentials.
Returns:
oauth2client.client.OAuth2Credentials instance.
Raises:
CodeExchangeException: an error occurred.
"""
flow = flow_from_clientsecrets(CLIENTSECRETS_LOCATION, ' '.join(SCOPES))
flow.redirect_uri = REDIRECT_URI
try:
credentials = flow.step2_exchange(authorization_code)
return credentials
except FlowExchangeError as error:
logging.error('An error occurred: %s', error)
raise CodeExchangeException(None)
def get_user_info(credentials):
"""Send a request to the UserInfo API to retrieve the user's information.
Args:
credentials: oauth2client.client.OAuth2Credentials instance to authorize the
request.
Returns:
User information as a dict.
"""
user_info_service = build(
serviceName='oauth2', version='v2',
http=credentials.authorize(httplib2.Http()))
user_info = None
try:
user_info = user_info_service.userinfo().get().execute()
except google_api_errors.HttpError as e:
logging.error('An error occurred: %s', e)
if user_info and user_info.get('id'):
return user_info
else:
raise NoUserIdException()
def get_authorization_url(email_address, state):
"""Retrieve the authorization URL.
Args:
email_address: User's e-mail address.
state: State for the authorization URL.
Returns:
Authorization URL to redirect the user to.
"""
flow = flow_from_clientsecrets(CLIENTSECRETS_LOCATION, ' '.join(SCOPES))
flow.params['access_type'] = 'offline'
flow.params['approval_prompt'] = 'force'
flow.params['user_id'] = email_address
flow.params['state'] = state
# The step1_get_authorize_url method uses the flow.redirect_uri attribute.
flow.redirect_uri = REDIRECT_URI
return flow.step1_get_authorize_url()
def get_credentials(authorization_code, state):
"""Retrieve credentials using the provided authorization code.
This function exchanges the authorization code for an access token and queries
the UserInfo API to retrieve the user's e-mail address.
If a refresh token has been retrieved along with an access token, it is stored
in the application database using the user's e-mail address as key.
If no refresh token has been retrieved, the function checks in the application
database for one and returns it if found or raises a NoRefreshTokenException
with the authorization URL to redirect the user to.
Args:
authorization_code: Authorization code to use to retrieve an access token.
state: State to set to the authorization URL in case of error.
Returns:
oauth2client.client.OAuth2Credentials instance containing an access and
refresh token.
Raises:
CodeExchangeError: Could not exchange the authorization code.
NoRefreshTokenException: No refresh token could be retrieved from the
available sources.
"""
email_address = ''
try:
credentials = exchange_code(authorization_code)
user_info = get_user_info(credentials) # Can raise NoUserIdException or google_api_errors.HttpError
email_address = user_info.get('email')
user_id = user_info.get('id')
if credentials.refresh_token is not None:
store_credentials(user_id, credentials)
return credentials
else:
credentials = get_stored_credentials(user_id)
if credentials and credentials.refresh_token is not None:
return credentials
except CodeExchangeException as error:
logging.error('An error occurred during code exchange.')
# Drive apps should try to retrieve the user and credentials for the current
# session.
# If none is available, redirect the user to the authorization URL.
error.authorization_url = get_authorization_url(email_address, state)
raise error
except NoUserIdException:
logging.error('No user ID could be retrieved.')
# No refresh token has been retrieved.
authorization_url = get_authorization_url(email_address, state)
raise NoRefreshTokenException(authorization_url)
Autorización con credenciales almacenadas
Cuando los usuarios visitan tu app después de un flujo de autorización exitoso por primera vez, tu aplicación puede usar un token de actualización almacenado para autorizar solicitudes sin volver a solicitarle al usuario que lo haga.
Si ya autenticaste al usuario, tu aplicación puede recuperar el token de actualización de su base de datos y almacenarlo en una sesión del servidor. Si se revoca el token de actualización o no es válido por algún otro motivo, deberás detectar esta situación y tomar las medidas correspondientes.
Usa credenciales de OAuth 2.0
Una vez que se recuperaron las credenciales de OAuth 2.0, como se muestra en la sección anterior, se pueden usar para autorizar un objeto de servicio de Gmail y enviar solicitudes a la API.
Crea una instancia de un objeto de servicio
En este ejemplo de código, se muestra cómo crear una instancia de un objeto de servicio y, luego, autorizarlo para que realice solicitudes a la API.
Python
from apiclient.discovery import build
# ...
def build_service(credentials):
"""Build a Gmail service object.
Args:
credentials: OAuth 2.0 credentials.
Returns:
Gmail service object.
"""
http = httplib2.Http()
http = credentials.authorize(http)
return build('gmail', 'v1', http=http)
Envía solicitudes autorizadas y verifica si se revocaron las credenciales
El siguiente fragmento de código usa una instancia autorizada del servicio de Gmail para recuperar una lista de mensajes.
Si se produce un error, el código verifica si hay un código de estado HTTP 401, que se debe controlar redireccionando al usuario a la URL de autorización.
En la Referencia de la API, se documentan más operaciones de la API de Gmail.
Python
from googleapiclient import errors
# ...
def ListMessages(service, user, query=''):
"""Gets a list of messages.
Args:
service: Authorized Gmail API service instance.
user: The email address of the account.
query: String used to filter messages returned.
Eg.- 'label:UNREAD' for unread Messages only.
Returns:
List of messages that match the criteria of the query. Note that the
returned list contains Message IDs, you must use get with the
appropriate id to get the details of a Message.
"""
try:
response = service.users().messages().list(userId=user, q=query).execute()
messages = []
if 'messages' in response:
messages.extend(response['messages'])
while 'nextPageToken' in response:
page_token = response['nextPageToken']
response = service.users().messages().list(userId=user, q=query,
pageToken=page_token).execute()
if 'messages' in response:
messages.extend(response['messages'])
return messages
except errors.HttpError as error:
print('An error occurred: %s' % error)
if error.resp.status == 401:
# Credentials have been revoked.
# TODO: Redirect the user to the authorization URL.
raise NotImplementedError()
Próximos pasos
Una vez que te sientas cómodo autorizando solicitudes a la API de Gmail, podrás comenzar a controlar mensajes, hilos y etiquetas, como se describe en las secciones de las Guías para desarrolladores.
Puedes obtener más información sobre los métodos de la API disponibles en la Referencia de la API.