Las solicitudes a la API de Gmail deben autorizarse con las credenciales de OAuth 2.0. Debes usar el flujo del servidor cuando tu aplicación necesite acceder a las API de Google en nombre del usuario, por ejemplo, cuando este no tenga conexión. Este enfoque requiere pasar un código de autorización único del cliente a tu servidor, que se usa para adquirir un token de acceso y tokens de actualización para tu servidor.
Consulta Cómo usar OAuth 2.0 para aplicaciones de servidor web a fin de obtener más información acerca de la implementación de OAuth 2.0 en el lado del servidor.
Contenido
Crea un ID de cliente y un secreto de cliente
Para comenzar a usar la API de Gmail, primero debes usar la herramienta de configuración, que te guiará para crear un proyecto en la Consola de API 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 tu tipo de aplicación.
- Completa el formulario y haz clic en Crear.
Los ID de cliente y las claves de la cuenta de servicio de tu aplicación ahora se muestran en la página Credenciales. Para obtener más información, 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 URI de redireccionamiento.
Toma nota del ID de cliente, ya que deberás agregarlo a tu código más adelante.
Maneja solicitudes de autorización
Cuando un usuario carga tu aplicación por primera vez, aparece un diálogo en el que se le otorga permiso para que la aplicación acceda a su cuenta de Gmail con los permisos de permisos solicitados. Después de esta autorización inicial, el usuario solo verá el diálogo del permiso si cambió el ID de cliente de tu app o los permisos solicitados.
Autentica al usuario
Este acceso inicial muestra un objeto de resultado de autorización que contiene un código de autorización si se ejecuta correctamente.
Intercambia el código de autorización por un token de acceso
El código de autorización es un código único 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 venció un token anterior. La aplicación almacena este token de actualización (por lo general, en una base de datos en tu servidor) para su uso posterior.
En las siguientes muestras de código, se demuestra el intercambio de un código de autorización por un token de acceso con acceso a offline y el almacenamiento del token de actualización.
Python
Reemplaza el valor CLIENTSECRETS_LOCATION por la ubicación de tu archivo client_secrets.json.
import logging
from oauth2client.client import flow_from_clientsecrets
from oauth2client.client import FlowExchangeError
from apiclient.discovery import build
# ...
# Path to client_secrets.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."""
self.authorization_url = authorization_url
class CodeExchangeException(GetCredentialsException):
"""Error raised when a code exchange has failed."""
class NoRefreshTokenException(GetCredentialsException):
"""Error raised when no refresh token has been found."""
class NoUserIdException(Exception):
"""Error raised when no user ID could be retrieved."""
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:
NotImplemented: 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.
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:
NotImplemented: 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.
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, 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 errors.HttpError, 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
return flow.step1_get_authorize_url(REDIRECT_URI)
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)
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, 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)
Autoriza con credenciales almacenadas
Cuando los usuarios visitan tu app después de un flujo de autorización por primera vez exitoso, la aplicación puede usar un token de actualización almacenado para autorizar solicitudes sin volver a preguntarle al usuario.
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, deberás detectarlo 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 esta muestra de código, se indica cómo crear una instancia de un objeto de servicio y, luego, autorizarlo para realizar 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 hay credenciales revocadas
En el siguiente fragmento de código, se usa una instancia de servicio autorizada de Gmail para recuperar una lista de mensajes.
Si se produce un error, el código busca un código de estado HTTP 401, que se debe controlar mediante el redireccionamiento del 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 apiclient 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 = response['messages']
while 'nextPageToken' in response:
page_token = response['nextPageToken']
response = service.users().messages().list(userId=user, q=query,
pageToken=page_token).execute()
messages.extend(response['messages'])
return messages
except errors.HttpError, 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 para autorizar las solicitudes a la API de Gmail, estarás listo para comenzar a controlar mensajes, conversaciones 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.