Las solicitudes a la API de Gmail se deben autorizar con OAuth 2.0 credenciales. Debes usar el flujo del servidor cuando tu aplicación necesita acceder a las APIs de Google en nombre del usuario, por ejemplo, cuando este sin conexión. Este enfoque requiere pasar 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 de actualización para tu servidor.
Para obtener más información sobre la implementación de Google OAuth 2.0 en el servidor, consulta Usa OAuth 2.0 para aplicaciones de servidor web.
Contenido
Crea un ID de cliente y un secreto de cliente
Para empezar a usar la API de Gmail, primero debes uso la herramienta de configuración, que te guiará para crear un proyecto en el Consola de APIs de Google, cómo habilitar la API y crear credenciales.
- Desde la página Credenciales, haz clic en Crear credenciales > cliente de OAuth ID para crear tus credenciales de OAuth 2.0 o Crear credenciales > Servicio de la 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 IDs de cliente y las claves de la cuenta de servicio de tu aplicación ahora aparecen 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 dirección de correo electrónico, secreto del cliente, Orígenes de JavaScript o URI de redireccionamiento.
Anota el ID de cliente, ya que necesitarás agregarlo a tu código más adelante.
Manejo de solicitudes de autorización
Cuando un usuario carga tu aplicación por primera vez, se le presentan un cuadro de diálogo que otorga permiso para que tu aplicación acceda a su cuenta de Gmail con los permisos de permisos solicitados. Después de esta inicial autorización, el usuario solo verá el diálogo de permiso si tu cambios en el ID de cliente de la app o los permisos solicitados.
Autentica al usuario
Este acceso inicial devuelve un objeto de resultado de autorización que contiene un código de autorización si se realiza 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 un token de acceso Este token de acceso se pasa a la API de Gmail para otorgar el acceso de tu aplicación a los datos del usuario por un tiempo limitado.
Si tu aplicación requiere acceso a offline, la primera vez que se intercambia la app
el código de autorización, también recibe un token de actualización que usa para
recibir un nuevo token de acceso después de que caduque el anterior; Tu aplicación
almacena este token de actualización (generalmente en una base de datos en tu servidor) para
su uso posterior.
Los siguientes ejemplos de código demuestran el intercambio de un código de autorización por
un token de acceso con acceso offline y almacenando el 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 una autorización exitosa por primera vez de actualización, la aplicación puede usar un token de actualización almacenado para autorizar solicitudes sin volver a pedirle permiso 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 un servidor sesión. Si se revoca el token de actualización o no es válido, necesitas detectarlo y tomar las medidas adecuadas.
Usa credenciales de OAuth 2.0
Una vez que se recuperan las credenciales de OAuth 2.0, como se muestra en el 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 hacer 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
El siguiente fragmento de código usa una instancia de servicio de Gmail autorizada 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 redireccionando al usuario a la cuenta
URL.
Encontrarás más operaciones de la API de Gmail en la Referencia de la API.
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 con la autorización de solicitudes a la API de Gmail, estarás listo para empezar a administrar mensajes, subprocesos y etiquetas, como se describe en el Guías para desarrolladores.
Puedes obtener más información sobre los métodos de API disponibles en el Referencia de la API.