Questa pagina è stata tradotta dall'API Cloud Translation.

Andare in vacanza con un'app Google Chat

1. Introduzione

Le app di Google Chat portano servizi e risorse direttamente in Chat, dove gli utenti possono ottenere informazioni e intraprendere azioni senza abbandonare la conversazione.

In questo codelab, imparerai a creare un'app Chat, "Attendance Chat app", che imposta le risposte automatiche per le ferie in Gmail e pianifica le riunioni in Google Calendar. Creando l'app Chat per il monitoraggio delle presenze in Google Apps Script, puoi accedere facilmente ad altri servizi Google come Drive, Gmail, Calendar, Documenti, Fogli e molti altri.

Obiettivi didattici

Come aggiungere gestori negli eventi generati in Chat
Come analizzare gli oggetti evento inviati da Chat
Come rispondere a Chat con risposte formattate a schede
Come definire e reagire alle azioni personalizzate per i clic sui pulsanti nelle schede

Che cosa ti serve

Accesso a internet e a un browser web.
Un account Google Workspace con accesso a Google Chat.
Competenze di base in JavaScript: Google Apps Script supporta solo JavaScript.

2. recupera il codice campione

Puoi scaricare un file ZIP o clonare il repository GitHub per visualizzare il codice di ogni passaggio di questo esempio.

Le cartelle step-NN in solutions/attendance-chat-app contengono lo stato finale desiderato di ogni passaggio di questo codelab. Sono presenti a scopo di riferimento.

Scarica il codice

Per scaricare il codice per questo codelab, fai clic sul pulsante seguente:

Decomprimi il file ZIP scaricato. Viene estratta una cartella principale (apps-script-samples), che contiene una cartella per ogni passaggio di questo codelab in solutions/attendance-chat-app.

Clona il repository GitHub

Per clonare il repository GitHub per questo codelab, esegui il comando seguente:

git clone https://github.com/googleworkspace/apps-script-samples

3. Crea i gestori per gli eventi di Google Chat

Crea un progetto Apps Script

Per creare un progetto Apps Script:

Vai a script.new.
Fai clic su Progetto senza titolo.
Rinomina lo script App Chat Presenze e fai clic su Rinomina.

Eventi in Google Chat

La maggior parte delle interazioni di Apps Script con Chat è basata su eventi. L'interazione tra l'utente, l'app Chat e Chat in genere segue questa sequenza:

Un utente avvia un'azione, ad esempio l'aggiunta di un'app di Chat a uno spazio, l'invio di un messaggio diretto a un'app di Chat o la rimozione di un'app di Chat da uno spazio.
L'azione genera un evento destinato all'app Chat in Chat.
Chat chiama il gestore di eventi corrispondente definito nello script dell'app di Chat.

La chat genera quattro eventi che la tua app può ascoltare:

ADDED_TO_SPACE: questo evento si verifica quando un utente umano aggiunge un'app Chat a uno spazio o a un messaggio diretto. In Apps Script, definisci una funzione onAddToSpace() per gestire questo evento.
REMOVED_FROM_SPACE: questo evento si verifica quando un utente rimuove l'app Chat da uno spazio o da un messaggio diretto. Questo evento non pubblica una risposta in Chat. In Apps Script, definisci una funzione onRemoveFromSpace() per gestire questo evento.
MESSAGE: questo evento si verifica quando un utente invia un messaggio all'app Chat, direttamente in un messaggio diretto o come @menzione in uno spazio. In Apps Script, definisci una funzione onMessage() per rispondere a questo evento.
CARD_CLICKED: questo evento si verifica quando l'utente fa clic su un pulsante a cui è assegnata un'azione personalizzata. In Apps Script, definisci una funzione onCardClick() per rispondere a questo evento.

Sostituisci i contenuti del file Code.gs con il seguente codice che definisce i gestori per gli eventi ADDED_TO_SPACE e REMOVE_FROM_SPACE. Aggiungerai i gestori per gli eventi MESSAGE e CARD_CLICKED più avanti in questo codelab.

Code.gs

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onAddToSpace(event) {
  console.info(event);
  var message = 'Thank you for adding me to ';
  if (event.space.type === 'DM') {
    message += 'a DM, ' + event.user.displayName + '!';
  } else {
    message += event.space.displayName;
  }
  return { text: message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onRemoveFromSpace(event) {
  console.info(event);
  console.log('Chat app removed from ', event.space.name);
}

4. Pubblicare e testare l'app Chat

Aggiornare il file manifest dello script

Prima di poter pubblicare l'app su Chat, devi aggiornare il manifest del progetto di script.

Fai clic su Impostazioni progetto .
Seleziona la casella di controllo Mostra il file manifest "appsscript.json" nell'editor.
Fai clic su Editor .
Fai clic sul file appsscript.json.
Aggiungi la riga "chat": {} al file manifest.

Il file manifest dovrebbe essere simile all'esempio seguente.

appsscript.json

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "chat": {}
}

Crea un progetto Google Cloud

Prima di poter eseguire e testare l'app di chat, devi creare un progetto Google Cloud, attivare e configurare l'API Chat e pubblicare l'app di chat nella tua organizzazione Google Workspace.

In Google Cloud Console, vai a Menu > IAM e amministrazione > Crea un progetto.
In Nome progetto, inserisci un nome descrittivo.
Se richiesto, seleziona l'organizzazione e l'account di fatturazione.
Fai clic su Crea.
Al termine della creazione del progetto, viene visualizzata una notifica in alto a destra della pagina. Fai clic sulla voce Crea progetto: <nome progetto> per aprire il progetto.
Fai clic su Menu > API e servizi > Credenziali.
Fai clic su Schermata consenso OAuth.
In Nome dell'app, digita App di chat per il rilevamento delle presenze.
Se richiesto, inserisci l'email per l'assistenza utente e i dati di contatto dello sviluppatore.
Fai clic su Salva e continua.
Fai clic su Impostazioni e utilità > Impostazioni progetto.
Copia il Numero progetto.
Nell'editor di Apps Script, fai clic su Impostazioni progetto .
In Progetto Google Cloud (GCP), fai clic su Cambia progetto.
Fai clic su Numero progetto Google Cloud e inserisci il numero del progetto.
Fai clic su Imposta progetto.

Pubblicare l'app su Chat

Per pubblicare la tua app di chat su Google Chat:

Nell'editor di Apps Script, fai clic su Pubblica > Nuovo deployment.
Accanto a Seleziona tipo, fai clic su Attiva tipi di deployment .
Seleziona Componente aggiuntivo e fai clic su Esegui il deployment.
Copia l'ID deployment e fai clic su Fine.
Nella console Google Cloud, vai a Menu > API e servizi > Libreria.
Cerca API Google Chat. Seleziona l'API dall'elenco dei risultati.
Nella pagina dell'API Google Chat, fai clic su Abilita.
Dopo aver abilitato l'API, fai clic su Configurazione. Ignora i messaggi che ti chiedono di creare credenziali.
Nella pagina Configurazione, segui questi passaggi:

Deseleziona Crea questa app di Chat come componente aggiuntivo di Workspace e fai clic su DISATTIVA per confermare.
In Nome dell'app, digita App di chat per il rilevamento delle presenze.
Per URL avatar, inserisci https://goo.gl/kv2ENA.
In Descrizione, inserisci Codelab di Apps Script: app di chat.
Nella sezione Funzionalità, seleziona Ricevi messaggi personali.
Nella sezione Impostazioni di connessione, seleziona Progetto Apps Script e incolla l'ID deployment dello script nella casella di testo.
Nella sezione Autorizzazioni, seleziona Persone e gruppi specifici nel tuo dominio. Nella casella di testo sotto il menu a discesa, inserisci il tuo indirizzo email associato alla tua organizzazione Google Workspace.
Fai clic su Salva.

Dopo aver salvato le modifiche, verifica che lo stato nella pagina dell'API Google Chat mostri Stato app come LIVE - disponibile per gli utenti.

Testare l'app Chat

Per testare la tua app in Google Chat:

Apri Google Chat.
Invia un nuovo messaggio diretto all'app Chat facendo clic su Avvia una chat > Trova app.
Nella pagina Trova app, cerca l'app Chat per il monitoraggio delle presenze.
Accanto ad App Chat per il rilevamento delle presenze, fai clic su Aggiungi > Chat.

Quando si apre il thread di messaggi diretti, dovresti visualizzare un messaggio dell'app Chat che ti ringrazia per averla aggiunta a un messaggio diretto, come mostrato nell'immagine seguente.

5. Definisci una risposta formattata a schede

Nel passaggio precedente, la tua app ha risposto agli eventi di Google Chat con una semplice risposta di testo. In questo passaggio, aggiorna l'app per rispondere con schede.

Risposte delle schede

Google Chat supporta l'utilizzo di schede per le risposte. Le schede sono contenitori visivi che ti consentono di raggruppare insieme set di widget dell'interfaccia utente. Le schede possono mostrare intestazioni, paragrafi di testo, set di pulsanti, immagini e testo chiave/valore. La tua app può definire una o più schede nella risposta JSON a Google Chat, che poi traduce la risposta negli elementi dell'interfaccia utente corrispondenti.

L'immagine seguente mostra una risposta a scheda con tre sezioni, che include un'intestazione, un widget chiave/valore, un widget immagine e un pulsante di testo.

Per rispondere ai messaggi degli utenti con una risposta a scheda, aggiungi il seguente codice al file Code.gs dell'app Chat.

Code.gs

const DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
const HEADER = {
  header: {
    title : 'Attendance Chat app',
    subtitle : 'Log your vacation time',
    imageUrl : DEFAULT_IMAGE_URL
  }
};

/**
 * Creates a card-formatted response.
 * @param {object} widgets the UI components to send
 * @return {object} JSON-formatted response
 */
function createCardResponse(widgets) {
  return {
    cards: [HEADER, {
      sections: [{
        widgets: widgets
      }]
    }]
  };
}

/**
 * Responds to a MESSAGE event triggered
 * in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return JSON-formatted response
 */
function onMessage(event) {
  const userMessage = event.message.text;

  const widgets = [{
    "textParagraph": {
      "text": "You said: " + userMessage
    }
  }];

  return createCardResponse(widgets);
}

La funzione onMessage(), aggiunta in questo passaggio, legge il messaggio originale dell'utente e crea una risposta come semplice widget TextParagragh. La funzione onMessage() chiama quindi createCardResponse(), che inserisce il widget TextParagraph in una sezione di una singola scheda. L'app Chat restituisce l'oggetto JavaScript creato con la risposta della scheda a Google Chat.

Testare l'app Chat

Per testare questa app, torna al messaggio diretto con l'app in Google Chat e digita un messaggio (qualsiasi messaggio va bene).

Tieni presente che il gestore di eventi onMessage() analizza l'oggetto evento che gli viene passato da Google Chat per estrarre il messaggio originale dell'utente. Puoi anche ottenere altri tipi di informazioni sull'evento, tra cui il nome dell'utente che lo ha avviato, il suo indirizzo email, il nome dello spazio in cui si è verificato l'evento e molto altro ancora.

Per saperne di più sulla struttura degli oggetti evento inviati da Google Chat, consulta la documentazione di riferimento sui formati degli eventi.

6. Reagire ai clic sui pulsanti nelle schede

Nel passaggio precedente, la tua app Chat ha risposto a un messaggio di un utente, un evento MESSAGE, con una semplice scheda contenente un widget TextParagragh. In questo passaggio, crei una risposta che include pulsanti, in cui ogni pulsante ha un'azione personalizzata definita.

Schede interattive

Le risposte delle schede possono contenere uno dei due tipi di pulsanti: widget pulsante di testo, che mostrano pulsanti solo di testo, e widget ImageButton, che mostrano un pulsante con un'icona o un'immagine semplice senza testo. I widget TextButton e ImageButton supportano uno dei due comportamenti onClick (come definito nella risposta JSON inviata a Google Chat): openLink o action. Come suggerisce il nome, openLink apre un link specificato in una nuova scheda del browser.

L'oggetto action specifica un'azione personalizzata da eseguire per il pulsante. Puoi specificare diversi valori arbitrari nell'oggetto azione, tra cui un actionMethodName univoco e un insieme di coppie di parametri chiave / valore.

Se specifichi un oggetto action per il pulsante, viene creata una scheda interattiva. Quando l'utente fa clic sul pulsante nel messaggio, Google Chat genera un evento CARD_CLICKED e invia una richiesta all'app che ha inviato il messaggio originale. L'app deve quindi gestire l'evento generato da Google Chat e restituire una risposta allo spazio.

Sostituisci la funzione onMessage() in Code.gs con il seguente codice. Questo codice crea due pulsanti, uno per Imposta ferie in Gmail e uno per Blocca giorno in Calendar, nella scheda inviata a Google Chat.

Code.gs

const REASON = {
  SICK: 'Out sick',
  OTHER: 'Out of office'
};
/**
 * Responds to a MESSAGE event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 */
function onMessage(event) {
  console.info(event);
  const reason = REASON.OTHER;
  const name = event.user.displayName;
  const userMessage = event.message.text;

  // If the user said that they were 'sick', adjust the image in the
  // header sent in response.
  if (userMessage.indexOf('sick') > -1) {
    // Hospital material icon
    HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
    reason = REASON.SICK;
  } else if (userMessage.indexOf('vacation') > -1) {
    // Spa material icon
    HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
  }

  const widgets = [{
    textParagraph: {
      text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
    }
  }, {
    buttons: [{
      textButton: {
        text: 'Set vacation in Gmail',
        onClick: {
          action: {
            actionMethodName: 'turnOnAutoResponder',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }, {
      textButton: {
        text: 'Block out day in Calendar',
        onClick: {
          action: {
            actionMethodName: 'blockOutCalendar',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }]
  }];
  return createCardResponse(widgets);
}

Per gestire l'evento CARD_CLICKED, devi aggiungere la funzione onCardClick() allo script dell'app Chat. Aggiungi il seguente codice che definisce la funzione onCardClick() Code.gs.

Code.gs

/**
 * Responds to a CARD_CLICKED event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onCardClick(event) {
  console.info(event);
  let message = '';
  const reason = event.action.parameters[0].value;
  if (event.action.actionMethodName == 'turnOnAutoResponder') {
    turnOnAutoResponder(reason);
    message = 'Turned on vacation settings.';
  } else if (event.action.actionMethodName == 'blockOutCalendar') {
    blockOutCalendar(reason);
    message = 'Blocked out your calendar for the day.';
  } else {
    message = "I'm sorry; I'm not sure which button you clicked.";
  }
  return { text: message };
}

In risposta ai clic degli utenti, ora l'app Chat esegue una delle due operazioni seguenti: imposta la risposta automatica per ferie dell'utente in Gmail su un messaggio "Fuori sede" oppure pianifica una riunione di un giorno intero nel calendario dell'utente. Per svolgere queste attività, l'app chiama il servizio avanzato Gmail e il servizio Calendar.

Aggiungi il seguente codice allo script per integrare l'app Chat con Gmail e Calendar.

Code.gs

const ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
 * Turns on the user's vacation response for today in Gmail.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function turnOnAutoResponder(reason) {
  let currentTime = (new Date()).getTime();
  Gmail.Users.Settings.updateVacation({
    enableAutoReply: true,
    responseSubject: reason,
    responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Chat app!</i>",
    restrictToContacts: true,
    restrictToDomain: true,
    startTime: currentTime,
    endTime: currentTime + ONE_DAY_MILLIS
  }, 'me');
}

/**
 * Places an all-day meeting on the user's Calendar.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function blockOutCalendar(reason) {
  CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}

Infine, devi attivare il servizio avanzato Gmail nel progetto. Per abilitare l'API Gmail:

Nell'editor Apps Script, accanto a Servizi, fai clic su Aggiungi un servizio .
Seleziona API Gmail.
Fai clic su Dashboard API di Google Cloud Platform di seguito per aprire la console Google Cloud.
Fai clic su Abilita API e servizi.
Cerca API Gmail e fai clic sull'API Gmail.
Nella pagina dell'API Gmail, fai clic su Abilita.

Testare l'app Chat

Per testare questa versione dell'app Chat, apri il messaggio diretto che hai iniziato nei passaggi precedenti in Google Chat e digita Vado in vacanza. L'app dovrebbe rispondere con una scheda simile all'immagine qui sotto.

Nota:se ti viene chiesto di fornire l'accesso all'app, potresti dover digitare il messaggio una seconda volta.

7. Complimenti!

La tua app Chat ora può rispondere ai messaggi degli utenti, impostare la risposta automatica per le vacanze in Gmail e inserire un evento che dura tutto il giorno nel calendario.

Argomenti trattati

Creare e pubblicare un'app Google Chat con Apps Script
Rispondere ai messaggi degli utenti con una risposta semplice
Ha interagito con altri servizi Google Workspace per conto dell'utente tramite l'app Chat

Andare in vacanza con un'app Google Chat Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

1. Introduzione

Obiettivi didattici

Che cosa ti serve

2. recupera il codice campione

Scarica il codice

Clona il repository GitHub

3. Crea i gestori per gli eventi di Google Chat

Crea un progetto Apps Script

Eventi in Google Chat

Code.gs

4. Pubblicare e testare l'app Chat

Aggiornare il file manifest dello script

appsscript.json

Crea un progetto Google Cloud

Pubblicare l'app su Chat

Testare l'app Chat

5. Definisci una risposta formattata a schede

Risposte delle schede

Code.gs

Testare l'app Chat

6. Reagire ai clic sui pulsanti nelle schede

Schede interattive

Code.gs

Code.gs

Code.gs

Testare l'app Chat

7. Complimenti!

Argomenti trattati

Scopri di più

Andare in vacanza con un'app Google Chat