Sviluppare un'app di chat con Apps Script

Apps Script è uno dei modi più rapidi di creare un'app di chat per Google Chat.

• Puoi installare un'app in pochi minuti direttamente nel browser.
• Non devi preoccuparti di eseguire e gestire server, costi di manutenzione o operativi in corso, né di scaricare e configurare un ambiente di sviluppo.
• È facile chiamare le API di Google, in particolare leGoogle Workspace API, perché con Apps Script non è necessario scaricare o configurare i contenuti, l'autenticazione viene gestita automaticamente e le chiamate alle API di Google sono simili alle chiamate delle funzioni native.

Questa guida spiega come creare e registrare un'app con Apps Script.

Come iniziare

Questa sezione mostra come creare rapidamente un'app di chat utilizzando Apps Script.

Passaggio 1: copia il modello Apps Script

Il modo più semplice per iniziare a creare un'app Apps Script è utilizzare il modello di chat. Viene creato un progetto Apps Script con i metodi necessari. Dopodiché, completa i metodi necessari per implementare la logica dell'app o per integrarla con un'app che hai creato. Il codice seguente mostra un esempio del modello completato per una semplice app.

Se crei un progetto manualmente, senza utilizzare il modello di Chat per avviarlo, dovrai anche modificare il file manifest di Apps Script.

/**
 * 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"));
}

Passaggio 2: modifica la funzione onMessage

Per impostazione predefinita, la funzione onMessage nel modello restituisce un oggetto Message che contiene testo e una scheda semplice. Puoi modificare questa funzione in modo che restituisca testo o widget di schede specifici.

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

Passaggio 3: recupera l'ID deployment

Prima di poter registrare l'app, dovrai ottenere l'ID deployment per questa app specifica.

1. Fai clic su Esegui il deployment > Nuovo deployment.
2. In Seleziona il tipo, fai clic su Componente aggiuntivo.
3. Compila le opzioni e fai clic su Esegui il deployment.
4. In "ID deployment", fai clic su Copia.

Avviso: puoi utilizzare il deployment HEAD per semplici test durante lo sviluppo. Tuttavia, le app con deployment HEAD non possono essere condivise tra domini e non sono accessibili agli utenti a meno che non abbiano accesso in lettura allo script. Pertanto, per i test e le release generali, devi creare un deployment con versione.

Consulta la guida alla gestione delle release per conoscere le prassi consigliate per l'utilizzo degli ID deployment.

Passaggio 4: registra l'app

Puoi registrare l'app dalla console Google Cloud. Nella schermata di registrazione dell'app, inserisci il nome, l'URL dell'avatar e la descrizione. Per i test, puoi attivare "È possibile inviare messaggi direttamente all'app" e "L'app funziona in spazi con più utenti". Nelle impostazioni di connessione, scegli Apps Script e incolla l'ID deployment che hai copiato nel passaggio precedente.

Per registrare un'app di Apps Script, devi essere un proprietario o disporre delle autorizzazioni di modifica per il progetto di Apps Script sottostante.

Passaggio 5: testa l'app

Per testare la tua app, puoi avviare un messaggio diretto con l'app o @menzionarla in uno spazio. Quando ti parli, risponderà a qualsiasi risposta del messaggio nel passaggio 2. È tutto.

Concetti sulle app di Apps Script

Eventi

Apps Script supporta diverse funzioni del gestore di eventi che la tua app può implementare. Ogni funzione gestisce un tipo di evento diverso e ogni funzione riceve un singolo argomento e, che è un oggetto Evento.

onAddToSpace(e)

Questa funzione viene eseguita quando la tua app viene aggiunta a uno spazio. L'app può essere aggiunta direttamente allo spazio o tramite una @menzione. Nel secondo caso, anche l'evento e avrà una proprietà message. Questa funzione dovrebbe restituire un oggetto Message, che di solito è un messaggio di benvenuto per comunicare agli utenti finali la tua app o una risposta alla @menzione.

onMessage(e)

Questa funzione viene chiamata quando l'app è già presente nello spazio e l'utente @menziona l'app. Dovrebbe restituire un oggetto Message contenente la risposta dell'app.

onRemoveFromSpace(e)

Questa funzione viene chiamata quando l'utente rimuove la tua app dall'elenco dei messaggi diretti o da uno spazio. Il valore restituito da questa funzione viene ignorato poiché l'app è stata rimossa e non può pubblicare altri messaggi.

L'esempio seguente implementa onAddToSpace e 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) {}

Tieni presente che e.space.displayName potrebbe non essere presente nei messaggi diretti tra persone.

Schede interattive

Come altre app, le app di Apps Script possono mostrare schede interattive. Per scoprire come rendere le schede interattive, consulta la documentazione sulle schede interattive. La differenza principale nelle app Apps Script è che possono specificare un metodo specifico da chiamare quando viene attivato l'evento webhook utilizzando action.actionMethodName e action.parameters coppie chiave/valore come parametri metodo.

Autorizzazione

Le app di Apps Script che accedono alle risorse protette devono chiedere agli utenti di autorizzare questo accesso la prima volta che viene eseguito per ciascun utente. Non è necessario alcun intervento da parte tua, ma tieni presente che gli utenti potrebbero visualizzare una finestra di dialogo di autorizzazione la prima volta che utilizzano la tua app.

Apps Script gestisce l'autorizzazione a livello di script. Le app che richiedono autorizzazione non possono eseguire alcuna azione finché l'utente finale non autorizza l'app. Se vuoi che la tua app mostri un messaggio di benvenuto se non è stata autorizzata e viene aggiunta direttamente a uno spazio, puoi specificare un messaggio di riserva nel manifest. Se la tua applicazione richiede una logica di inizializzazione, potresti dover duplicare questa logica nell'azione onMessage. Ad esempio:

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.
  ...
}

Messaggi asincroni

Alcune app potrebbero dover inviare messaggi in Google Chat in base a un attivatore esterno, ad esempio un attivatore basato sul tempo in Apps Script.

Abbiamo intenzione di integrare in modo nativo l'API Google Chat in Apps Script per questo caso d'uso. Nel frattempo, l'unico modo per ottenere questo risultato attualmente è tramite l'API HTTP esterna (vedi la documentazione). Ciò richiede l'utilizzo di un account di servizio Cloud (consulta la documentazione) tramite la libreria OAuth2 for Apps Script.

La seguente app di esempio completa, che pubblica un messaggio ogni minuto in ogni spazio in cui si trova:

// 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 = '[e-mail]';

// 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 manifest

Di seguito è riportato un esempio del file manifest di Apps Script che deve essere accompagnato dallo script.

Se non hai avviato il progetto dal modello di chat, devi modificare il file manifest per aggiungere l'oggetto "chat": {}.

Nel file manifest, imposta il runtime su Rhino: "runtimeVersion": "DEPRECATED_ES5". Le app di chat non supportano completamente il runtime di Apps Script V8, quindi se specifichi "runtimeVersion": "V8", l'app di chat potrebbe presentare un errore irregolare. Ad esempio, la struttura delle risposte JSON può cambiare in modo imprevedibile, in modo imprevedibile, per le app di chat create con il runtime V8.

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

È possibile che un utente aggiunga la tua app a uno spazio prima di autorizzarla. In questo caso, l'app non può rispondere all'evento di aggiunta allo spazio. In questo caso, puoi fornire un messaggio di benvenuto da visualizzare utilizzando il campo addToSpaceFallbackMessage.

Il file manifest è denominato appsscript.json e fa parte del tuo progetto Apps Script. Per visualizzare il file manifest nell'editor di Apps Script, seleziona Visualizza > Mostra file manifest.