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 tersebut untuk mengotomatiskan alur kerja harian Anda dengan mudah. Di lab ini, Anda akan membuat ekstensi Gmail canggih yang secara otomatis mengategorikan email dalam pesan masuk dan menyimpan kategori tersebut di spreadsheet Google. Ekstensi ini akan menggunakan RESTful API G Suite, Google Cloud Functions, dan layanan Google Cloud Platform lainnya.
Yang akan Anda build
Di 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:
- Mengizinkan akses aman ke data Gmail dan Google Spreadsheet Anda
- Ekstrak gambar yang dilampirkan ke email masuk
- Kategorikan gambar tersebut menggunakan Cloud Vision API
- Tulis kategori tersebut, alamat pengirim, dan nama lampiran ke Spreadsheet Google
Yang akan Anda pelajari
- Dasar-dasar API RESTful G Suite
- 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
Di 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 dapat Anda gunakan untuk menjalankan setiap cuplikan kode ('fungsi') secara sederhana dan skalabel.
Untuk mengaktifkan Google Cloud Functions, klik menu tiga garis di kiri atas layar untuk membuka sidebar navigasi kiri:
Temukan Cloud Functions di menu navigasi, lalu klik tombol tersebut. Klik Enable API untuk mengaktifkan Google Cloud Functions di project Anda.
Google Cloud Pub/Sub
Google Cloud Pub/Sub adalah fondasi sederhana dan skalabel untuk streaming data dan penayangan peristiwa. Di lab ini, lab ini berfungsi sebagai kurir antara Gmail dan Google Cloud Functions.
Untuk mengaktifkan Google Cloud Pub/Sub, buka sidebar navigasi sebelah kiri, cari 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 sebelah kiri, temukan Datastore dan klik. Klik Select Datastore Mode di halaman baru.
Anda dapat menggunakan lokasi database mana pun untuk lab ini. Klik Create Database untuk mengaktifkan Google Cloud Datastore; mungkin perlu waktu beberapa menit untuk menyelesaikannya.
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 mendapatkan informasi tentang cara mengaktifkan Google Cloud Vision API.
Mengaktifkan Gmail API, Google Sheets API, dan Google Cloud Vision API
Sekali lagi, buka sidebar navigasi sebelah kiri, lalu cari API & Layanan. Klik Koleksi. Di bagian Search for APIs & Services, ketik Gmail. Di hasil penelusuran, pilih Gmail API dan klik Aktifkan.
Kembali ke halaman Library API. Telusuri Google Sheets API dan aktifkan.
Ulangi proses tersebut. Telusuri Cloud Vision API, lalu aktifkan.
Membuka Google Cloud Shell
Di lab ini, Anda akan menggunakan Google Cloud Shell untuk menjalankan sebagian besar operasi. Cloud Shell menyediakan akses command line ke resource Google Cloud Platform langsung dari browser, sehingga Anda dapat mengelolanya tanpa menggunakan mesin lokal.
Untuk membuka Google Cloud Shell, klik tombol Activate Cloud Shell di kolom horizontal biru atas:
Panel baru akan muncul di bagian bawah layar:
Klik tombol Launch code editor untuk memulai Cloud Shell Code Editor:
Cloud Shell Code Editor akan terbuka di jendela baru.
Mendownload kode
Jalankan perintah di bawah ini di Cloud Shell 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 Code Editor Cloud Shell.
3. Ringkasan arsitektur
Berikut adalah alur kerja lab ini:
- Pengguna menyiapkan notifikasi push Gmail: setiap kali pesan baru masuk di kotak masuk, Gmail akan mengirimkan notifikasi ke Cloud Pub/Sub.
- Cloud Pub/Sub mengirimkan notifikasi pesan baru ke Google Cloud Functions.
- Setelah ada notifikasi pesan baru, instance Cloud Functions terhubung ke Gmail dan mengambil pesan baru.
- Jika email berisi gambar sebagai lampiran, instance Cloud Functions akan memanggil Cloud Vision API untuk menganalisis lampiran tersebut.
- Instance Cloud Functions mengupdate Spreadsheet Google pilihan Anda, yang menentukan siapa yang mengirim pesan dan tempat untuk mendownload lampiran.
4. Mengizinkan akses ke Gmail
Sebelum menyiapkan Cloud Function untuk membaca email secara otomatis, Anda harus mengizinkan aksesnya ke Gmail. Anda harus mendaftarkan klien OAuth ke Google dan membuat client ID terkait.
Mendaftarkan klien OAuth
Di menu navigasi sebelah kiri di Konsol Google Cloud, cari API & Layanan. Klik OAuth consent screen.
Ketik nama di kolom Application name, seperti GCF + Gmail Codelab. Jangan ubah setelan lain, scroll halaman ke bawah, 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 Restrictions 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:
Melakukan proses otorisasi
Dalam kode contoh, auth/index.js menetapkan dua Cloud Functions, 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 Editor Kode Cloud Shell.
Proses otorisasi akan menampilkan dua jenis token: token akses dan token refresh.
- Token akses adalah bukti identitas berumur singkat yang memberikan akses terbatas ke data Anda kepada siapa pun yang memilikinya;
auth_callbackmenyimpannya di Cloud Datastore. - Token refresh digunakan untuk memperoleh token akses baru, dan berumur lebih panjang.
Biasanya, kunci tersebut dienkripsi dan/atau disimpan terpisah dari token akses.
Edit auth/env_vars.yaml di Editor Kode Cloud Shell. Ganti YOUR-GOOGLE-CLIENT-ID dan YOUR-GOOGLE-CLIENT-SECRET dengan nilai Anda sendiri. Lihat langkah sebelumnya untuk mengetahui informasi selengkapnya. Jangan ubah nilai YOUR-GOOGLE-CLIENT-CALLBACK-URL dan YOUR-PUBSUB-TOPIC untuk saat ini.
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, beri Cloud SDK izin untuk menginstal perintah beta.
Selanjutnya, buka Konsol Google Cloud, dan klik Cloud Functions di menu navigasi sebelah kiri. Klik auth_callback dalam daftar Cloud Functions, lalu beralihlah ke tab Trigger.
Salin URL halaman tersebut. Kembali ke halaman Cloud Functions, klik auth_init di daftar Cloud Functions. Di tab Umum, klik Edit. Klik Environmental variables, networking, timeout and more, dan ganti nilai GOOGLE_CALLBACK_URL dengan URL yang baru saja Anda salin.
Klik Deploy untuk menerapkan perubahan. Ulangi prosesnya dan update auth_callback juga.
Terakhir, buka menu navigasi sebelah kiri dan klik API & Layanan > Verifikasi domain. Untuk menambahkan domain yang diotorisasi, klik Tambahkan domain. Misalnya, jika URL yang Anda salin sebelumnya terlihat seperti
https://us-central1-my-project.cloudfunctions.net/auth_callback
Anda harus menambahkan hal berikut sebagai domain yang diotorisasi:
us-central1-my-project.cloudfunctions.net
Tekan Tambahkan domain untuk mengonfirmasi.
Kembali ke halaman Credentials. Klik nama klien OAuth, lalu tambahkan URL yang Anda salin sebagai URI pengalihan yang diotorisasi. Tekan Enter untuk mengonfirmasi.
Hapus bagian /auth_callback dari URL dan tambahkan sisanya sebagai Asal JavaScript resmi. Misalnya, jika URL Anda terlihat seperti
https://us-central1-my-project.cloudfunctions.net/auth_callback
Anda harus menambahkan string berikut sebagai origin:
https://us-central1-my-project.cloudfunctions.net/
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 tersebut akan menerima notifikasi pesan masuk secara otomatis saat mereka tiba dari Gmail.
Untuk membuat topik Pub/Sub, buka Konsol Google Cloud, lalu klik Pub/Sub > Topics di menu navigasi kiri. Klik Create Topic. Ketik nama topik, misalnya gmail-watch, lalu klik Create. Selain itu, Anda harus memberi Gmail izin untuk mengirim pesan ke topik Pub/Sub Anda: klik menu konteks dari topik yang baru saja dibuat (tiga titik vertikal), lalu pilih Izin; klik Add members, tentukan gmail-api-push@system.gserviceaccount.com sebagai anggota baru, dan berikan peran Pub/Sub > Penerbit Pub/Sub; terakhir, klik Save untuk menerapkan perubahan.
Update Cloud Function auth_callback untuk menentukan topik Pub/Sub yang akan digunakan. Klik Cloud Functions di menu navigasi sebelah kiri, lalu pilih auth_callback di daftar Cloud Functions. Di tab Umum, klik Edit. Klik More, dan ganti nilai PUBSUB_TOPIC dengan nama topik Pub/Sub yang baru saja Anda buat. Klik Simpan untuk menerapkan perubahan.
Sekarang Anda siap untuk mengotorisasi dan menyiapkan notifikasi push Gmail. Tunggu hingga perubahan baru selesai, lalu kembali ke halaman Cloud Functions, pilih auth_init di daftar Cloud Functions, dan beralihlah ke tab Trigger. Klik URL, dan Anda akan dialihkan ke halaman Login dengan Google:
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:
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 Anda ketika proses ini selesai.
Codelab ini menggunakan paket @google-cloud/express-oauth2-handlers untuk mengotomatiskan alur kerja otorisasi untuk Anda. Untuk informasi selengkapnya, lihat repositorinya di GitHub.
6. Memproses pesan masuk
Seperti yang telah kami sebutkan, setiap pelanggan topik Pub/Sub yang Anda buat akan menerima notifikasi saat ada pesan baru masuk 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 Editor Kode Cloud Shell.
Mengambil pesan
Notifikasi push Gmail menyertakan alamat email yang terkait dengan notifikasi, dan ID histori. Untuk alasan kemudahan, dalam codelab ini Anda cukup meminta pesan terbaru ke Gmail API saat notifikasi push masuk; 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 menganotasi gambar. Dalam codelab ini, Anda akan meminta Cloud Vision API untuk mengklasifikasi gambar dan menampilkan sejumlah tag gambar; misalnya, jika diberikan gambar langit biru, Cloud Vision API dapat menampilkan tag blue, sky,dan ature.
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. Salinan ini mencakup nama pengirim, nama lampiran, dan tag lampiran gambar (jika ada).
Pertama, buat Spreadsheet Google. Buka Google Spreadsheet, lalu 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 Editor Kode Cloud Shell, update gcf-gmail-codelab/pubsub/env_vars.yaml, lalu 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 Code Editor pada Cloud Shell, 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 berikut di Konsol Google Cloud: buka Cloud Functions di menu navigasi sebelah kiri, pilih auth_init dalam daftar Cloud Functions, lalu cari bagian Environment variables.
Men-deploy kode
Jalankan perintah di bawah ini 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 menamai topik Cloud Pub/Sub dengan sesuatu selain gmail-watch, ganti gmail-watch pada 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 kepada diri sendiri dengan lampiran gambar. Dalam beberapa detik, Anda akan melihat Spreadsheet Google yang Anda buat akan otomatis diperbarui dengan informasi yang Anda berikan.