Convertir une application Google Chat interactive en module complémentaire Google Workspace

Si vous avez créé et publié une application Google Chat qui utilise des événements d'interaction de l'API Google Chat, comme une application basée sur le démarrage rapide de l'application Google Chat, cette page vous explique comment la convertir en module complémentaire Google Workspace qui étend Google Chat.

En effectuant la conversion, votre application Google Chat peut utiliser le framework des modules complémentaires Google Workspace, ce qui ouvre de nouvelles possibilités d'intégration et de fonctionnalités dans Google Chat et dans Google Workspace. Par exemple, au lieu de deux distributions (une application Google Chat et un module complémentaire Google Workspace), vous pouvez distribuer un seul module complémentaire Google Workspace via Google Workspace Marketplace. Ce module complémentaire étend les applications Chat aux autres applications hôtes Google Workspace, comme Gmail, Agenda et Docs.

Limites

Avant de commencer la conversion, consultez les limites des modules complémentaires Google Workspace qui étendent Google Chat pour vous assurer que votre application Google Chat peut être convertie sans perdre de fonctionnalités essentielles.

Étape 1 : Copiez le code de votre application Google Chat existante

Le processus de conversion nécessite des modifications de code. Pour éviter d'affecter votre application Google Chat en production, créez une copie de votre code et travaillez dessus.

Apps Script

  1. Ouvrez votre projet Google Apps Script existant pour l'application Google Chat.
  2. À gauche, cliquez sur Vue d'ensemble .
  3. À droite, cliquez sur Créer une copie .
  4. À gauche, cliquez sur Paramètres du projet .
  5. Sous Projet Google Cloud, cliquez sur Changer de projet.
  6. Saisissez le même numéro de projet que celui associé à votre projet d'application Google Chat existant.
  7. Cliquez sur Définir un projet.

HTTP

Créez un fork ou une copie de votre codebase existant et déployez-le en tant que nouveau service, distinct de votre application Google Chat en production.

Si votre application est déployée sur Google Cloud et repose sur des fonctionnalités liées au projet Google Cloud (par exemple, l'identité App Engine par défaut), le nouveau code doit être déployé sur un service associé au projet d'application Google Chat existant.

Étape 2 : Modifiez le code copié

Les modules complémentaires Google Workspace qui étendent Google Chat utilisent des structures de requête et de réponse différentes de celles des applications Google Chat créées avec des événements d'interaction de l'API Chat. Vous devez mettre à jour votre code pour utiliser le module complémentaire Google Workspace EventObject au lieu de l'API Google Chat Event pour les requêtes et les réponses. Utilisez le guide de conversion du code pour modifier votre code.

Étape 3 : Activez la configuration du module complémentaire Google Workspace pour les utilisateurs de test

Utilisez la console Google Cloud pour configurer les paramètres du module complémentaire Google Workspace pour votre application Google Chat :

  1. Accédez à la page de configuration de l'API Google Chat dans la console Google Cloud.

    Accéder à la page de configuration de l'API Google Chat

  2. Sous Fonctionnalités interactives, cliquez sur Convertir en module complémentaire.

  3. Activez Activer les paramètres de configuration du module complémentaire.

  4. Dans la section Visibilité, ajoutez les adresses e-mail de vos utilisateurs test.

  5. Si nécessaire, mettez à jour les paramètres de connexion avec l'URL du point de terminaison de déploiement ou l'ID de déploiement Apps Script du code de votre application Google Chat copiée et modifiée à l'étape 2.

  6. Cliquez sur Enregistrer et tester.

Étape 4 : Testez l'application convertie

Testez minutieusement les fonctionnalités du module complémentaire Google Workspace à l'aide des comptes utilisateur de test configurés à l'étape 3. Vérifiez toutes les fonctionnalités et interactions.

Étape 5 : Terminez la conversion pour tous les utilisateurs

Une fois que vous avez vérifié que le module complémentaire Google Workspace converti fonctionne correctement, vous pouvez le rendre disponible pour tous les utilisateurs.

  1. Accédez à la page de configuration de l'API Google Chat dans la console Google Cloud.

    Accéder à la page de configuration de l'API Google Chat

  2. Sous Fonctionnalités interactives, cliquez sur Convertir en module complémentaire. Un panneau latéral s'ouvre.

  3. Dans le panneau latéral, cliquez sur Convertir en module complémentaire.

  4. Saisissez l'ID de votre projet, puis cliquez sur Convertir.

Votre application Google Chat est désormais un module complémentaire Google Workspace qui étend Google Chat.

Facultatif : Nettoyer ou libérer les ressources Google Cloud inutilisées

Si vous le souhaitez, après avoir converti votre application Google Chat en module complémentaire Google Workspace, vous pouvez désactiver les ressources utilisées par l'application Google Chat qui ne sont plus utilisées pour éviter qu'elles ne soient facturées sur votre compte Google Cloud.

Guide de conversion de code

Cette section décrit en détail le mappage entre le format d'interaction de l'API Google Chat Event et le format du module complémentaire Google Workspace EventObject.

Mappage des demandes

Le tableau suivant montre comment les champs de l'API Google Chat Event sont mappés avec les champs correspondants du module complémentaire Google Workspace EventObject.

Champ Event d'interaction avec l'API Google Chat Champ EventObject du module complémentaire Google Workspace Remarques
action.actionMethodName N/A Pour les interactions avec les cartes, le nom de la méthode peut être transmis en tant que paramètre dans commonEventObject.parameters. Consultez Ouvrir une boîte de dialogue initiale.
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 Disponible dans différentes charges utiles en fonction du type d'événement.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 Disponible dans différentes charges utiles en fonction du type d'événement.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 Disponible dans différentes charges utiles en fonction du type d'événement.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 Disponible dans différentes charges utiles en fonction du type d'événement.
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
 Disponible dans différentes charges utiles en fonction du type d'événement.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 Disponible dans différentes charges utiles en fonction du type d'événement.
token N/A La validation est gérée différemment. Pour en savoir plus, consultez Demander la validation pour les applications HTTP.
type N/A Le type d'événement peut être déduit du trigger.
user chat.user

Mappage des demandes par cas d'utilisation

Le tableau suivant présente les différences entre les charges utiles des requêtes pour les cas d'utilisation courants entre les applications Google Chat créées avec des événements d'interaction de l'API Chat et les modules complémentaires Google Workspace qui étendent Google Chat.

Cas d'utilisation Charge utile de l'interaction avec l'API Chat Event Charge utile du module complémentaire Google Workspace EventObject
Application ajoutée à l'espace 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
Supprimer une application d'un espace 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
Un utilisateur @mentionne une application 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
L'utilisateur @mentionne une application pour l'ajouter à l'espace. Vous devez traiter une demande de Google Chat :
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 Vous devez traiter deux demandes de Google Chat.

Première demande :
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Deuxième requête :
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
Commande à barre oblique 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Commande à barre oblique pour ajouter une application à l'espace Vous devez traiter une demande de Google Chat :
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 Vous devez traiter deux demandes de Google Chat.

Première demande :
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Deuxième requête :
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
L'utilisateur clique sur un bouton d'une fiche ou d'une boîte de dialogue. 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

Pour les événements de boîte de dialogue, common.formInputs contient les valeurs des widgets. Exemple 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": "..."
    }
  }
}

Pour les événements de boîte de dialogue, commonEventObject.formInputs contient les valeurs des widgets. Exemple Google Apps Script :

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
L'utilisateur envoie des informations dans une fiche d'accueil d'application. 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
L'utilisateur appelle une commande d'application à l'aide d'une commande rapide. 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Aperçu du lien 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
L'utilisateur met à jour un widget dans un message ou une boîte de dialogue. 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

Mappage des réponses par cas d'utilisation

Les modules complémentaires Google Workspace qui étendent Google Chat renvoient des actions au lieu d'un objet Message. Le tableau suivant met en correspondance les types de réponse Message de l'API Google Chat avec leurs équivalents dans les actions des modules complémentaires Google Workspace.

Cas d'utilisation Réponse de l'API Google Chat Message Réponse de l'action Chat du module complémentaire Google Workspace
Créer un message dans l'espace appelé 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse est facultatif. Pour en savoir plus, consultez Répondre à une commande à barre oblique.

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

Pour en savoir plus, consultez Envoyer un message.
Modifier un message 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

Pour en savoir plus, consultez Modifier un message (Chat).

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

Pour en savoir plus, consultez Mettre à jour un message (modules complémentaires).
Aperçu du lien 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

Pour en savoir plus, consultez Prévisualiser un lien (Chat).

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

Pour en savoir plus, consultez Prévisualiser un lien(modules complémentaires).
Ouvrir une boîte de dialogue initiale 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

Pour en savoir plus, consultez Ouvrir une boîte de dialogue (Chat).

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
La carte que vous envoyez peut contenir des widgets avec des actions onClick. Pour les modules complémentaires Google Workspace HTTP, configurez ces actions pour appeler un point de terminaison de fonction : 
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

Pour en savoir plus, consultez Ouvrir une boîte de dialogue (modules complémentaires).
Fermer une boîte de dialogue 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

Pour en savoir plus, consultez Fermer une boîte de dialogue (Chat).

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

Pour en savoir plus, consultez Fermer une boîte de dialogue (modules complémentaires).
Se connecter à un système externe (demander une configuration) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

Pour en savoir plus, consultez Se connecter à un système externe.

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

Pour en savoir plus, consultez Associer votre module complémentaire Google Workspace à un service tiers.
Éléments de saisie semi-automatique dans les widgets interactifs 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

Pour en savoir plus, consultez Ajouter un menu à sélection multiple.

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

Pour en savoir plus, consultez Collecter et traiter les informations des utilisateurs Google Chat.

Gérer les interactions avec les cartes sur les messages créés avant la conversion

Lorsque vous convertissez une application Google Chat HTTP en module complémentaire Google Workspace, les interactions avec les fiches des messages créés avant la conversion nécessitent un traitement spécial. Les modules complémentaires Google Workspace utilisent une URL HTTP complète pour le action.function d'une fiche, tandis que les applications Google Chat créées avec des événements d'interaction de l'API Google Chat utilisent un nom de fonction. Le tableau suivant récapitule ces différences.

Application Google Chat créée avec des événements d'interaction de l'API Google Chat Module complémentaire Google Workspace qui étend Google Chat
Configuration Vous configurez un seul point de terminaison pour tous les événements dans la console Google Cloud. Lorsque vous implémentez des interactions avec des cartes, le action d'une carte ne contient que le nom de la fonction à exécuter. Le point de terminaison HTTP commun est appelé pour les événements de clic sur les cartes.

Pour en savoir plus, consultez Ouvrir une boîte de dialogue (Chat).



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 Vous pouvez éventuellement configurer des points de terminaison par événement dans la console Google Cloud, mais cela n'inclut pas les événements de clic sur une fiche. Lorsque vous implémentez des interactions avec des cartes, le action d'une carte doit contenir l'URL complète du point de terminaison HTTP à appeler. Vous pouvez définir un point de terminaison HTTP unique par bouton ou utiliser un point de terminaison commun et transmettre l'action en tant que paramètre dans action.parameters.

Pour en savoir plus, consultez Ouvrir une boîte de dialogue (modules complémentaires).



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

Pour que les interactions avec les cartes fonctionnent pour les messages créés avant la conversion, configurez une URL d'interaction avec les cartes sur la page de configuration de l'API Google Chat.

Cette URL n'est utilisée que pour les interactions sur les messages créés avant la conversion de votre application. Lorsqu'un utilisateur interagit avec l'un de ces messages, la valeur action.function d'origine est transmise en tant que paramètre appelé __action_method_name__.

Exemple : clic sur une carte

Si vous avez configuré l'URL d'interaction avec la fiche sur https://.../card-interaction-handler et qu'un utilisateur clique sur une fiche dans un message historique avec l'action suivante :

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

Un événement est envoyé à l'URL d'interaction avec la carte que vous avez configurée, au format suivant :

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

Exemple : Menu multi-sélection

Si un utilisateur interagit avec un menu à sélection multiple comportant une source de données externe :

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

Un événement est envoyé à l'URL d'interaction avec la carte que vous avez configurée, au format suivant :

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

Si vous activez l'option Utiliser une URL de point de terminaison HTTP commune pour tous les déclencheurs pour vos déclencheurs HTTP, l'URL commune est également utilisée pour les événements Bouton cliqué.

Valider les requêtes pour les modules complémentaires HTTP Google Workspace qui étendent Chat

Pour les applications Google Chat basées sur HTTP, la logique permettant de vérifier que les requêtes proviennent de Google doit être mise à jour lors de la conversion en module complémentaire Google Workspace.

Voici les principales différences concernant la validation des demandes :

Type d'application Audience acceptée Adresse e-mail du compte de service
Application Google Chat créée avec des événements d'interaction de l'API Google Chat Numéro du projet chat@system.gserviceaccount.com
Module complémentaire Google Workspace étendant Google Chat Point de terminaison HTTP uniquement Adresse e-mail du compte de service par projet

L'adresse e-mail unique du compte de service de votre module complémentaire Google Workspace se trouve dans la section Convertir en modules complémentaires Google Workspace de la page de configuration de l'API Google Chat dans la console Google Cloud.

Pour valider les demandes dans votre module complémentaire Google Workspace mis à niveau :

  1. Si vous utilisez des fonctions Cloud Run, attribuez le rôle roles/cloudfunctions.invoker au compte de service de chaque module complémentaire. Consultez Autoriser l'accès avec IAM.
  2. Mettez à jour votre code de validation du jeton pour utiliser l'adresse e-mail du compte de service du module complémentaire Google Workspace afin de valider la signature du jeton du porteur. Consultez Valider les demandes de Google.