Autentikasi & Otorisasi

Cakupan Gmail API

Dokumen ini berisi informasi otorisasi dan autentikasi khusus Gmail API. Sebelum membaca dokumen ini, pastikan Anda membaca informasi autentikasi dan otorisasi umum Google Workspace di Mempelajari autentikasi dan otorisasi.

Mengonfigurasi OAuth 2.0 untuk otorisasi

Mengonfigurasi layar izin OAuth dan memilih cakupan untuk menentukan informasi yang ditampilkan kepada pengguna dan peninjau aplikasi, serta mendaftarkan aplikasi Anda agar dapat dipublikasikan nanti.

Cakupan Gmail API

Untuk menentukan tingkat akses yang diberikan ke aplikasi Anda, Anda perlu mengidentifikasi dan mendeklarasikan cakupan otorisasi. Cakupan otorisasi adalah string URI OAuth 2.0 yang berisi nama aplikasi Google Workspace, jenis data yang diakses, dan tingkat akses. Cakupan adalah permintaan aplikasi Anda untuk menggunakan data Google Workspace, termasuk data Akun Google pengguna.

Saat aplikasi Anda diinstal, pengguna akan diminta untuk memvalidasi cakupan yang digunakan oleh aplikasi. Secara umum, Anda harus memilih cakupan yang paling berfokus dan menghindari permintaan cakupan yang tidak diperlukan aplikasi Anda. Pengguna lebih bersedia memberikan akses ke cakupan terbatas yang dijelaskan dengan jelas.

Peringatan

Jika aplikasi publik Anda menggunakan cakupan yang mengizinkan akses ke data pengguna tertentu, aplikasi tersebut harus menyelesaikan proses verifikasi. Jika Anda melihat aplikasi belum diverifikasi di layar saat menguji aplikasi, Anda harus mengirimkan permintaan verifikasi untuk menghapusnya. Cari tahu lebih lanjut tentang aplikasi yang tidak diverifikasi dan dapatkan jawaban atas pertanyaan umum tentang verifikasi aplikasi di Pusat Bantuan.

Gmail API mendukung cakupan berikut:

Kode cakupan	Deskripsi	Penggunaan
https://www.googleapis.com/auth/ gmail.addons.current.action.compose	Mengelola draf dan mengirim email saat Anda berinteraksi dengan add-on.	Tidak sensitif
https://www.googleapis.com/auth/ gmail.addons.current.message.action	Melihat pesan email Anda saat Anda berinteraksi dengan add-on.	Tidak sensitif
https://www.googleapis.com/auth/ gmail.addons.current.message.metadata	Melihat metadata pesan email Anda saat add-on dijalankan.	Sensitif
https://www.googleapis.com/auth/ gmail.addons.current.message.readonly	Melihat pesan email Anda saat add-on sedang dijalankan.	Sensitif
https://www.googleapis.com/auth/ gmail.labels	Hanya membuat, membaca, memperbarui, dan menghapus label.	Tidak sensitif
https://www.googleapis.com/auth/ gmail.send	Hanya mengirim pesan. Tidak ada hak istimewa baca atau ubah pada kotak surat.	Sensitif
https://www.googleapis.com/auth/ gmail.readonly	Membaca semua resource dan metadatanya—tanpa operasi tulis.	Dibatasi
https://www.googleapis.com/auth/ gmail.compose	Membuat, membaca, memperbarui, dan menghapus draf. Mengirim pesan dan draf.	Dibatasi
https://www.googleapis.com/auth/ gmail.insert	Hanya menyisipkan dan mengimpor pesan.	Dibatasi
https://www.googleapis.com/auth/ gmail.modify	Semua operasi baca/tulis kecuali penghapusan langsung dan permanen rangkaian pesan dan pesan, dengan melewati Sampah.	Dibatasi
https://www.googleapis.com/auth/ gmail.metadata	Membaca metadata resource termasuk label, catatan histori, dan header pesan email, tetapi bukan isi pesan atau lampiran.	Dibatasi
https://www.googleapis.com/auth/ gmail.settings.basic	Mengelola setelan email dasar.	Dibatasi
https://www.googleapis.com/auth/ gmail.settings.sharing	Mengelola setelan email sensitif, termasuk aturan penerusan dan alias. Catatan:Operasi yang dilindungi oleh cakupan ini dibatasi untuk penggunaan administratif saja. API ini hanya tersedia untuk pelanggan Google Workspace yang menggunakan akun layanan dengan delegasi tingkat domain.	Dibatasi
https://mail.google.com/	Akses penuh ke kotak surat akun, termasuk penghapusan permanen rangkaian pesan dan pesan Cakupan ini hanya boleh diminta jika aplikasi Anda perlu segera dan secara permanen menghapus rangkaian pesan dan pesan, melewati Sampah; semua tindakan lainnya dapat dilakukan dengan cakupan yang kurang permisif.	Dibatasi

Kolom Penggunaan dalam tabel di atas menunjukkan sensitivitas setiap cakupan, sesuai dengan definisi berikut:

• Tidak sensitif —— Cakupan ini memberikan akses otorisasi terkecil dan hanya memerlukan verifikasi aplikasi dasar. Untuk mengetahui informasi tentang persyaratan ini, lihat Langkah-langkah untuk bersiap melakukan verifikasi.

• Sensitif — Cakupan ini memungkinkan akses ke Data Pengguna Google dan memerlukan proses verifikasi cakupan sensitif. Untuk mengetahui informasi tentang persyaratan ini, lihat Layanan Google API: Kebijakan Data Pengguna. Cakupan ini tidak memerlukan penilaian keamanan.

• Dibatasi — Cakupan ini memberikan akses luas ke Data Pengguna Google dan mengharuskan Anda menjalani proses verifikasi cakupan yang dibatasi. Untuk mengetahui informasi tentang persyaratan ini, lihat Layanan Google API: Kebijakan Data Pengguna dan Persyaratan Tambahan untuk Cakupan API Tertentu. Jika Anda menyimpan data cakupan terbatas di server (atau mengirimkannya), Anda harus menjalani penilaian keamanan.

Informasi tambahan yang mengatur penggunaan dan akses Anda ke Gmail API saat Anda meminta akses ke data pengguna dapat ditemukan di Kebijakan Data Pengguna dan Developer Layanan Gmail API.

Jika aplikasi Anda memerlukan akses ke Google API lainnya, Anda juga dapat menambahkan cakupan tersebut. Untuk mengetahui informasi selengkapnya tentang cakupan Google API, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.

Verifikasi OAuth

Penggunaan cakupan OAuth sensitif tertentu mungkin mengharuskan aplikasi Anda melalui proses verifikasi OAuth Google. Baca FAQ verifikasi OAuth untuk menentukan kapan aplikasi Anda harus melalui verifikasi dan jenis verifikasi yang diperlukan. Lihat juga Layanan Google API: Kebijakan Data Pengguna.

Mengimplementasikan otorisasi sisi server

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

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

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 Credentials, klik Create credentials > OAuth client ID untuk membuat kredensial OAuth 2.0 atau Create credentials > Service account key untuk membuat akun layanan.

2. Jika Anda membuat client ID OAuth, pilih jenis aplikasi Anda.

3. Isi formulir, lalu klik Buat.

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

Catat ID Klien 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 kepada aplikasi Anda agar dapat mengakses akun Gmail mereka dengan cakupan izin yang diminta. Setelah otorisasi awal ini, pengguna hanya akan melihat dialog izin jika ID klien 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 sekali pakai yang dapat ditukar oleh server Anda dengan token akses. Token akses ini diteruskan ke Gmail API untuk memberikan akses aplikasi Anda ke data pengguna selama jangka waktu terbatas.

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

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

#Ganti nilai CLIENTSECRETS_LOCATION dengan lokasi file credentials.json Anda.

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)

Memberi otorisasi dengan kredensial tersimpan

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

Jika Anda telah mengautentikasi pengguna, aplikasi Anda dapat mengambil token refresh dari databasenya dan menyimpan token di sesi sisi server. Jika token refresh dicabut atau tidak valid, Anda harus menangkapnya 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 mengotorisasi objek layanan Gmail dan mengirim permintaan ke API.

Buat instance objek layanan

Contoh kode ini menunjukkan cara membuat instance objek layanan, lalu memberi otorisasi untuk membuat permintaan API.

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 sah dan memeriksa kredensial yang dicabut

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

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

Operasi Gmail API lainnya didokumentasikan dalam Referensi API.

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()

Langkah berikutnya

Setelah Anda merasa nyaman mengizinkan permintaan Gmail API, Anda siap 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 Anda selama pengembangan, pastikan untuk menggunakan akun Gmail pengujian yang tidak penting bagi Anda. Tindakan ini akan mencegah Anda secara tidak sengaja menyebabkan kekacauan pada email, rangkaian pesan, dan label Anda yang sebenarnya.