Mengimplementasikan otorisasi sisi server

Permintaan ke Gmail API harus diotorisasi menggunakan kredensial OAuth 2.0. Anda harus menggunakan alur sisi server saat aplikasi harus mengakses Google API atas nama pengguna, misalnya saat pengguna offline. Pendekatan ini memerlukan penerusan kode otorisasi satu kali dari klien ke server; kode ini digunakan untuk memperoleh token akses dan token refresh untuk server Anda.

Untuk mempelajari penerapan Google OAuth 2.0 sisi server lebih lanjut, lihat Menggunakan OAuth 2.0 untuk Aplikasi Server Web.

Daftar Isi

Membuat client ID dan rahasia klien

Untuk mulai menggunakan Gmail API, pertama-tama Anda harus menggunakan alat penyiapan, yang memandu Anda menyelesaikan pembuatan project di Konsol Google API, mengaktifkan API, dan membuat kredensial.

1. Dari halaman Kredensial, klik Buat kredensial > Client ID OAuth untuk membuat kredensial OAuth 2.0 atau Buat kredensial > Kunci akun layanan untuk membuat akun layanan.
2. Jika Anda membuat client ID OAuth, pilih jenis aplikasi Anda.
3. Isi formulir, lalu klik Buat.

Client ID dan kunci akun layanan aplikasi Anda kini tercantum di halaman Kredensial. Untuk mengetahui detailnya, klik client ID; parameter bervariasi bergantung pada jenis ID, tetapi dapat mencakup alamat email, rahasia klien, asal JavaScript, atau URI pengalihan.

Catat Client ID karena Anda harus menambahkannya ke kode nanti.

Menangani permintaan otorisasi

Saat pengguna memuat aplikasi Anda untuk pertama kalinya, mereka akan melihat dialog untuk memberikan izin bagi aplikasi Anda untuk mengakses akun Gmail mereka dengan cakupan izin yang diminta. Setelah otorisasi awal ini, pengguna hanya akan melihat dialog izin jika client ID aplikasi Anda berubah atau cakupan yang diminta telah berubah.

Mengautentikasi pengguna

Login awal ini menampilkan objek hasil otorisasi yang berisi kode otorisasi jika berhasil.

Menukar kode otorisasi dengan token akses

Kode otorisasi adalah kode satu kali yang dapat ditukarkan server Anda dengan token akses. Token akses ini diteruskan ke Gmail API untuk memberikan akses aplikasi Anda ke data pengguna selama waktu terbatas.

Jika aplikasi Anda memerlukan akses offline, saat pertama kali menukarkan kode otorisasi, aplikasi juga akan menerima token refresh yang digunakan untuk menerima token akses baru setelah token sebelumnya tidak lagi berlaku. Aplikasi Anda menyimpan token refresh ini (umumnya dalam database di server Anda) untuk digunakan nanti.

Penting: Selalu simpan token refresh pengguna. Jika aplikasi Anda memerlukan token refresh baru, aplikasi harus mengirim permintaan dengan parameter kueri approval_prompt yang ditetapkan ke force. Tindakan ini akan menyebabkan pengguna melihat dialog untuk memberikan izin ke aplikasi Anda lagi.

Contoh kode berikut menunjukkan pertukaran kode otorisasi dengan token akses dengan akses offline dan menyimpan token refresh.

Python

Ganti nilai CLIENTSECRETS_LOCATION dengan lokasi file client_secrets.json Anda.

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)

Memberi otorisasi dengan kredensial tersimpan

Saat pengguna mengunjungi aplikasi Anda setelah alur otorisasi pertama kali berhasil, aplikasi Anda dapat menggunakan token refresh yang disimpan untuk memberikan otorisasi permintaan tanpa meminta pengguna lagi.

Jika Anda telah mengautentikasi pengguna, aplikasi Anda dapat mengambil token refresh dari database-nya dan menyimpan token dalam sesi sisi server. Jika token refresh dicabut atau tidak valid, Anda harus menemukannya dan mengambil tindakan yang sesuai.

Menggunakan kredensial OAuth 2.0

Setelah kredensial OAuth 2.0 diambil seperti yang ditunjukkan di bagian sebelumnya, kredensial tersebut dapat digunakan untuk memberikan otorisasi pada objek layanan Gmail dan mengirim permintaan ke API.

Membuat instance objek layanan

Contoh kode ini menunjukkan cara membuat instance objek layanan, lalu memberikan otorisasi untuk membuat permintaan 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)

Mengirim permintaan yang diotorisasi dan memeriksa kredensial yang dicabut

Cuplikan kode berikut menggunakan instance layanan Gmail resmi untuk mengambil daftar pesan.

Jika terjadi error, kode akan memeriksa kode status 401 HTTP, yang harus ditangani dengan mengalihkan pengguna ke URL otorisasi.

Operasi Gmail API lainnya didokumentasikan dalam Referensi 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()

Langkah berikutnya

Setelah Anda merasa nyaman memberikan otorisasi pada permintaan Gmail API, Anda siap untuk mulai menangani pesan, rangkaian pesan, dan label, seperti yang dijelaskan di bagian Panduan Developer.

Anda dapat mempelajari lebih lanjut metode API yang tersedia di Referensi API.

Peringatan: Saat menguji aplikasi selama pengembangan, pastikan untuk menggunakan akun Gmail pengujian yang tidak Anda pedulikan. Tindakan ini akan mencegah Anda secara tidak sengaja menyebabkan kekacauan pada email, rangkaian pesan, dan label yang sebenarnya.