Menghubungkan aplikasi Chat dengan layanan dan alat lainnya

Halaman ini menjelaskan cara menghubungkan aplikasi Google Chat dengan layanan atau alat di luar Google Chat. Meskipun aplikasi Chat sangat canggih, aplikasi ini sering kali bekerja sama dengan sistem lain dan memerlukan aplikasi pendamping untuk menghubungkan akun, mengizinkan akses data, menampilkan data tambahan, atau mengonfigurasi preferensi pengguna.

Untuk mengautentikasi pengguna dengan layanan pihak ketiga atau alur OAuth, aplikasi Chat Anda melakukan langkah-langkah berikut:

  1. Mendeteksi saat otorisasi atau konfigurasi diperlukan.
  2. Menampilkan kartu otorisasi dasar yang meminta pengguna untuk login atau mengonfigurasi layanan.
  3. Lakukan pengalihan ke URI penyelesaian sehingga Google Chat akan otomatis mencoba ulang interaksi asli setelah pengguna menyelesaikan otorisasi.

Arsitektur cara aplikasi Google Chat melakukan autentikasi dengan layanan pihak ketiga.

Prasyarat

HTTP

Aplikasi Google Chat yang menerima dan merespons interaksi pengguna. Untuk membuatnya, selesaikan panduan memulai HTTP.

Apps Script

Aplikasi Google Chat yang menerima dan merespons interaksi pengguna. Untuk membuatnya, selesaikan panduan memulai Apps Script.

Mendeteksi bahwa otorisasi diperlukan

Saat berinteraksi dengan aplikasi Chat Anda, pengguna mungkin tidak diizinkan untuk mengakses resource yang dilindungi karena berbagai alasan, seperti berikut:

  • Token akses untuk terhubung ke layanan pihak ketiga belum dibuat atau masa berlakunya telah berakhir.
  • Token akses tidak mencakup resource yang diminta.
  • Token akses tidak mencakup cakupan yang diperlukan permintaan.

Aplikasi Chat Anda harus mendeteksi kasus ini agar pengguna dapat login dan mengizinkan akses ke layanan Anda.

Jika Anda membangun di Apps Script, Anda dapat menggunakan library OAuth2 untuk Google Apps Script (atau versi OAuth1), dengan fungsi hasAccess yang memeriksa apakah pengguna telah mengizinkan akses ke layanan. Atau, saat menggunakan permintaan UrlFetchApp.fetch, Anda dapat menetapkan parameter muteHttpExceptions ke true untuk memeriksa kode respons dan konten dalam objek HttpResponse yang ditampilkan.

Mengarahkan pengguna dengan kartu otorisasi dasar

Saat aplikasi Chat Anda mendeteksi bahwa otorisasi atau konfigurasi diperlukan, kembalikan respons AuthorizationError untuk menampilkan kartu otorisasi dasar pribadi kepada pengguna.

Gambar berikut menunjukkan contoh kartu otorisasi dasar Google:

Dialog otorisasi dasar untuk Akun Contoh.
Gambar 1: Dialog otorisasi dasar untuk Akun Contoh. Dialog tersebut menyatakan bahwa aplikasi Chat ingin menampilkan informasi tambahan, tetapi memerlukan persetujuan pengguna untuk mengakses akun.

Untuk meminta pengguna dengan kartu otorisasi dasar, tampilkan objek AuthorizationError:

HTTP

Tampilkan respons JSON berikut:

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

Apps Script

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

Ganti kode berikut:

  • AUTHORIZATION_URL: URL HTTPS untuk aplikasi web yang menangani autentikasi, otorisasi, atau konfigurasi.
  • RESOURCE_DISPLAY_NAME: Nama tampilan untuk layanan atau resource yang dilindungi. Nama ini ditampilkan kepada pengguna pada dialog otorisasi. Misalnya, jika RESOURCE_DISPLAY_NAME Anda adalah Example Account, perintah akan menyatakan bahwa aplikasi memerlukan persetujuan untuk mengakses Example Account Anda.

Menyelesaikan permintaan konfigurasi

Di Chat, pengguna dapat menyelesaikan proses otorisasi dan meminta Chat mencoba kembali interaksi asli secara otomatis tanpa memuat ulang secara manual. Chat mendukung percobaan ulang otomatis jika pemicunya adalah Pesan, Ditambahkan ke ruang, atau Perintah aplikasi.

Untuk pemicu ini, aplikasi Chat Anda menerima URI pengalihan penyelesaian (configCompleteRedirectUri / completeRedirectUri) di payload peristiwa:

  • Pesan: chat.messagePayload.configCompleteRedirectUri
  • Ditambahkan ke ruang: chat.addedToSpacePayload.configCompleteRedirectUri
  • Perintah aplikasi: chat.appCommandPayload.configCompleteRedirectUri

Anda harus mengenkode URI pengalihan ini di <var>AUTHORIZATION_URL</var> dan mengalihkan browser pengguna ke URI tersebut setelah alur otorisasi selesai. Pengalihan ke URL ini memberi sinyal ke Google Chat bahwa permintaan otorisasi atau konfigurasi telah dipenuhi.

Saat pengguna berhasil dialihkan ke URI pengalihan penyelesaian yang diberikan dalam payload peristiwa asli, Google Chat akan melakukan langkah-langkah berikut:

  1. Menghapus dialog otorisasi pribadi yang ditampilkan kepada pengguna yang memulai.
  2. Mengubah pesan asli menjadi publik, sehingga dapat dilihat oleh anggota ruang lainnya.
  3. Mengirim objek peristiwa asli ke aplikasi Chat Anda untuk kedua kalinya.

Jika Anda tidak mengalihkan ke URI pengalihan penyelesaian, pengguna masih dapat menyelesaikan alur otorisasi, tetapi Google Chat tidak otomatis mencoba ulang eksekusi sebelumnya dan pengguna harus memanggil aplikasi Chat Anda secara manual lagi.

Mengunjungi URI pengalihan penyelesaian hanya memengaruhi satu interaksi pengguna. Jika pengguna telah mengirim pesan ke aplikasi Chat beberapa kali dan menerima beberapa perintah, menyelesaikan proses autentikasi dan konfigurasi untuk satu perintah hanya akan mencoba ulang interaksi tertentu tersebut.

Mengautentikasi pengguna Chat di luar Chat

Saat menautkan ke URL di luar Chat (seperti callback web OAuth), Anda sering kali perlu mengorelasikan sesi web eksternal dengan identitas pengguna di Chat. Sebaiknya Anda melindungi aplikasi web tujuan dengan Login dengan Google.

Gunakan token identitas yang dikeluarkan selama login untuk mendapatkan ID pengguna. Klaim sub berisi ID Google unik pengguna dan dapat dikorelasikan dengan nama resource pengguna (chat.user.name) dari Google Chat.

Untuk mengorelasikan klaim sub dengan nama resource users/{user} Google Chat, tambahkan awalan users/ pada nilai klaim sub. Misalnya, nilai klaim sub 123 sesuai dengan users/123 dalam objek peristiwa yang dikirim ke aplikasi Chat Anda.

Contoh kode

Contoh kode berikut menunjukkan cara aplikasi Chat dapat meminta kredensial OAuth2 offline menggunakan kartu otorisasi dasar, menyimpannya dalam database, mengalihkan ke URI penyelesaian, dan melakukan panggilan API dengan autentikasi pengguna:

Aplikasi Chat yang bukan add-on: Menghubungkan aplikasi Chat dengan layanan dan alat lainnya

Jika Anda mengelola aplikasi Chat yang bukan add-on Google Workspace, aplikasi Chat Anda akan meminta konfigurasi menggunakan actionResponse berjenis REQUEST_CONFIG dan membaca configCompleteRedirectUrl dari objek Event tingkat teratas.

Untuk mengupgrade aplikasi Chat yang bukan add-on ke framework add-on Google Workspace, lihat Mengonversi aplikasi Google Chat menjadi add-on Google Workspace.

Meminta konfigurasi dari pengguna di aplikasi Chat yang bukan add-on

Di aplikasi Chat yang bukan add-on, tampilkan URL konfigurasi kepada pengguna dalam bentuk berikut:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

Hal ini memberi tahu Google Chat untuk menampilkan perintah pribadi kepada pengguna, dengan CONFIGURATION_URL adalah link yang dapat dikunjungi pengguna untuk melakukan autentikasi, otorisasi, atau konfigurasi tambahan. Respons REQUEST_CONFIG tidak dapat digunakan bersamaan dengan pesan respons biasa; teks, kartu, atau atribut lainnya diabaikan.

Menyelesaikan permintaan konfigurasi di aplikasi Chat yang bukan add-on

Setiap interaksi MESSAGE, ADDED_TO_SPACE, dan APP_COMMAND Event yang diterima aplikasi Chat yang bukan add-on mencakup kolom tingkat teratas configCompleteRedirectUrl. Enkode URL ini di URL konfigurasi Anda dan alihkan pengguna ke URL tersebut setelah selesai sehingga Google Chat menghapus perintah, mengonversi pesan asli menjadi publik, dan mengirim ulang peristiwa interaksi asli ke aplikasi Chat Anda.

Untuk contoh penerapan, lihat contoh aplikasi konektivitas Node.js dan contoh aplikasi autentikasi MyProfile Python di GitHub.