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

Se hai creato e pubblicato un'app di Chat che non è un componente aggiuntivo di Google Workspace, 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, puoi distribuire un singolo componente aggiuntivo di 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 i limiti e le considerazioni per i componenti aggiuntivi di Google Workspace per assicurarti che la tua app di chat che non è un componente aggiuntivo possa essere convertita senza perdere funzionalità essenziali.

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

La procedura 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 di app Google Chat esistente.
  7. Fai clic su Imposta progetto.

HTTP

Crea un fork o una copia del codebase esistente e implementalo 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 Google Chat utilizzano strutture di richiesta e risposta diverse rispetto alle app di chat che non sono componenti aggiuntivi. Devi aggiornare il codice per utilizzare gli oggetti evento dei componenti aggiuntivi di Google Workspace (EventObject) anziché gli eventi di interazione dell'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 di 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. Nella sezione Funzionalità interattive, attiva l'opzione Abilita funzionalità interattive.

  3. Nella sezione Converti in componente aggiuntivo di Google Workspace, fai clic su Converti in componente aggiuntivo.

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

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

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

  7. 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. Nella sezione 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 Google Chat ora è un componente aggiuntivo di Google Workspace che estende Google Chat.

(Facoltativo) Libera spazio 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 nel dettaglio il mapping tra l'interazione dell'API Google Chat Event e il formato del componente aggiuntivo di Google Workspace EventObject.

Mappatura delle richieste

La seguente tabella mostra la mappatura dei campi nell'API Google Chat Event per un'app di chat che non è un componente aggiuntivo con i campi corrispondenti nel componente aggiuntivo di Google Workspace EventObject.

App di chat che non è un componente aggiuntivo (campo Event) Campo EventObject del componente aggiuntivo di Google Workspace Note
action.actionMethodName N/D Per le interazioni con le schede, il nome del metodo può essere passato come parametro in commonEventObject.parameters. Consulta 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 la sezione 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 seguente tabella mostra le differenze nei payload delle richieste per i casi d'uso comuni tra le app di chat che non sono componenti aggiuntivi e i componenti aggiuntivi di Google Workspace che estendono Google Chat.

Caso d'uso App di chat che non è un componente aggiuntivo (payload 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 di 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 per un'app di Chat che non è un componente aggiuntivo alle azioni equivalenti del componente aggiuntivo di Google Workspace.

Caso d'uso App di chat che non è un componente aggiuntivo (risposta 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 Rispondere con un messaggio.
Aggiornare un messaggio 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

Per saperne di più, consulta Aggiornare un messaggio.

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

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

Per saperne di più, consulta Link di anteprima.

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

Per saperne di più, consulta Link di anteprima.
Aprire una finestra di dialogo iniziale 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

Per scoprire di più, consulta Aprire finestre di dialogo interattive.

 
{
  "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 scoprire di più, consulta Aprire finestre di dialogo interattive.
Chiudere una finestra di dialogo 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

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

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

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

Per saperne di più, vedi Connettersi a un sistema esterno (app di chat che non sono componenti aggiuntivi).

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

Per saperne di più, consulta Collegare un'app di chat ad altri servizi e strumenti.
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 Leggere i dati inseriti dagli utenti nei moduli delle schede.

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

Quando converti un'app di chat HTTP che non è un componente aggiuntivo in un componente aggiuntivo di Google Workspace, le interazioni con le schede nei messaggi creati prima della conversione richiedono una gestione speciale. I componenti aggiuntivi utilizzano un URL HTTP completo per action.function di una scheda, mentre le app di chat che non sono componenti aggiuntivi utilizzano un nome di funzione. La seguente tabella riassume queste differenze.

App di chat che non è un componente aggiuntivo 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 scoprire di più, consulta Aprire finestre di dialogo interattive.



{
  "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 o utilizzare un endpoint comune e passare l'azione come parametro in action.parameters.

Per scoprire di più, consulta Aprire finestre di dialogo interattive.



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

Per assicurarti che le interazioni con le schede siano funzionali 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 di 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 a selezione multipla

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

Verifica 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 di chat che non è un componente aggiuntivo 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 Autorizza l'accesso con IAM.
  2. Aggiorna il codice di verifica del token in modo che utilizzi l'email dell'account del servizio del componente aggiuntivo Google Workspace per verificare la firma del token Bearer. Consulta Convalida le richieste di Google.