Permintaan ke Gmail API harus diizinkan menggunakan kredensial OAuth 2.0. Anda harus menggunakan alur sisi server saat aplikasi perlu mengakses Google API atas nama pengguna, misalnya saat pengguna sedang offline. Pendekatan ini mengharuskan penerusan kode otorisasi satu kali dari klien ke server; kode ini digunakan untuk mendapatkan token akses dan token refresh untuk server Anda.
Untuk mempelajari lebih lanjut implementasi Google OAuth 2.0 sisi server, lihat Menggunakan OAuth 2.0 untuk Aplikasi Server Web.
Daftar Isi
Membuat client ID dan rahasia klien
Untuk mulai menggunakan Gmail API, Anda harus terlebih dahulu menggunakan alat penyiapan, yang akan memandu Anda menyelesaikan pembuatan project di Konsol API Google, mengaktifkan API, dan membuat kredensial.
- Dari halaman Credentials, klik Create credentials > OAuth client ID untuk membuat kredensial OAuth 2.0 Anda atau Create credentials > Service account key untuk membuat akun layanan.
- Jika Anda membuat client ID OAuth, pilih jenis aplikasi Anda.
- 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 akan perlu menambahkannya ke kode nanti.
Menangani permintaan otorisasi
Saat memuat aplikasi Anda untuk pertama kalinya, pengguna akan melihat dialog untuk memberikan izin bagi aplikasi Anda agar dapat 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 akan menampilkan objek hasil otorisasi yang berisi kode otorisasi jika berhasil.
Menukarkan 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 memberi aplikasi Anda akses ke data pengguna dalam waktu yang terbatas.
Jika aplikasi Anda memerlukan akses offline, saat pertama kali aplikasi bertukar
kode otorisasi, aplikasi juga menerima token refresh yang digunakan untuk
menerima token akses baru setelah masa berlaku token sebelumnya berakhir. Aplikasi Anda menyimpan token refresh ini (umumnya dalam database di server Anda) untuk digunakan nanti.
Contoh kode berikut menunjukkan pertukaran kode otorisasi untuk token akses dengan akses offline dan penyimpanan 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 yang disimpan
Saat pengguna mengunjungi aplikasi Anda setelah alur otorisasi pertama kali berhasil, aplikasi Anda dapat menggunakan token refresh yang tersimpan untuk mengizinkan permintaan tanpa meminta pengguna lagi.
Jika Anda telah mengautentikasi pengguna, aplikasi Anda dapat mengambil token refresh dari database-nya dan menyimpan token tersebut di sesi sisi server. Jika token refresh dicabut atau tidak valid, Anda harus mengetahui hal ini dan melakukan tindakan yang sesuai.
Menggunakan kredensial OAuth 2.0
Setelah kredensial OAuth 2.0 diambil seperti ditunjukkan di bagian sebelumnya, kredensial tersebut dapat digunakan untuk mengizinkan objek layanan Gmail dan mengirimkan permintaan ke API.
Membuat instance objek layanan
Contoh kode ini menunjukkan cara membuat instance objek layanan, lalu memberinya 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 yang diotorisasi untuk mengambil daftar pesan.
Jika terjadi error, kode akan memeriksa kode status 401 HTTP, yang seharusnya ditangani dengan mengalihkan pengguna ke URL otorisasi.
Operasi API Gmail 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 merasa nyaman melakukan otorisasi 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.