Halaman ini diterjemahkan oleh Cloud Translation API.

Mengembangkan aplikasi Chat dengan Apps Script

Apps Script adalah salah satu cara tercepat untuk membuat aplikasi Chat untuk Google Chat.

Anda dapat menyiapkan dan menjalankan aplikasi hanya dalam beberapa menit langsung di browser.
Anda tidak perlu khawatir tentang menjalankan dan mengelola server, biaya pemeliharaan atau operasional yang berkelanjutan, atau bahkan mendownload dan menyiapkan lingkungan pengembangan.
Sangat mudah untuk memanggil Google API—terutama Google Workspace API—karena dengan Apps Script tidak ada download atau penyiapan, autentikasi ditangani secara otomatis, dan panggilan Google API seperti panggilan fungsi native.

Panduan ini menjelaskan cara membuat dan mendaftarkan aplikasi menggunakan Apps Script.

Memulai

Bagian ini menunjukkan cara membuat aplikasi Chat dengan cepat menggunakan Apps Script.

Langkah 1: Salin template Apps Script

Cara termudah untuk mulai membuat aplikasi Apps Script adalah menggunakan template Chat. Tindakan ini akan membuat project Apps Script dengan metode yang Anda perlukan. Setelah itu, isi metode yang diperlukan untuk menerapkan logika aplikasi Anda, atau untuk berintegrasi dengan aplikasi yang telah Anda build. Kode berikut menunjukkan contoh template yang diisi untuk aplikasi sederhana.

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  var name = "";

  if (event.space.type == "DM") {
    name = "You";
  } else {
    name = event.user.displayName;
  }
  var message = name + " said \"" + event.message.text + "\"";

  return { "text": message };
}

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAddToSpace(event) {
  var message = "";

  if (event.space.singleUserBotDm) {
    message = "Thank you for adding me to a DM, " + event.user.displayName + "!";
  } else {
    message = "Thank you for adding me to " +
        (event.space.displayName ? event.space.displayName : "this chat");
  }

  if (event.message) {
    // Bot added through @mention.
    message = message + " and you said: \"" + event.message.text + "\"";
  }

  return { "text": message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onRemoveFromSpace(event) {
  console.info("Bot removed from ",
      (event.space.name ? event.space.name : "this chat"));
}

Langkah 2: Edit fungsi onMessage

Secara default, fungsi onMessage di template menampilkan objek Message yang berisi teks dan kartu sederhana. Anda dapat mengedit fungsi ini untuk menampilkan teks atau widget kartu tertentu.

function onMessage(e) {
  return { 'text': 'You said: \`' + e.message.text + '\`' };
}

Langkah 3: Dapatkan ID deployment

Agar dapat mendaftarkan aplikasi, Anda harus mendapatkan deploymentID untuk aplikasi tertentu ini.

Klik Deploy > New deployment.
Di bagian Select type, klik Add-on.
Isi opsi, lalu klik Deploy.
Di bagian "ID Deployment", klik Salin.

Lihat panduan Pengelolaan Rilis untuk mempelajari praktik yang direkomendasikan dalam menggunakan ID deployment.

Langkah 4: Daftarkan aplikasi

Anda dapat mendaftarkan aplikasi dari Google Cloud Console. Di layar pendaftaran aplikasi, masukkan nama aplikasi, URL avatar, dan deskripsi. Untuk pengujian, Anda dapat mengaktifkan 'Aplikasi dapat dikirimi pesan secara langsung' dan 'Aplikasi berfungsi di ruang dengan beberapa pengguna'. Di bagian setelan koneksi, pilih Apps Script dan tempel ID deployment yang disalin pada langkah sebelumnya.

Setelan koneksi untuk mendaftarkan aplikasi Anda.

Langkah 5: Uji aplikasi Anda

Untuk menguji aplikasi, Anda dapat memulai DM dengannya atau @menyebutnya dalam Ruang. Saat Anda berbicara ke fitur tersebut, pesan akan merespons apa pun dari respons Pesan pada Langkah 2. Selesai.

Konsep aplikasi Apps Script

Acara

Apps Script mendukung beberapa fungsi pengendali peristiwa yang dapat diterapkan oleh aplikasi Anda. Setiap fungsi menangani jenis peristiwa yang berbeda dan setiap fungsi menerima satu argumen e, yang merupakan objek Peristiwa.

onAddToSpace(e): Fungsi ini dijalankan saat aplikasi ditambahkan ke ruang. Aplikasi Anda dapat ditambahkan langsung ke ruang atau ditambahkan melalui @sebutan. Dalam kasus kedua, peristiwa e juga akan memiliki properti message. Fungsi ini akan menampilkan objek Message, yang biasanya merupakan pesan selamat datang untuk memberi tahu pengguna akhir tentang aplikasi Anda atau respons terhadap @sebutan.
onMessage(e): Fungsi ini dipanggil saat aplikasi sudah ada dalam ruang dan pengguna @sebutan aplikasi. Fungsi ini akan menampilkan objek Message yang berisi respons aplikasi Anda.
onRemoveFromSpace(e): Fungsi ini dipanggil saat pengguna menghapus aplikasi dari daftar DM atau dari ruang. Nilai yang ditampilkan dari fungsi ini diabaikan karena aplikasi Anda telah dihapus dan tidak dapat memposting pesan lagi.

Contoh berikut mengimplementasikan onAddToSpace dan onRemoveFromSpace:

// onAddToSpace() is invoked when the app is added to a space or when
// a user initiates / re-initiates a direct message with the app.
function onAddToSpace(e) {
  if (!e.space.singleUserBotDm) {
    return { 'text': 'Thanks for adding me to "' +
        (e.space.displayName ? e.space.displayName : "this chat") + '"!' };
  } else {
    return { 'text': 'Thanks for adding me to a DM!' };
  }
}
// onRemoveFromSpace() is invoked when app is removed from a space
// or when a user removes a direct message with the app.
function onRemoveFromSpace(e) {}

Perhatikan bahwa e.space.displayName mungkin tidak ada dalam pesan langsung antar-manusia.

Kartu interaktif

Seperti aplikasi lainnya, aplikasi Apps Script dapat menampilkan kartu yang interaktif. Untuk mempelajari cara membuat kartu menjadi interaktif, baca dokumentasi tentang kartu interaktif. Perbedaan utama untuk aplikasi Apps Script adalah aplikasi ini dapat menentukan metode tertentu untuk dipanggil saat peristiwa onClick dipicu dengan menggunakan key-value pair action.actionMethodName dan action.parameters sebagai parameter metode.

Otorisasi

Aplikasi Apps Script yang mengakses resource yang dilindungi harus meminta pengguna untuk memberi otorisasi akses ini saat pertama kali dijalankan untuk setiap pengguna. Anda tidak perlu melakukan tindakan apa pun, tetapi perlu diketahui bahwa pengguna mungkin melihat dialog otorisasi saat pertama kali mereka menggunakan aplikasi Anda.

Apps Script menangani otorisasi di level skrip. Aplikasi yang memerlukan otorisasi tidak dapat melakukan tindakan apa pun hingga pengguna akhir mengizinkan aplikasi tersebut. Jika ingin aplikasi Anda menampilkan pesan selamat datang saat aplikasi belum diotorisasi dan langsung ditambahkan ke ruang, Anda dapat menentukan pesan penggantian di manifes. Jika aplikasi Anda memerlukan logika inisialisasi, Anda mungkin perlu menduplikasi logika ini dalam tindakan onMessage. Contoh:

function onMessage(event) {
  var userProperties = PropertiesService.getUserProperties();
  if (!userProperties.getProperty('initialized')) {
    // handle the onAddToSpace initialization logic here.
    ...
    userProperties.setProperties({initialized: 'true'});
  }
  // Handle normal onMessage logic.
  ...
}

Pesan asinkron

Beberapa aplikasi mungkin perlu mengirim pesan ke Google Chat berdasarkan pemicu eksternal, seperti Pemicu berbasis waktu di Apps Script.

Kami berencana untuk mengintegrasikan Google Chat API secara native ke dalam Apps Script untuk kasus penggunaan ini. Sementara itu, satu-satunya cara untuk mencapainya saat ini adalah melalui HTTP API eksternal (lihat dokumentasi). Untuk menggunakan akun layanan Cloud, Anda harus menggunakan dokumentasi) melalui library OAuth2 untuk Apps Script.

Contoh aplikasi lengkap berikut yang memposting pesan setiap menit ke setiap ruang tempatnya berada:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute via the
// "Edit > Current Project's Triggers" menu. When it runs, it will
// post in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

File manifes

Berikut adalah contoh file manifes Apps Script yang harus disertakan dengan skrip.

Jika tidak memulai project dari template Chat, Anda harus mengedit file manifes untuk menambahkan objek "chat": {} ke dalamnya.

Dalam file manifes, setel runtime ke Rhino: "runtimeVersion": "DEPRECATED_ES5". Aplikasi Chat tidak sepenuhnya mendukung runtime Apps Script V8, sehingga jika Anda menentukan "runtimeVersion": "V8", aplikasi Chat mungkin akan mengalami error secara tidak menentu. Misalnya, struktur respons JSON dapat berubah secara situasional dengan cara yang tidak dapat diprediksi untuk aplikasi Chat yang di-build dengan runtime V8.

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "chat": {
    "addToSpaceFallbackMessage": "Thank you for adding me!"
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "DEPRECATED_ES5"
}

Pengguna dapat menambahkan aplikasi Anda ke ruang sebelum memberi otorisasi aplikasi. Dalam hal ini, aplikasi tidak dapat merespons peristiwa tambahkan ke ruang. Anda dapat memberikan pesan selamat datang untuk ditampilkan jika hal ini terjadi, menggunakan kolom addToSpaceFallbackMessage.

File manifes akan diberi nama appsscript.json dan merupakan bagian dari project Apps Script Anda. Untuk melihat file manifes di editor Apps Script, pilih Lihat > Tampilkan file manifes.