Importer des données dans Google Chat

L'API Google Chat vous permet d'importer les données de vos autres plates-formes de messagerie dans Google Chat. Vous pouvez importer les messages, pièces jointes, réactions, membres et entités d'espace existants depuis vos autres plates-formes de messagerie vers les ressources de l'API Chat correspondantes. Pour importer ces données, vous pouvez créer des espaces Chat en mode importation et y importer des données. Une fois le processus terminé, ces espaces deviennent des espaces Chat standards.

Voici le processus d'importation complet :

1. Planifier votre importation
2. Configurer l'autorisation pour l'application Chat
3. Créer un espace en mode importation
4. Importer des ressources
5. Valider les ressources importées
6. Rapprocher les différences de ressources importées par rapport aux données sources
7. Mode d'importation complète
8. Donner accès à l'espace après le mode importation
9. Dépannage

Prérequis

Planifier votre importation

Planifiez en conséquence la quantité de données à importer, comprenez comment les limites d'utilisation et les quotas peuvent impacter le processus d'importation, et identifiez les types d'espaces Chat compatibles lors de l'importation vers un nouvel espace. Si vous êtes administrateur, lisez Importer les données des messages vers Google Chat à partir d'un autre service et suivez attentivement les étapes.

Examiner les limites d'utilisation des API

Le temps nécessaire pour importer des données dans Chat peut varier considérablement en fonction de la quantité de ressources Chat à importer. Consultez les limites d'utilisation de l'application Chat et la quantité de données dont l'importation est prévue depuis la plate-forme de messagerie source pour déterminer une estimation du calendrier.

Lorsque vous importez des messages dans un espace, nous vous recommandons de répartir les appels à la méthode messages.create() sur différents fils de discussion.

Identifier les espaces compatibles à importer

Le mode d'importation n'est compatible qu'avec les SpaceType de SPACE et GROUP_CHAT. Il n'est pas compatible avec DIRECT_MESSAGE. Pour en savoir plus, consultez la documentation sur SpaceType.

Créer un espace en mode importation

Pour créer un espace en mode importation, appelez la méthode create sur la ressource Space et définissez importMode sur true.

Lorsque vous créez l'espace en mode importation, tenez compte des points suivants.

• La date et l'heure : n'oubliez pas que le mode importation doit être terminé dans les 90 jours. Si l'espace est toujours en mode importation 90 jours après l'appel de la méthode spaces.create(), il est automatiquement supprimé et devient inaccessible et irrécupérable.
  • Utilisez la valeur du champ importModeExpireTime pour suivre l'expiration du délai de 90 jours.
  • N'utilisez pas la valeur du champ createTime pour suivre l'expiration du délai de 90 jours. Ce n'est pas toujours la même chose que lorsque vous appelez la méthode spaces.create(). Lorsque vous utilisez le mode d'importation, le champ createTime peut être défini sur le code temporel historique auquel l'espace a été créé dans la source afin de conserver l'heure de création d'origine.
• Nom de ressource de l'espace (name) : identifiant unique utilisé pour récupérer des informations sur l'espace spécifique et référencé dans les étapes ultérieures lors de l'importation de contenu dans l'espace.

Pour conserver l'heure de création de l'entité spatiale équivalente de la plate-forme de messagerie source, vous pouvez définir le createTime de l'espace. Cette createTime doit être définie sur une valeur comprise entre le 1er janvier 2000 et la date actuelle.

Pour créer un espace externe en mode importation, définissez externalUserAllowed sur true. Une fois l'importation terminée, vous pouvez ajouter des utilisateurs externes.

L'exemple suivant montre comment créer un espace en mode importation :

function createSpaceInImportMode() {
  const space = Chat.Spaces.create({
      spaceType: 'SPACE',
      displayName: 'DISPLAY_NAME',
      importMode: true,
      createTime: (new Date('January 1, 2000')).toJSON()
  });
  console.log(space.name);
}

"""Create a space in import mode."""

import datetime

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [
    'https://www.googleapis.com/auth/chat.import',
]

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

result = (
    service.spaces()
    .create(
        body={
            'spaceType': 'SPACE',
            'displayName': 'DISPLAY_NAME',
            'importMode': True,
            'createTime': f'{datetime.datetime(2000, 1, 1).isoformat()}Z',
        }
    )
    .execute()
)

print(result)

Remplacez les éléments suivants :

• EMAIL : adresse e-mail du compte utilisateur que vous usurpez avec une autorité à l'échelle du domaine.
• DISPLAY_NAME : nom de l'espace créé en mode importation. Il doit s'agir d'un nom unique pour l'espace, qui sera affiché aux utilisateurs de Chat. Nous vous recommandons d'utiliser le même nom à afficher que celui de l'espace à partir duquel vous importez des données.

Importer des ressources

Pour importer des ressources depuis d'autres plates-formes de messagerie, vous devez créer des ressources Google Chat (comme des messages, des réactions ou des pièces jointes) dans l'espace en mode importation. Lorsque vous créez une ressource dans l'espace, vous spécifiez les données de la ressource associée à partir de la plate-forme de messagerie depuis laquelle vous effectuez la migration.

Messages

Vos applications Chat peuvent importer des messages en utilisant leur propre autorisation ou au nom d'un utilisateur par le biais de l'usurpation d'identité. L'auteur du message est défini sur le compte utilisateur usurpé. Pour en savoir plus, consultez Autoriser les applications Chat. Pour importer un message dans un espace en mode importation, appelez la méthode create sur la ressource Message. Pour conserver l'heure de création du message d'origine de la plate-forme de messagerie source, vous pouvez définir le createTime du message. Cette valeur createTime doit être comprise entre l'heure de création de l'espace que vous avez définie précédemment et l'heure actuelle.

Les messages d'un même espace ne peuvent pas contenir la même createTime, même si les messages précédents avec cette heure sont supprimés.

Les aperçus de liens ne peuvent pas s'afficher dans Google Chat pour les messages contenant des URL tierces dans les espaces en mode importation.

Lorsque vous créez des messages en mode importation, les espaces n'envoient pas de notifications ni d'e-mails aux utilisateurs, y compris pour les messages contenant des mentions d'utilisateurs.

L'exemple suivant montre comment créer un message dans un espace en mode importation :

"""Create a message in import mode space."""

import datetime

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [
    'https://www.googleapis.com/auth/chat.import',
]

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

NAME = 'spaces/SPACE_NAME'
result = (
    service.spaces()
    .messages()
    .create(
        parent=NAME,
        body={
            'text': 'Hello, world!',
            'createTime': f'{datetime.datetime(2000, 1, 2).isoformat()}Z',
        },
    )
    .execute()
)

print(result)

Remplacez les éléments suivants :

• EMAIL : adresse e-mail du compte utilisateur que vous usurpez avec une autorité à l'échelle du domaine.
• SPACE_NAME : nom de l'espace créé en mode importation.

Réactions

Votre application Chat peut importer les réactions aux messages à l'aide de l'API Chat. Pour en savoir plus sur les méthodes de ressources et les types d'authentification compatibles dans les espaces en mode importation, consultez Autoriser les applications Chat.

Pièces jointes

Votre application Chat peut importer des pièces jointes à l'aide de l'API Chat. Pour en savoir plus sur les méthodes de ressources et les types d'authentification compatibles dans les espaces en mode importation, consultez Autoriser les applications Chat. Toutefois, nous vous recommandons vivement d'utiliser l'API Google Drive pour importer les pièces jointes en tant que fichiers Google Drive et associer les URI des fichiers aux messages correspondants dans les espaces en mode importation. Cela vous permettra d'importer les pièces jointes depuis d'autres plates-formes de messagerie sans dépasser la limite interne de Google Chat pour l'importation de pièces jointes.

Abonnements historiques

Les membres historiques sont des membres créés pour les utilisateurs qui ont déjà quitté l'entité espace d'origine sur la plate-forme de messagerie source, mais dont vous souhaitez conserver les données dans Chat. Pour savoir comment ajouter des membres une fois que l'espace n'est plus en mode importation, consultez Créer une ressource d'appartenance.

Dans de nombreux cas, lorsque ces anciens membres sont soumis à une règle de conservation des données dans Google, vous souhaitez conserver les données (telles que les messages et les réactions) créées par les anciens membres dans un espace avant de les importer dans Chat. Lorsque l'espace est en mode importation, vous pouvez importer ces adhésions historiques dans l'espace à l'aide de la méthode create sur la ressource Membership. Pour préserver la date de départ de l'abonnement historique, vous devez définir le deleteTime de l'abonnement. Cette durée d'absence doit être exacte, car elle a une incidence sur les données à conserver pour ces abonnements. De plus, ce deleteTime doit être postérieur à l'horodatage de création de l'espace et ne doit pas être un horodatage futur.

En plus de deleteTime, vous pouvez également définir createTime pour conserver la date d'adhésion d'origine de l'historique des abonnements. Contrairement à deleteTime, createTime est facultatif. Si elle n'est pas définie, createTime est calculée automatiquement en soustrayant une microseconde à deleteTime. Si elle est définie, createTime doit être antérieure à deleteTime et doit être égale ou postérieure à l'heure de création de l'espace. Ces informations createTime ne sont pas utilisées pour déterminer la durée de conservation des données et ne sont pas visibles dans les outils d'administration tels que la console d'administration Google et Google Vault.

Dans la plate-forme de messagerie source, un utilisateur peut rejoindre et quitter un espace de plusieurs façons (par le biais d'invitations, en le rejoignant lui-même ou en étant ajouté par un autre utilisateur). Dans Chat, ces actions sont toutes représentées par les champs d'historique des membres createTime et deleteTime comme étant ajoutées ou supprimées.

L'exemple suivant montre comment créer un membre historique dans un espace en mode importation :

"""Create a historical membership in import mode space."""

import datetime

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [
    'https://www.googleapis.com/auth/chat.import',
]

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

NAME = 'spaces/SPACE_NAME'
USER = 'users/USER_ID'
result = (
    service.spaces()
    .members()
    .create(
        parent=NAME,
        body={
            'createTime': f'{datetime.datetime(2000, 1, 3).isoformat()}Z',
            'deleteTime': f'{datetime.datetime(2000, 1, 4).isoformat()}Z',
            'member': {'name': USER, 'type': 'HUMAN'},
        },
    )
    .execute()
)

print(result)

Remplacez les éléments suivants :

• EMAIL : adresse e-mail du compte utilisateur que vous usurpez avec une autorité à l'échelle du domaine.
• SPACE_NAME : nom de l'espace créé en mode importation.
• USER_ID : ID unique de l'utilisateur.

Importer des ressources dans un espace externe

Vous ne pouvez créer un espace externe en mode importation qu'avec des identifiants appartenant à des utilisateurs de votre organisation Workspace. Cela ne s'applique que lorsque l'espace est en mode importation. Une fois que l'espace a quitté le mode importation, les utilisateurs externes peuvent être invités à rejoindre les espaces importés (voir la section sur l'accès). Leurs identifiants peuvent être utilisés pour appeler l'API Chat.

Valider les ressources importées

Votre application Chat peut relire et valider le contenu d'un espace en mode importation en appelant la méthode list sur la ressource Message. Vous pouvez lire les ressources Reaction et Attachment à partir des champs emojiReactionSummaries et attachment de n'importe quel message renvoyé. Les applications de chat ne peuvent appeler cette méthode au nom d'un utilisateur que par le biais de l'emprunt d'identité. Pour en savoir plus, consultez Autoriser les applications Chat.

Votre application Chat peut également lire des messages individuels pour les valider en appelant la méthode get sur la ressource Message. Les applications Chat ne peuvent appeler cette méthode que pour lire leurs propres messages en utilisant leur propre autorité. Pour en savoir plus, consultez Autoriser les applications Chat.

Les applications de chat peuvent également lister les membres historiques en appelant la méthode list sur la ressource Membership. Une fois que l'espace quitte le mode importation, la méthode list n'expose plus les adhésions historiques. Les applications de chat ne peuvent appeler cette méthode au nom d'un utilisateur que par le biais de l'usurpation d'identité. Pour en savoir plus, consultez Autoriser les applications Chat.

Vous pouvez lire les propriétés d'un espace en mode importation en appelant la méthode get sur la ressource Space. La réponse inclura également importModeExpireTime, ce qui vous permettra de suivre correctement le délai nécessaire pour terminer le processus d'importation. Les applications de chat ne peuvent appeler cette méthode qu'avec leur propre autorité. Pour en savoir plus, consultez Autoriser les applications Chat.

Rapprocher les différences de ressources importées par rapport aux données sources

Si une ressource importée ne correspond plus à l'entité d'origine de la plate-forme de messagerie source en raison de modifications apportées à l'entité d'origine lors de l'importation, les applications Chat peuvent appeler l'API Chat pour modifier la ressource de chat importée. Par exemple, si un utilisateur modifie un message dans la plate-forme de messagerie source après sa création dans Chat, les applications Chat peuvent mettre à jour le message importé pour qu'il reflète le contenu actuel du message d'origine.

Messages

Pour mettre à jour les champs compatibles d'un message dans un espace en mode importation, appelez la méthode update sur la ressource Message. Les applications de chat ne peuvent appeler cette méthode qu'avec la même autorité que celle utilisée lors de la création du message initial. Si vous avez utilisé l'usurpation d'identité lors de la création du message initial, vous devez utiliser le même utilisateur usurpé pour mettre à jour ce message.

Pour supprimer un message dans un espace en mode importation, appelez la méthode delete sur la ressource Message. Les messages dans un espace en mode importation n'ont pas besoin d'être supprimés par le créateur du message d'origine. Ils peuvent être supprimés en se faisant passer pour n'importe quel utilisateur du domaine. Les applications Chat ne peuvent supprimer que leurs propres messages en utilisant leur propre autorité. Pour en savoir plus, consultez Autoriser les applications Chat.

Réactions

Pour supprimer une réaction à un message dans un espace en mode importation, utilisez la méthode delete sur la ressource reactions. Pour en savoir plus sur les méthodes de ressources et les types d'authentification compatibles dans les espaces en mode importation, consultez Autoriser les applications Chat.

Pièces jointes

Pour mettre à jour les pièces jointes d'un message dans un espace en mode importation, utilisez la méthode upload sur la ressource media. Pour en savoir plus sur les méthodes de ressources et les types d'authentification compatibles dans les espaces en mode importation, consultez Autoriser les applications Chat.

Abonnements historiques

Pour supprimer un membre historique dans un espace en mode importation, utilisez la méthode delete sur la ressource Membership. Une fois qu'un espace n'est plus en mode importation, la méthode delete ne vous permet plus de supprimer les adhésions historiques.

Vous ne pouvez pas modifier une adhésion historique dans un espace en mode importation. Si vous souhaitez corriger une adhésion historique importée de manière incorrecte, vous devez d'abord la supprimer, puis la recréer tant que l'espace est encore en mode importation.

Spaces

Pour mettre à jour les champs compatibles dans un espace en mode importation, utilisez la méthode patch sur la ressource spaces.

Pour supprimer un espace en mode Importation, utilisez la méthode delete sur la ressource spaces.

Pour en savoir plus sur les méthodes de ressources et les types d'authentification compatibles dans les espaces en mode importation, consultez Autoriser les applications Chat.

Mode d'importation complète

Avant d'appeler la méthode completeImport, vous devez vous assurer que la validation et la réconciliation des différences de ressources sont terminées. Quitter un espace en mode importation est une action irréversible qui convertit l'espace en mode importation en espace standard. Dans Chat, aucun indicateur n'attribue ces espaces à une importation de données.

Notez la date et l'heure auxquelles vous appelez completeImport, le nom de ressource de l'utilisateur qui a effectué l'appel et la réponse renvoyée. Cela peut être utile si vous rencontrez des problèmes et devez les examiner.

Pour quitter le mode importation et rendre l'espace accessible aux utilisateurs, l'application Chat peut appeler la méthode completeImport sur la ressource Space. Les applications de chat ne peuvent appeler cette méthode au nom d'un utilisateur que par le biais de l'usurpation d'identité. Pour en savoir plus, consultez Autoriser les applications Chat. L'utilisateur dont l'identité est usurpée est ajouté à l'espace en tant que gestionnaire de l'espace une fois cette méthode terminée. Cette méthode doit être appelée dans les 90 jours suivant l'appel initial de la méthode create.space. Si vous tentez d'appeler cette méthode après l'expiration du délai de 90 jours, l'appel échoue, car l'espace en mode importation est supprimé et n'est plus accessible à l'application Chat.

L'utilisateur usurpé dans la méthode completeImport n'a pas besoin d'être le créateur de l'espace.

N'appelez pas completeImport trop près de importModeExpireTime, car nous ne pouvons pas garantir que la demande arrivera avant importModeExpireTime. De plus, des conflits peuvent survenir avec le traitement des données dans les systèmes déclenchés à l'heure d'expiration. Nous vous recommandons d'appeler le completeImport au moins 30 minutes avant importModeExpireTime.

L'exemple suivant montre comment terminer le mode d'importation :

"""Complete import."""

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [
    'https://www.googleapis.com/auth/chat.import',
]

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

NAME = 'spaces/SPACE_NAME'
result = service.spaces().completeImport(name=NAME).execute()

print(result)

Remplacez les éléments suivants :

• EMAIL : adresse e-mail du compte utilisateur que vous usurpez avec une autorité à l'échelle du domaine.
• SPACE_NAME : nom de l'espace créé en mode importation.

Donner accès à l'espace après le mode importation

Pour donner aux utilisateurs Chat accès à l'espace récemment importé, les applications Chat peuvent continuer à utiliser le champ d'application chat.import et l'usurpation d'identité de l'utilisateur dans les 90 jours suivant l'appel de la méthode create.space() initiale pour effectuer les opérations suivantes :

• Ajoutez des membres à l'espace : appelez la méthode create() sur la ressource Membership. Nous recommandons aux applications Chat de créer des ressources Membership immédiatement après l'importation de l'espace, afin qu'elles puissent continuer à utiliser le champ d'application chat.import et s'assurer que tous les membres importés ont accès à l'espace. Vous devez prioriser l'ajout de membres susceptibles d'être soumis à la règle de conservation Vault, qui permet de conserver les messages importés même s'ils sont hors période de conservation.
• Définissez une audience cible : appelez la méthode update() sur la ressource Space. Pour savoir comment créer et ajouter des audiences cibles, consultez Rendre un espace Google Chat visible par des utilisateurs spécifiques dans une organisation Google Workspace.

Pour utiliser ces méthodes avec le champ d'application chat.import, l'utilisateur usurpé doit être un gestionnaire d'espace.

Pour les espaces externes, la méthode create() d'appartenance permet également d'inviter des utilisateurs externes à votre organisation Workspace. Assurez-vous de bien comprendre toutes les limitations connues pour les utilisateurs externes.

Dépannage

Si vous rencontrez un problème lors de l'importation d'espaces de discussion Chat, consultez les problèmes suivants pour obtenir de l'aide. Si vous rencontrez une réponse d'erreur, notez-la (copiez/collez le texte dans un document ou enregistrez une capture d'écran) pour référence et dépannage ultérieurs.

Lorsqu'un espace est importé avec succès, CompleteImportSpace se termine avec l'état OK.

Vous n'avez pas terminé l'importation avant l'expiration du délai de 90 jours.

Comme décrit précédemment dans Créer un espace en mode importation, si l'espace est toujours en mode importation 90 jours après l'appel de la méthode de création, il est automatiquement supprimé et devient inaccessible et irrécupérable.

Malheureusement, l'espace supprimé n'est plus disponible ni récupérable, et vous devez recommencer le processus d'importation.

Si l'espace n'a pas été importé, car il contient trop de données à importer dans la période de 90 jours avec les limites d'utilisation actuelles, divisez-le en deux ou plusieurs espaces plus petits à des fins d'archivage, puis recommencez le processus d'importation.

Retrouver des espaces manquants

Si vous ne trouvez pas le nouvel espace Chat, consultez le tableau ci-dessous pour connaître la réponse que vous avez reçue de CompleteImportSpace, ainsi que l'explication et la solution.