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.

Prasyarat

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:

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

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

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:

Topik terkait

• Menerima dan merespons interaksi pengguna
• Mengautentikasi serta memberi otorisasi aplikasi Google Chat dan permintaan Google Chat API
• Menghubungkan add-on Google Workspace ke layanan pihak ketiga

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