Mengautentikasi serta mengizinkan aplikasi Chat dan permintaan Google Chat API

Otentikasi dan otorisasi adalah mekanisme yang digunakan untuk memverifikasi identitas dan akses ke sumber daya. Dokumen ini menguraikan bagaimana otentikasi dan otorisasi untuk aplikasi Chat dan permintaan Chat API.

Ringkasan proses

Diagram berikut menunjukkan langkah-langkah tingkat tinggi otentikasi dan otorisasi untuk Google Chat:

Langkah-langkah tingkat tinggi untuk autentikasi dan otorisasi Google Chat
Gambar 1. Langkah-langkah tingkat tinggi untuk autentikasi dan otorisasi Google Chat.

  1. Mengonfigurasi project Google Cloud, mengaktifkan Chat API, dan mengonfigurasi Aplikasi Chat: Selama pengembangan, Anda akan membuat project Google Cloud Anda. Di project Google Cloud, Anda mengaktifkan Chat API, mengonfigurasi aplikasi Chat Anda, dan menyiapkan autentikasi. Untuk informasi selengkapnya, lihat Mengembangkan di Google Workspace dan Membangun aplikasi Chat.

  2. Call Chat API: Saat aplikasi memanggil metode Chat API, lapisan ini mengirimkan kredensial autentikasi ke API Chat. Jika aplikasi Anda melakukan otentikasi dengan akun layanan, kredensial akan dikirim sebagai pada kode aplikasi Anda. Jika aplikasi Anda perlu memanggil Chat API menggunakan otentikasi pengguna yang belum diberikan, maka akan meminta untuk login.

  3. Minta resource: Aplikasi Anda meminta akses dengan cakupan yang Anda tentukan saat menyiapkan otentikasi.

  4. Minta izin: Jika aplikasi Anda diautentikasi sebagai pengguna, Google akan menampilkan layar izin OAuth sehingga pengguna dapat memutuskan apakah akan memberikan aplikasi Anda atau tidak akses ke data yang diminta. Otentikasi dengan akun layanan tidak memerlukan izin pengguna.

  5. Kirim permintaan fasilitas yang disetujui: Jika pengguna mengizinkan cakupan otorisasi, app bundle Anda, kredensial, dan cakupan ke dalam permintaan. Permintaan dikirim ke server otorisasi Google untuk memperoleh token akses.

  6. Google menampilkan token akses: Token akses berisi daftar cakupan yang diberikan. Jika daftar cakupan yang ditampilkan lebih ketat daripada cakupan yang diminta, aplikasi Anda akan menonaktifkan fitur apa pun yang dibatasi oleh token.

  7. Mengakses resource yang diminta: Aplikasi Anda menggunakan token akses dari Google untuk memanggil Chat API dan mengakses resource Chat API.

  8. Dapatkan token refresh (opsional): Jika aplikasi Anda harus mengakses Google Chat API setelah masa berlaku token akses tunggal, dapat memperoleh token refresh. Untuk informasi selengkapnya, lihat Gunakan OAuth 2.0 untuk mengakses Google API.

  9. Minta lebih banyak sumber daya: Jika aplikasi Anda membutuhkan lebih banyak akses, aplikasi akan meminta pengguna untuk melakukannya untuk memberikan cakupan baru, sehingga menghasilkan permintaan baru untuk mendapatkan token akses (langkah 3-6).

Saat aplikasi Chat memerlukan autentikasi

Aplikasi chat dapat mengirim pesan sebagai respons terhadap interaksi pengguna, atau secara asinkron. Mereka juga dapat menyelesaikan tugas atas nama pengguna, seperti membuat ruang Chat atau mendapatkan daftar orang dalam Ruang Chat.

Aplikasi Chat tidak memerlukan autentikasi untuk merespons interaksi pengguna, kecuali jika aplikasi Chat memanggil Chat API atau Google API lain saat memproses respons.

Untuk mengirim pesan asinkron atau melakukan tugas atas nama pengguna, Aplikasi chat membuat permintaan RESTful ke Chat API, yang memerlukan otentikasi dan otorisasi.

Respons ke interaksi pengguna tidak memerlukan autentikasi

Aplikasi Google Chat tidak perlu melakukan autentikasi sebagai pengguna atau Aplikasi Chat untuk menerima dan merespons secara sinkron ke peristiwa interaksi.

Aplikasi Google Chat menerima peristiwa interaksi setiap kali pengguna berinteraksi atau memanggil aplikasi Chat, termasuk hal-hal berikut:

  • Pengguna mengirim pesan ke aplikasi Chat.
  • Pengguna @menyebut aplikasi Chat.
  • Pengguna memanggil salah satu aplikasi Chat perintah garis miring.

Diagram berikut menunjukkan urutan permintaan-respons antara Pengguna Chat dan aplikasi Chat:

Tidak diperlukan otorisasi untuk peristiwa interaksi aplikasi Chat
Gambar 2.Peristiwa interaksi aplikasi Chat tidak memerlukan autentikasi.

  1. Pengguna mengirim pesan ke aplikasi Chat di Google Chat.
  2. Google Chat akan meneruskan pesan ke aplikasi.
  3. Aplikasi menerima pesan, memprosesnya, dan mengembalikan respons ke Google Chat.
  4. Google Chat merender respons untuk pengguna, atau dalam ruang.

Urutan ini berulang untuk setiap interaksi aplikasi Chat peristiwa.

Pesan asinkron memerlukan autentikasi

Pesan asinkron terjadi ketika aplikasi Chat membuat permintaan ke Chat API, yang membutuhkan otentikasi dan otorisasi.

Dengan memanggil Chat API, aplikasi Chat dapat memposting pesan ke Google Chat atau menyelesaikan tugas dan mengakses data atas nama pengguna. Sebagai misalnya, setelah mendeteksi pemadaman server, aplikasi Chat dapat memanggil Chat API untuk:

  • Buat ruang Chat khusus untuk menyelidiki dan memperbaiki pemadaman layanan.
  • Tambahkan orang ke ruang Chat.
  • Posting pesan ke ruang Chat untuk memberikan detail tentang pemadaman layanan.

Diagram berikut menunjukkan urutan pesan asinkron antara Aplikasi Chat dan ruang Chat:

Autentikasi diperlukan untuk pesan asinkron
Gambar 3. Pesan asinkron memerlukan autentikasi.

  1. Aplikasi Chat membuat pesan dengan memanggil Chat API menggunakan spaces.messages.create metode, dan menyertakan kredensial pengguna dalam permintaan HTTP.
  2. Google Chat mengautentikasi aplikasi Chat dengan akun layanan atau kredensial pengguna.
  3. Google Chat merender pesan aplikasi ke Chat tertentu spasi.

Cakupan Chat API

Mengonfigurasi layar izin OAuth dan memilih cakupan untuk menentukan informasi yang akan ditampilkan kepada pengguna dan peninjau aplikasi, dan mendaftarkan aplikasi Anda sehingga Anda dapat memublikasikannya nanti.

Untuk menentukan tingkat akses yang diberikan ke aplikasi, Anda perlu mengidentifikasi dan mendeklarasikan cakupan otorisasi. Cakupan otorisasi adalah URI OAuth 2.0 string yang berisi nama aplikasi Google Workspace, jenis data yang akses, dan tingkat akses.

Cakupan tidak sensitif

Kode cakupan Deskripsi
https://www.googleapis.com/auth/chat.bot

Cakupan chat.bot hanya mendukung akun layanan. Anda tidak dapat mengotentikasi dengan kredensial pengguna atau dengan delegasi tingkat domain menggunakan cakupan ini.

Mengizinkan aplikasi Chat melihat chat dan mengirim pesan. Memberi akses ke semua fitur yang tersedia untuk aplikasi Chat.

Cakupan sensitif

Kode cakupan Deskripsi
https://www.googleapis.com/auth/chat.spaces Membuat percakapan dan ruang serta melihat atau mengedit metadata (termasuk setelan histori dan setelan akses) di Chat.
https://www.googleapis.com/auth/chat.spaces.create Membuat percakapan baru di Chat.
https://www.googleapis.com/auth/chat.spaces.readonly Melihat chat dan ruang di Chat.
https://www.googleapis.com/auth/chat.memberships Melihat, menambahkan, memperbarui, dan menghapus anggota dari percakapan di Chat.
https://www.googleapis.com/auth/chat.memberships.app Menambahkan dan menghapus dirinya sendiri dari percakapan di Google Chat.
https://www.googleapis.com/auth/chat.memberships.readonly Melihat anggota dalam percakapan Chat.
https://www.googleapis.com/auth/chat.messages.create Menulis dan mengirim pesan di Chat.
https://www.googleapis.com/auth/chat.messages.reactions Melihat, menambahkan, dan menghapus reaksi pada pesan di Chat.
https://www.googleapis.com/auth/chat.messages.reactions.create Menambahkan reaksi pada pesan di Chat.
https://www.googleapis.com/auth/chat.messages.reactions.readonly Melihat reaksi terhadap pesan di Chat.
https://www.googleapis.com/auth/chat.users.readstate Melihat dan mengubah waktu baca terakhir untuk percakapan Chat.
https://www.googleapis.com/auth/chat.users.readstate.readonly Melihat waktu terakhir dibaca untuk percakapan Chat.
https://www.googleapis.com/auth/chat.admin.spaces.readonly Melihat chat dan ruang yang dimiliki oleh domain administrator di Chat.
https://www.googleapis.com/auth/chat.admin.spaces Melihat atau mengedit chat dan ruang yang dimiliki oleh domain administrator di Chat.
https://www.googleapis.com/auth/chat.admin.memberships.readonly Melihat anggota dan pengelola dalam percakapan yang dimiliki oleh domain administrator di Chat.
https://www.googleapis.com/auth/chat.admin.memberships Melihat, menambahkan, memperbarui, dan menghapus anggota serta pengelola dalam percakapan yang dimiliki oleh domain administrator di Chat.

Cakupan yang dibatasi

Kode cakupan Deskripsi
https://www.googleapis.com/auth/chat.delete Menghapus percakapan dan ruang, serta menghapus akses ke file terkait di Chat.
https://www.googleapis.com/auth/chat.import Mengimpor ruang, pesan, dan keanggotaan ke Chat. Sebagai informasi selengkapnya, lihat Mengizinkan aplikasi Chat untuk mengimpor data
https://www.googleapis.com/auth/chat.messages Melihat, menulis, mengirim, memperbarui, dan menghapus pesan, serta menambahkan, melihat, dan menghapus reaksi terhadap pesan.
https://www.googleapis.com/auth/chat.messages.readonly Melihat pesan dan reaksi di Chat.
https://www.googleapis.com/auth/chat.admin.delete Menghapus percakapan dan ruang yang dimiliki oleh domain administrator, serta menghapus akses ke file terkait di Chat.

Ruang lingkup dalam tabel sebelumnya menunjukkan sensitivitasnya, sesuai dengan definisi berikut:

Jika aplikasi Anda memerlukan akses ke Google API lainnya, Anda dapat menambahkan cakupan tersebut juga. Untuk informasi selengkapnya tentang cakupan Google API, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.

Untuk mempelajari lebih lanjut cakupan untuk Google Workspace API, lihat Konfigurasi layar izin OAuth dan pilih cakupan.

Jenis autentikasi yang diperlukan

Ada dua cara bagi aplikasi Chat untuk mengautentikasi dan memberi otorisasi dengan Chat API: kredensial pengguna atau akun layanan.

Dengan otorisasi kredensial pengguna, aplikasi Chat dapat mengakses data pengguna dan menyelesaikan tindakan atas nama pengguna. Cakupan OAuth menentukan data dan tindakan yang diizinkan.

Dengan otorisasi aplikasi, aplikasi Chat mengakses API sebagai aplikasi menggunakan kredensial akun layanan. Otorisasi aplikasi selalu menggunakan cakupan otorisasi chat.bot.

Saat memutuskan jenis kredensial yang akan digunakan untuk permintaan API tertentu, ingat bahwa beberapa metode API hanya mendukung jenis kredensial. Jika metode API mendukung kedua kredensial, jenis kredensial yang digunakan dalam panggilan memengaruhi hasil yang ditampilkan:

  • Dengan otorisasi aplikasi, metode hanya akan menampilkan resource yang dapat ditampilkan oleh aplikasi akses.
  • Dengan otorisasi pengguna, metode tersebut hanya menampilkan resource yang pengguna dapat diakses di UI Chat.

Misalnya, memanggil metode ListSpaces dengan otorisasi aplikasi akan menampilkan daftar ruang tempat aplikasi menjadi anggota. Memanggil ListSpaces dengan pengguna otorisasi akan menampilkan daftar ruang tempat pengguna menjadi anggota. Di beberapa aplikasi Anda mungkin menggunakan kedua jenis otorisasi saat memanggil Chat API, bergantung pada fungsi yang Anda inginkan.

Untuk panggilan Chat API asinkron

Tabel berikut berisi daftar metode Chat API dan metode yang didukung cakupan otorisasi:

Metode Autentikasi pengguna didukung Autentikasi aplikasi didukung Cakupan otorisasi yang didukung
Ruang  
Membuat ruang Dengan Autentikasi pengguna:
  • chat.spaces.create
  • chat.spaces
  • chat.import
Menyiapkan ruang Dengan Autentikasi pengguna:
  • chat.spaces.create
  • chat.spaces
Mendapatkan ruang Dengan Autentikasi pengguna:
  • chat.spaces.readonly
  • chat.spaces
Dengan Autentikasi aplikasi:
  • chat.bot
Dengan Autentikasi pengguna menggunakan hak istimewa administrator:
  • chat.admin.spaces.readonly
Menampilkan daftar ruang Dengan Autentikasi pengguna:
  • chat.spaces.readonly
  • chat.spaces
Dengan Autentikasi aplikasi:
  • chat.bot
Telusuri ruang Dengan Autentikasi pengguna menggunakan hak istimewa administrator:
  • chat.admin.spaces.readonly
Memperbarui ruang Dengan Autentikasi pengguna:
  • chat.spaces
  • chat.import
Dengan Autentikasi pengguna menggunakan hak istimewa administrator:
  • chat.admin.spaces
Menghapus ruang Dengan Autentikasi pengguna:
  • chat.delete
  • chat.import
Dengan Autentikasi pengguna menggunakan hak istimewa administrator:
  • chat.admin.delete
Menyelesaikan proses impor ruang Dengan Autentikasi pengguna:
  • chat.import
Menemukan pesan langsung Dengan Autentikasi pengguna:
  • chat.spaces.readonly
  • chat.spaces
Dengan Autentikasi aplikasi:
  • chat.bot
Anggota  
Membuat anggota Dengan Autentikasi pengguna:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Dengan Autentikasi pengguna menggunakan hak istimewa administrator:
  • chat.admin.memberships
Dapatkan pelanggan Dengan Autentikasi pengguna:
  • chat.memberships.readonly
  • chat.memberships
Dengan Autentikasi aplikasi:
  • chat.bot
Dengan Autentikasi pengguna menggunakan hak istimewa administrator:
  • chat.admin.memberships.readonly
Anggota daftar Dengan Autentikasi pengguna:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
Dengan Autentikasi aplikasi:
  • chat.bot
Dengan Autentikasi pengguna menggunakan hak istimewa administrator:
  • chat.admin.memberships.readonly
Menghapus anggota Dengan Autentikasi pengguna:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Dengan Autentikasi pengguna menggunakan hak istimewa administrator:
  • chat.admin.memberships
Memperbarui anggota Dengan Autentikasi pengguna:
  • chat.memberships
  • chat.import
Dengan Autentikasi pengguna menggunakan hak istimewa administrator:
  • chat.admin.memberships
Pesan  
Membuat pesan Dengan Autentikasi pengguna:
  • chat.messages.create
  • chat.messages
  • chat.import
Dengan Autentikasi aplikasi:
  • chat.bot
Mendapatkan pesan Dengan Autentikasi pengguna:
  • chat.messages.readonly
  • chat.messages
Dengan Autentikasi aplikasi:
  • chat.bot
Membuat daftar pesan Dengan Autentikasi pengguna:
  • chat.messages.readonly
  • chat.messages
  • chat.import
Memperbarui pesan Dengan Autentikasi pengguna:
  • chat.messages
  • chat.import
Dengan Autentikasi aplikasi:
  • chat.bot
Menghapus pesan Dengan Autentikasi pengguna:
  • chat.messages
  • chat.import
Dengan Autentikasi aplikasi:
  • chat.bot
Reaksi  
Membuat reaksi Dengan Autentikasi pengguna:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
Membuat daftar reaksi Dengan Autentikasi pengguna:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Menghapus reaksi Dengan Autentikasi pengguna:
  • chat.messages.reactions
  • chat.messages
  • chat.import
Media & lampiran  
Mengupload media sebagai lampiran file Dengan Autentikasi pengguna:
  • chat.messages.create
  • chat.messages
  • chat.import
Mendownload media Dengan Autentikasi pengguna:
  • chat.messages.readonly
  • chat.messages
Dengan Autentikasi aplikasi:
  • chat.bot
Mendapatkan lampiran pesan Dengan Autentikasi aplikasi:
  • chat.bot
Status pembacaan pengguna
Mendapatkan status pembacaan ruang pengguna Dengan Autentikasi pengguna:
  • chat.users.readstate
  • chat.users.readstate.readonly
Memperbarui status pembacaan ruang pengguna Dengan Autentikasi pengguna:
  • chat.users.readstate
Mendapatkan status pembacaan thread pengguna Dengan Autentikasi pengguna:
  • chat.users.readstate
  • chat.users.readstate.readonly
Acara ruang
Mendapatkan acara antariksa Dengan Autentikasi pengguna, Anda harus menggunakan ruang lingkup berdasarkan jenis peristiwa:
  • Untuk peristiwa terkait pesan:
    • chat.messages
    • chat.messages.readonly
  • Untuk peristiwa terkait reaksi:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • Untuk acara terkait keanggotaan:
    • chat.memberships
    • chat.memberships.readonly
  • Untuk acara tentang ruang:
    • chat.spaces
    • chat.spaces.readonly
Membuat daftar peristiwa ruang Dengan Autentikasi pengguna, Anda harus menggunakan cakupan untuk setiap jenis peristiwa yang disertakan dalam permintaan:
  • Untuk peristiwa terkait pesan:
    • chat.messages
    • chat.messages.readonly
  • Untuk peristiwa terkait reaksi:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • Untuk acara terkait keanggotaan:
    • chat.memberships
    • chat.memberships.readonly
  • Untuk acara tentang ruang:
    • chat.spaces
    • chat.spaces.readonly

Untuk peristiwa interaksi aplikasi Chat

Tabel berikut mencantumkan cara umum pengguna berinteraksi dengan aplikasi Chat dan apakah autentikasi diperlukan atau didukung:

Skenario Tidak perlu autentikasi Autentikasi pengguna didukung Autentikasi aplikasi didukung
Terima pesan dari:
Peristiwa interaksi aplikasi Chat
Callback Apps Script
Google Cloud Pub/Sub
Membalas pesan:
Secara sinkron, menggunakan peristiwa interaksi aplikasi Chat
Secara sinkron, menggunakan nilai hasil callback Apps Script
Mengirim pesan baru:
Dengan web webhook masuk