Memberdayakan Kotak Masuk Gmail Anda dengan Google Cloud Functions

1. Pengantar

Miliaran bisnis dan individu menggunakan Gmail dan layanan G Suite lainnya untuk berkomunikasi dan memproses data. Google menawarkan G Suite API untuk membantu Anda mengakses informasi dalam layanan ini secara terprogram, dan Anda dapat menggunakan API untuk mengotomatiskan alur kerja harian dengan mudah. Dalam lab ini, Anda akan membuat ekstensi Gmail yang canggih yang otomatis mengategorikan email dalam pesan masuk dan menyimpan kategori tersebut dalam spreadsheet Google. Ekstensi ini akan menggunakan RESTful API G Suite, Google Cloud Functions, dan layanan Google Cloud Platform lainnya.

Yang akan Anda bangun

Dalam lab ini, Anda akan membangun dan men-deploy beberapa Cloud Functions yang terhubung ke G Suite API dan layanan Google Cloud Platform lainnya. Fungsi ini akan:

  • Memberi otorisasi akses yang aman ke data Gmail dan Google Spreadsheet Anda
  • Mengekstrak gambar yang dilampirkan ke email masuk
  • Mengategorikan gambar tersebut menggunakan Cloud Vision API
  • Tulis kategori tersebut, alamat pengirim, dan nama lampiran ke Spreadsheet Google

Yang akan Anda pelajari

  • Dasar-dasar G Suite RESTful API
  • Dasar-Dasar Google Cloud Functions dan layanan Google Cloud Platform lainnya
  • Cara mengakses Gmail secara terprogram menggunakan Google Cloud Functions

Yang akan Anda butuhkan

  • Akun Google dengan akses Gmail dan Google Spreadsheet. Jika Anda belum memilikinya, buat akun di sini.
  • Pengetahuan dasar tentang Javascript/Node.js.

2. Pertama-tama

Mengaktifkan API

Dalam lab ini, Anda akan menggunakan produk/layanan Google berikut:

  • Google Cloud Functions
  • Google Cloud Pub/Sub
  • Google Cloud Vision API
  • Google Cloud Datastore
  • Gmail API
  • Google Sheets API

Google Cloud Functions

Google Cloud Functions adalah platform Functions-as-a-Service Serverless dari Google yang memungkinkan Anda menjalankan cuplikan kode individual (‘fungsi') dengan cara yang sederhana dan skalabel.

Untuk mengaktifkan Google Cloud Functions, klik menu hamburger di kiri atas layar untuk membuka sidebar navigasi kiri:

f457988e33594bb6.png

Temukan Cloud Functions di menu navigasi, lalu klik. Klik Enable API untuk mengaktifkan Google Cloud Functions di project Anda.

Google Cloud Pub/Sub

Google Cloud Pub/Sub adalah fondasi yang sederhana dan skalabel untuk streaming data dan pengiriman peristiwa. Dalam lab ini, fungsi tersebut bertindak sebagai kurir antara Gmail dan Google Cloud Functions.

Untuk mengaktifkan Google Cloud Pub/Sub, buka sidebar navigasi kiri, temukan Pub/Sub, lalu klik. Klik Enable API untuk mengaktifkan Google Cloud Pub/Sub di project Anda.

Google Cloud Datastore

Google Cloud Datastore adalah database Serverless yang skalabel dan terdistribusi.

Untuk mengaktifkan Google Cloud Datastore, di sidebar navigasi kiri, cari Datastore, lalu klik. Klik Pilih Mode Datastore di halaman baru.

98012c91fd4080d4.png

Anda dapat menggunakan lokasi database apa pun untuk lab ini. Klik Create Database untuk mengaktifkan Google Cloud Datastore; proses ini mungkin memerlukan waktu beberapa menit untuk diselesaikan.

Google Cloud Vision

Google Cloud Vision API adalah layanan machine learning canggih yang menggunakan model terlatih untuk mendapatkan insight dari gambar Anda.

Lihat petunjuk di bawah untuk mengetahui informasi tentang cara mengaktifkan Google Cloud Vision API.

Mengaktifkan Gmail API, Google Sheets API, dan Google Cloud Vision API

Sekali lagi, buka sidebar navigasi kiri, lalu temukan APIs & Services. Klik Koleksi. Di kolom Search for APIs & Services, ketik Gmail. Di hasil penelusuran, pilih Gmail API, lalu klik Aktifkan.

Kembali ke halaman API Library. Telusuri Google Sheets API dan aktifkan.

Ulangi prosesnya. Telusuri Cloud Vision API dan aktifkan.

Membuka Google Cloud Shell

Dalam lab ini, Anda akan menggunakan Google Cloud Shell untuk melakukan sebagian besar operasi. Cloud Shell menyediakan akses command line ke resource Google Cloud Platform langsung dari browser Anda, sehingga Anda dapat mengelolanya tanpa menggunakan komputer lokal.

Untuk membuka Google Cloud Shell, klik tombol Activate Cloud Shell di panel horizontal biru atas:

fd5c2925ca9cdfdd.png

Panel baru akan muncul di bagian bawah layar:

34f498402e910802.png

Klik tombol Launch code editor untuk memulai Editor Kode Cloud Shell:

10f8631ef48bed22.png

Cloud Shell Code Editor akan terbuka di jendela baru.

Mendownload kode

Jalankan perintah di bawah di Cloud Shell Anda untuk meng-clone project:

git clone https://github.com/googlecodelabs/gcf-gmail-codelab.git

cd gcf-gmail-codelab

Anda akan melihat folder baru, gcf-gmail-codelab, muncul di Editor Kode Cloud Shell.

3. Ringkasan arsitektur

Berikut adalah alur kerja lab ini:

79c5d3e43f674b33.png

  1. Pengguna menyiapkan notifikasi push Gmail: setiap kali ada pesan baru masuk ke kotak masuk, Gmail akan mengirimkan notifikasi ke Cloud Pub/Sub.
  2. Cloud Pub/Sub mengirimkan notifikasi pesan baru ke Google Cloud Functions.
  3. Setelah notifikasi pesan baru tiba, instance Cloud Functions akan terhubung ke Gmail dan mengambil pesan baru.
  4. Jika email memiliki gambar sebagai lampiran, instance Cloud Functions akan memanggil Cloud Vision API untuk menganalisis lampiran tersebut.
  5. Instance Cloud Functions memperbarui Spreadsheet Google pilihan Anda, dengan menentukan siapa yang mengirim pesan dan tempat untuk mendownload lampiran.

4. Memberi otorisasi akses ke Gmail

Sebelum menyiapkan Cloud Function untuk membaca email Anda secara otomatis, Anda harus mengizinkan aksesnya ke Gmail. Anda harus mendaftarkan klien OAuth ke Google dan membuat ID klien terkait.

Mendaftarkan klien OAuth

Di menu navigasi kiri Konsol Google Cloud, temukan APIs & Services. Klik OAuth consent screen.

91b2a3bac30bb2c5.png

Ketik nama di kolom Application name, seperti GCF + Gmail Codelab. Biarkan setelan lainnya tidak diubah, scroll ke bawah halaman, lalu klik Simpan.

Membuat client ID terkait

Beralihlah ke tab Credentials. Klik Create Credentials, lalu pilih OAuth client ID. Pilih jenis Web application, beri nama (Anda dapat menggunakan GCF + Gmail Codelab lagi di sini), lalu klik Create. Biarkan kolom Pembatasan kosong untuk saat ini.

Catat client ID dan rahasia klien yang ditampilkan di jendela pop-up. Anda dapat mengklik nama klien di halaman untuk melihat nilai ini lagi:

1160d8027ea52d90.png

Melakukan proses otorisasi

Dalam contoh kode, auth/index.js menentukan dua Cloud Function, auth_init dan auth_callback, yang bekerja sama untuk melakukan proses otorisasi, menggunakan client ID dan rahasia klien yang baru saja Anda buat.

Untuk memeriksa kode, buka auth/index.js di Cloud Shell Code Editor.

Proses otorisasi menampilkan dua jenis token: token akses dan token refresh.

  • Token akses adalah bukti identitas sementara yang memberikan akses yang tercakup kepada siapa pun yang memilikinya ke data Anda; auth_callback menyimpannya di Cloud Datastore.
  • Token refresh digunakan untuk mendapatkan token akses baru, dan memiliki masa berlaku yang jauh lebih lama.

Biasanya, kunci ini dienkripsi dan/atau disimpan secara terpisah dari token akses.

Edit auth/env_vars.yaml di Cloud Shell Code Editor. Ganti YOUR-GOOGLE-CLIENT-ID dan YOUR-GOOGLE-CLIENT-SECRET dengan nilai Anda sendiri. Lihat langkah sebelumnya untuk mengetahui informasi selengkapnya. Biarkan nilai YOUR-GOOGLE-CLIENT-CALLBACK-URL dan YOUR-PUBSUB-TOPIC tidak berubah untuk saat ini.

a2b4853c39a78bc6.png

Setelah mengedit auth/env_vars.yaml, jalankan perintah berikut di Cloud Shell untuk men-deploy Cloud Functions:

cd ~
cd gcf-gmail-codelab/auth

# Deploy Cloud Function auth_init
gcloud functions deploy auth_init --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml

# Deploy Cloud Function auth_callback
gcloud functions deploy auth_callback --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml

Mungkin perlu waktu beberapa menit untuk men-deploy Cloud Functions. Jika diminta, berikan izin kepada Cloud SDK untuk menginstal perintah beta.

Selanjutnya, buka Konsol Google Cloud, lalu klik Cloud Functions di menu navigasi di sebelah kiri. Klik auth_callback dalam daftar Cloud Functions, lalu beralih ke tab Trigger.

cb094bd341f9b299.png

45678a327c80e0f1.png

Salin URL di halaman. Kembali ke halaman Cloud Functions, klik auth_init dalam daftar Cloud Functions. Di tab General, klik Edit. Klik Environmental variables, networking, timeouts and more, lalu ganti nilai GOOGLE_CALLBACK_URL dengan URL yang baru saja Anda salin.

939ca3bd38047282.png

Klik Deploy untuk menerapkan perubahan. Ulangi prosesnya dan perbarui auth_callback juga.

Terakhir, buka menu navigasi kiri, lalu klik APIs & Services > Domain verification. Untuk menambahkan domain resmi, klik Tambahkan domain. Misalnya, jika URL yang Anda salin sebelumnya terlihat seperti

https://us-central1-my-project.cloudfunctions.net/auth_callback

Anda harus menambahkan berikut sebagai domain yang diotorisasi:

us-central1-my-project.cloudfunctions.net

Tekan Tambahkan domain untuk mengonfirmasi.

4348748f232ceb87.png

Kembali ke halaman Credentials. Klik nama klien OAuth Anda, lalu tambahkan URL yang Anda salin sebagai URI pengalihan yang diotorisasi. Tekan Enter untuk mengonfirmasi.

Hapus bagian /auth_callback dari URL dan tambahkan bagian lainnya sebagai Authorized Javascript origin. Misalnya, jika URL Anda terlihat seperti

https://us-central1-my-project.cloudfunctions.net/auth_callback

Anda harus menambahkan hal berikut sebagai asal:

https://us-central1-my-project.cloudfunctions.net/

159bad719432582c.png

Tekan Enter untuk mengonfirmasi dan klik Simpan untuk menerapkan perubahan.

5. Menyiapkan notifikasi push Gmail

Jika proses otorisasi berhasil, auth_callback akan otomatis memanggil Gmail API untuk menyiapkan notifikasi push.

Untuk menerima notifikasi push Gmail, Anda harus membuat topik Pub/Sub. Setiap pelanggan topik akan otomatis menerima notifikasi pesan masuk saat pesan tiba dari Gmail.

Untuk membuat topik Pub/Sub, buka Konsol Google Cloud, lalu klik Pub/Sub > Topics di menu navigasi sebelah kiri. Klik Buat Topik. Ketik nama topik, seperti gmail-watch, lalu klik Buat. Selain itu, Anda harus memberikan izin kepada Gmail untuk mengirim pesan ke topik Pub/Sub Anda: klik menu konteks topik yang baru saja Anda buat (tiga titik vertikal), lalu pilih Permissions; klik Add members, tentukan gmail-api-push@system.gserviceaccount.com sebagai anggota baru, lalu berikan peran Pub/Sub > Pub/Sub Publisher; terakhir, klik Save untuk menerapkan perubahan.

Perbarui Cloud Function auth_callback untuk menentukan topik Pub/Sub yang akan digunakan. Klik Cloud Functions di menu navigasi sebelah kiri, lalu pilih auth_callback dalam daftar Cloud Functions. Di tab General, klik Edit. Klik More, lalu ganti nilai PUBSUB_TOPIC dengan nama topik Pub/Sub yang baru saja Anda buat. Klik Simpan untuk menerapkan perubahan.

Sekarang Anda siap untuk mengizinkan dan menyiapkan notifikasi push Gmail. Tunggu hingga perubahan baru selesai, lalu kembali ke halaman Cloud Functions, pilih auth_init dalam daftar Cloud Functions, dan beralih ke tab Trigger. Klik URL, dan Anda akan dialihkan ke halaman Login dengan Google:

348ab0a7e0c9cd03.png

Login dengan akun Gmail yang Anda miliki. Setiap pesan baru yang masuk ke kotak masuk akun akan memicu notifikasi push. Setelah login, Anda akan melihat halaman di bawah:

cfdad62fd02de004.png

Klik Izinkan untuk mengizinkan akses. auth_callback akan menyelesaikan proses otorisasi, menyimpan token akses, dan menyiapkan notifikasi push Gmail untuk Anda. Anda akan melihat pesan Successfully set up Gmail push notifications di browser saat proses ini selesai.

Codelab ini menggunakan paket @google-cloud/express-oauth2-handlers untuk mengotomatiskan alur kerja otorisasi untuk Anda. Untuk mengetahui informasi selengkapnya, lihat repositorinya di GitHub.

6. Memproses pesan masuk

Seperti yang kami sebutkan sebelumnya, setiap pelanggan topik Pub/Sub yang Anda buat akan menerima notifikasi saat pesan baru tiba di kotak masuk Anda. pubsub/index.js menentukan Cloud Function, watchGmailMessages, yang, setelah di-deploy sebagai pelanggan topik, akan membaca pesan baru, mengategorikan gambar terlampir, dan mengekspor kategori tersebut ke Spreadsheet Google.

Untuk memeriksa kode, buka pubsub/index.js di Cloud Shell Code Editor.

Mengambil pesan

Notifikasi push Gmail mencakup alamat email yang terkait dengan notifikasi, dan ID histori. Untuk alasan kesederhanaan, dalam codelab ini Anda cukup meminta pesan terbaru dari Gmail API saat notifikasi push tiba; untuk hasil yang lebih baik, gunakan ID histori untuk mencari pesan.

// Look up the most recent message.
const listMessagesRes = await gmail.users.messages.list({
  userId: email,
  maxResults: 1
});
const messageId = listMessagesRes.messages[0].id;

// Get the message using the message ID.
const message = await gmail.users.messages.get({
  userId: email,
  id: messageId
});

return message;

Menganalisis lampiran gambar

Jika pesan memiliki lampiran gambar, watchGmailMessages akan memanggil Cloud Vision API untuk membuat anotasi pada gambar. Dalam codelab ini, Anda akan meminta Cloud Vision API untuk mengklasifikasikan gambar dan menampilkan sejumlah tag gambar; misalnya, jika diberi gambar langit biru, Cloud Vision API dapat menampilkan tag biru, langit,dan alam.

watchGmailMessages menggunakan Library Cloud Vision API untuk Node.js guna memanggil Cloud Vision API:

// Tag the attachment using Cloud Vision API
const analyzeAttachment = async (data, filename) => {
  var topLabels = ['', '', ''];
  if (filename.endsWith('.png') || filename.endsWith('.jpg')) {
    const [analysis] = await visionClient.labelDetection({
      image: {
        content: Buffer.from(data, 'base64')
      }
    });
    const labels = analysis.labelAnnotations;
    topLabels = labels.map(x => x.description).slice(0, 3);
  }

  return topLabels;
};

Perbarui Spreadsheet Google

watchGmailMessages mengekspor hasil analisis ini ke Spreadsheet Google. Email ini mencakup nama pengirim, nama lampiran, dan tag lampiran gambar (jika ada).

Pertama, buat Spreadsheet Google. Buka Google Spreadsheet dan klik template Kosong di bagian Mulai spreadsheet baru. Salin ID sheet Anda. Misalnya, jika alamat di browser Anda terlihat seperti ini:

https://docs.google.com/spreadsheets/d/abcdefghij01234567890/edit#gid=0

ID spreadsheet Anda adalah abcdefghij01234567890. Di Cloud Shell Code Editor, perbarui gcf-gmail-codelab/pubsub/env_vars.yaml, dan ganti YOUR-GOOGLE-SHEET-ID dengan nilai Anda sendiri.

watchGmailMessages terhubung dengan Google Sheets API untuk menambahkan informasi:

const updateReferenceSheet = async (from, filename, topLabels) => {
  await googleSheets.spreadsheets.values.append({
    spreadsheetId: SHEET,
    range: SHEET_RANGE,
    valueInputOption: 'USER_ENTERED',
    requestBody: {
      range: SHEET_RANGE,
      majorDimension: 'ROWS',
      values: [
        [from, filename].concat(topLabels)
      ]
    }
  });
};

Satu langkah terakhir

Di Cloud Shell Code Editor, buka gcf-gmail-codelab/pubsub/env_vars.yaml dan ganti YOUR-GOOGLE-CLIENT-ID, YOUR-GOOGLE-CLIENT-SECRET, dan YOUR-GOOGLE-CALLBACK-URL dengan nilai Anda sendiri. Anda dapat menemukan nilai ini di Konsol Google Cloud: buka Cloud Functions di menu navigasi kiri, pilih auth_init dalam daftar Cloud Functions, lalu cari bagian Environment variables.

Deploy kode

Jalankan perintah di bawah untuk men-deploy Cloud Function:

cd ~

cd gcf-gmail-codelab/pubsub

gcloud functions deploy watchGmailMessages --runtime=nodejs8 --trigger-topic=gmail-watch --env-vars-file=env_vars.yaml

Jika Anda memberi nama topik Cloud Pub/Sub selain gmail-watch, ganti gmail-watch dalam perintah di atas dengan nama topik Anda. Mungkin perlu waktu beberapa detik untuk men-deploy Cloud Function.

7. Cobalah

Selamat, Anda sudah selesai! Kirim email ke diri Anda sendiri dengan lampiran gambar. Dalam beberapa detik, Anda akan melihat Google Spreadsheet yang Anda buat diperbarui secara otomatis dengan informasi yang Anda berikan.