Implementa la autorización del servidor

Las solicitudes a la API de Gmail deben estar autorizadas 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 tenga 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 tokens de actualización para tu servidor.

Si quieres obtener más información sobre la implementación de OAuth 2.0 de Google en el servidor, consulta Cómo usar 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 usar la herramienta de configuración, que te guiará en el proceso de creación de un proyecto en la Consola de APIs de Google, la habilitación de la API y la creación de credenciales.

1. 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.
2. Si creaste un ID de cliente de OAuth, selecciona tu tipo de aplicación.
3. 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 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 URIs de redireccionamiento.

Anota el ID de cliente, ya que lo necesitarás más adelante para agregarlo a tu código.

Cómo controlar las solicitudes de autorización

Cuando un usuario carga tu aplicación por primera vez, se le muestra un diálogo para otorgarle permiso a la aplicación para que acceda a su cuenta de Gmail con los alcances de permisos solicitados. Después de esta autorización inicial, al usuario solo se le presenta el diálogo de permisos si cambia 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 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 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 venza un token anterior. Tu aplicación almacena este token de actualización (por lo general, en una base de datos en tu servidor) para usarlo más adelante.

Importante: Siempre almacena los tokens de actualización del usuario. Si tu aplicación necesita un nuevo token de actualización, debe enviar una solicitud con el parámetro de consulta approval_prompt establecido en force. Esto hará que el usuario vea un diálogo para otorgar permiso nuevamente a tu aplicación.

En las siguientes muestras de código, se muestra cómo intercambiar un código de autorización por un token de acceso con acceso a offline y almacenar 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 un flujo de autorización exitoso por primera vez, la aplicación puede usar un token de actualización almacenado para autorizar las solicitudes sin volver a solicitarle 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 adecuadas.

Cómo usar credenciales de OAuth 2.0

Una vez que se hayan recuperado 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 hay credenciales revocadas

En el siguiente fragmento de código, se usa una instancia autorizada del servicio 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 redireccionando al usuario a la URL de autorización.

Hay más operaciones de la API de Gmail documentadas 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 autorizando las solicitudes de la API de Gmail, estarás listo para comenzar a controlar los mensajes, los hilos y las etiquetas, como se describe en las secciones de las guías para desarrolladores.

Puedes obtener más información sobre los métodos de API disponibles en la Referencia de la API.

Advertencia: Cuando pruebes tu app durante el desarrollo, asegúrate de usar una cuenta de Gmail de prueba que no te importe perder. Esto evitará que cause estragos accidentalmente con tus correos electrónicos, conversaciones y etiquetas reales.