Convertire un'app di Google Chat interattiva in un componente aggiuntivo di Google Workspace

Se hai creato e pubblicato un'app Google Chat che utilizza eventi di interazione dell'API Google Chat, ad esempio una basata sulla guida rapida dell'app Google Chat, questa pagina mostra come convertirla in un componente aggiuntivo di Google Workspace che estende Google Chat.

Con la conversione, la tua app Google Chat può utilizzare il framework dei componenti aggiuntivi di Google Workspace, aprendo nuove possibilità di integrazione e funzionalità all'interno di Google Chat e in Google Workspace. Ad esempio, invece di due distribuzioni, una per l'app Google Chat e una per il componente aggiuntivo Google Workspace, puoi distribuire un unico componente aggiuntivo Google Workspace tramite Google Workspace Marketplace che estende le app di chat insieme ad altre applicazioni host di Google Workspace, come Gmail, Calendar e Documenti.

Limitazioni

Prima di iniziare la conversione, esamina le limitazioni dei componenti aggiuntivi di Google Workspace che estendono Google Chat per assicurarti che la tua app Google Chat possa essere convertita senza perdere funzionalità essenziali.

Passaggio 1: copia il codice dell'app Google Chat esistente

Il processo di conversione richiede modifiche al codice. Per evitare di influire sulla tua app Google Chat live, crea e lavora su una copia del codice.

Apps Script

  1. Apri il progetto Google Apps Script dell'app Google Chat esistente.
  2. A sinistra, fai clic su Panoramica .
  3. A destra, fai clic su Crea una copia .
  4. A sinistra, fai clic su Impostazioni progetto .
  5. Nella sezione Progetto Google Cloud, fai clic su Cambia progetto.
  6. Inserisci lo stesso numero di progetto associato al tuo progetto dell'app Google Chat esistente.
  7. Fai clic su Imposta progetto.

HTTP

Crea un fork o una copia del codebase esistente ed esegui il deployment come nuovo servizio, separato dall'app Google Chat live.

Se la tua app è implementata su Google Cloud e si basa su funzionalità legate al progetto Google Cloud (ad esempio, l'identità App Engine predefinita), il nuovo codice deve essere implementato su un servizio associato al progetto dell'app Google Chat esistente.

Passaggio 2: modifica il codice copiato

I componenti aggiuntivi di Google Workspace che estendono l'utilizzo di Google Chat utilizzano strutture di richiesta e risposta diverse rispetto alle app Google Chat create con eventi di interazione dell'API Chat. Devi aggiornare il codice per utilizzare il componente aggiuntivo Google Workspace EventObject anziché l'API Google Chat Event per richieste e risposte. Utilizza la guida alla conversione del codice per modificare il codice.

Passaggio 3: attiva la configurazione del componente aggiuntivo Google Workspace per gli utenti di test

Utilizza la console Google Cloud per configurare le impostazioni del componente aggiuntivo Google Workspace per la tua app Google Chat:

  1. Vai alla pagina di configurazione dell'API Google Chat nella console Google Cloud.

    Vai alla pagina di configurazione dell'API Google Chat

  2. In Funzionalità interattive, fai clic su Converti in componente aggiuntivo.

  3. Attiva Attiva le impostazioni di configurazione del componente aggiuntivo.

  4. Nella sezione Visibilità, aggiungi gli indirizzi email degli utenti di test.

  5. Se necessario, aggiorna le impostazioni di connessione con l'URL dell'endpoint di deployment o l'ID deployment di Apps Script del codice dell'app Google Chat copiato e modificato nel passaggio 2.

  6. Fai clic su Salva e testa.

Passaggio 4: testa l'app convertita

Testa a fondo la funzionalità del componente aggiuntivo Google Workspace utilizzando gli account utente di test configurati nel passaggio 3. Verifica tutte le funzionalità e le interazioni.

Passaggio 5: completa la conversione per tutti gli utenti

Dopo aver verificato che il componente aggiuntivo Google Workspace convertito funzioni correttamente, puoi renderlo disponibile a tutti gli utenti.

  1. Vai alla pagina di configurazione dell'API Google Chat nella console Google Cloud.

    Vai alla pagina di configurazione dell'API Google Chat

  2. In Funzionalità interattive, fai clic su Converti in componente aggiuntivo. Si apre un riquadro laterale.

  3. Nel riquadro laterale, fai clic su Converti in componente aggiuntivo.

  4. Digita l'ID progetto e fai clic su Converti.

La tua app di Google Chat ora è un componente aggiuntivo di Google Workspace che estende Google Chat.

(Facoltativo) Esegui la pulizia o libera le risorse Google Cloud inutilizzate

Se vuoi, dopo aver convertito la tua app Google Chat in un componente aggiuntivo di Google Workspace, per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate dall'app Google Chat che non sono più in uso, valuta la possibilità di disattivarle.

Guida alla conversione del codice

Questa sezione descrive in dettaglio il mapping tra il formato dell'interazione dell'API Google Chat Event e il formato del componente aggiuntivo di Google Workspace EventObject.

Mappatura delle richieste

La seguente tabella mostra come i campi dell'API Google Chat Event vengono mappati ai campi corrispondenti del componente aggiuntivo Google Workspace EventObject.

Campo Interazione API Google Chat Event Campo EventObject del componente aggiuntivo di Google Workspace Note
action.actionMethodName N/D Per le interazioni con la carta, il nome del metodo può essere passato come parametro in commonEventObject.parameters. Vedi Aprire una finestra di dialogo iniziale.
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 Disponibile in diversi payload a seconda del tipo di evento.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 Disponibile in diversi payload a seconda del tipo di evento.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 Disponibile in diversi payload a seconda del tipo di evento.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 Disponibile in diversi payload a seconda del tipo di evento.
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 Disponibile in diversi payload a seconda del tipo di evento.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 Disponibile in diversi payload a seconda del tipo di evento.
token N/D La verifica viene gestita in modo diverso. Consulta Richiedere la verifica per le app HTTP.
type N/D Il tipo di evento può essere dedotto dal trigger.
user chat.user

Mappatura delle richieste per caso d'uso

La tabella seguente mostra le differenze nei payload delle richieste per i casi d'uso comuni tra le app Google Chat create con eventi di interazione dell'API Chat e i componenti aggiuntivi di Google Workspace che estendono Google Chat.

Caso d'uso Payload di interazione dell'API Chat Event Payload del componente aggiuntivo di Google Workspace EventObject
App aggiunta allo spazio 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
Rimuovere un'app da uno spazio 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
L'utente @menziona un'app 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
L'utente @menziona un'app per aggiungerla allo spazio Devi gestire una richiesta da Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 Devi gestire due richieste da Google Chat.

Prima richiesta:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Seconda richiesta:
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
Comando slash 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Comando slash per aggiungere un'app allo spazio Devi gestire una richiesta da Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 Devi gestire due richieste da Google Chat.

Prima richiesta:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Seconda richiesta:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
L'utente fa clic su un pulsante di una scheda o di una finestra di dialogo 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

Per gli eventi di dialogo, common.formInputs contiene i valori dei widget. Esempio di Google Apps Script:

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

Per gli eventi di dialogo, commonEventObject.formInputs contiene i valori dei widget. Esempio di Google Apps Script:

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
L'utente invia informazioni in una scheda della home page dell'app 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
L'utente richiama un comando dell'app utilizzando un comando rapido 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Anteprima link 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
L'utente aggiorna un widget in un messaggio della scheda o in una finestra di dialogo 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

Mappatura delle risposte per caso d'uso

I componenti aggiuntivi di Google Workspace che estendono Google Chat restituiscono azioni anziché un oggetto Message. La tabella seguente mappa i tipi di risposta Message dell'API Google Chat alle azioni equivalenti dei componenti aggiuntivi di Google Workspace.

Caso d'uso Risposta dell'API Google Chat Message Risposta dell'azione di Chat del componente aggiuntivo di Google Workspace
Creare un messaggio nello spazio richiamato 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse è facoltativo. Per saperne di più, consulta Rispondere a un comando slash.

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Per saperne di più, consulta Inviare un messaggio.
Aggiornare un messaggio 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

Per saperne di più, vedi Aggiornare un messaggio (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Per saperne di più, consulta Aggiornare un messaggio (componenti aggiuntivi).
Anteprima link 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

Per saperne di più, vedi Visualizzare l'anteprima di un link (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

Per saperne di più, consulta Visualizzare l'anteprima di un link(componenti aggiuntivi).
Apri una finestra di dialogo iniziale 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

Per saperne di più, vedi Aprire una finestra di dialogo (Chat).

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
La scheda che invii può contenere widget con azioni onClick. Per i componenti aggiuntivi di Google Workspace HTTP, configura queste azioni per chiamare un endpoint di funzione: 
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

Per saperne di più, consulta Aprire una finestra di dialogo (componenti aggiuntivi).
Chiudere una finestra di dialogo 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

Per saperne di più, vedi Chiudere una finestra di dialogo (Chat).

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

Per saperne di più, vedi Chiudere una finestra di dialogo (componenti aggiuntivi).
Connettersi a un sistema esterno (richiedi configurazione) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

Per saperne di più, consulta Connettersi a un sistema esterno.

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

Per saperne di più, vedi Collegare il componente aggiuntivo di Google Workspace a un servizio di terze parti.
Elementi del completamento automatico sui widget interattivi 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

Per saperne di più, vedi Aggiungere un menu a selezione multipla.

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

Per saperne di più, vedi Raccogliere ed elaborare le informazioni degli utenti di Google Chat.

Gestire le interazioni con le schede nei messaggi creati prima della conversione

Quando converti un'app Google Chat HTTP in un componente aggiuntivo di Google Workspace, le interazioni con le schede sui messaggi creati prima della conversione richiedono una gestione speciale. I componenti aggiuntivi di Google Workspace utilizzano un URL HTTP completo per action.function di una scheda, mentre le app Google Chat create con gli eventi di interazione dell'API Google Chat utilizzano un nome di funzione. La seguente tabella riassume queste differenze.

App Google Chat creata con gli eventi di interazione dell'API Google Chat Componente aggiuntivo di Google Workspace che estende Google Chat
Configurazione Configura un singolo endpoint per tutti gli eventi nella console Google Cloud. Quando implementi le interazioni con le schede, action di una scheda contiene solo il nome della funzione da eseguire. L'endpoint HTTP comune viene richiamato per gli eventi di clic sulle schede.

Per saperne di più, vedi Aprire una finestra di dialogo (Chat).



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 Puoi configurare facoltativamente gli endpoint per evento nella console Google Cloud, ma non sono inclusi gli eventi di clic sulle schede. Quando implementi le interazioni con le schede, l'action di una scheda deve contenere l'URL completo dell'endpoint HTTP da richiamare. Puoi impostare un endpoint HTTP univoco per pulsante oppure utilizzare un endpoint comune e trasmettere l'azione come parametro in action.parameters.

Per saperne di più, consulta Aprire una finestra di dialogo (componenti aggiuntivi).



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

Per assicurarti che le interazioni con le schede funzionino per i messaggi creati prima della conversione, configura un URL di interazione con le schede nella pagina di configurazione dell'API Google Chat.

Questo URL viene utilizzato solo per le interazioni sui messaggi creati prima della conversione dell'app. Quando un utente interagisce con uno di questi messaggi, il valore action.function originale viene trasmesso come parametro denominato __action_method_name__.

Esempio: clic sulla scheda

Se hai configurato l'URL interazione scheda come https://.../card-interaction-handler e un utente fa clic su una scheda in un messaggio storico con la seguente azione:

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

Un evento viene inviato all'URL di interazione con la scheda configurato nel seguente formato:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

Esempio: menu multiselezione

Se un utente interagisce con un menu a selezione multipla con un'origine dati esterna:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

Un evento viene inviato all'URL di interazione con la scheda configurato nel seguente formato:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

Se attivi l'opzione Utilizza un URL dell'endpoint HTTP comune per tutti i trigger per i trigger HTTP, l'URL comune viene utilizzato anche per gli eventi Pulsante cliccato.

Verificare le richieste per i componenti aggiuntivi HTTP di Google Workspace che estendono Chat

Per le app Google Chat basate su HTTP, la logica per verificare che le richieste provengano da Google deve essere aggiornata durante la conversione in un componente aggiuntivo di Google Workspace.

Le principali differenze nella verifica delle richieste sono:

Tipo di app Pubblico supportato Email del service account
App Google Chat creata con gli eventi di interazione dell'API Google Chat Numero progetto chat@system.gserviceaccount.com
Componente aggiuntivo di Google Workspace che estende Google Chat Solo endpoint HTTP Email del service account per progetto

L'indirizzo email univoco dell'account di servizio per il tuo componente aggiuntivo Google Workspace si trova nella sezione Converti in componenti aggiuntivi Google Workspace della pagina di configurazione dell'API Google Chat nella console Google Cloud.

Per verificare le richieste nel componente aggiuntivo di Google Workspace di cui hai eseguito l'upgrade:

  1. Se utilizzi Cloud Run Functions, concedi il ruolo roles/cloudfunctions.invoker al service account per componente aggiuntivo. Consulta Autorizzare l'accesso con IAM.
  2. Aggiorna il codice di verifica del token per utilizzare l'email dell'account del servizio di componenti aggiuntivi Google Workspace per verificare la firma del token Bearer. Vedi Convalida le richieste di Google.