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 des messages, des pièces jointes, des réactions, des membres et des entités d'espace existants depuis vos autres plates-formes de messagerie vers les ressources de l'API Chat correspondantes. Vous pouvez importer ces données en créant des espaces Chat en mode importation et en y important des données. Une fois le processus terminé, ces espaces deviennent des espaces Chat standards.

  1. Examinez les limites d'utilisation des API et planifiez votre stratégie à l'avance.
  2. Configurez les autorisations pour l'application Chat.
  3. Créez un espace en mode importation.
  4. Importer des ressources
  5. Valider les ressources importées
  6. Rapprochez les différences de ressources importées avec les données sources.
  7. Mode d'importation complet :
  8. Créez des ressources d'adhésion.

Conditions préalables

Apps Script ;

Python

  • Python 3.6 ou version ultérieure
  • L'outil de gestion de packages pip

  • Les dernières bibliothèques clientes Google pour Python. Pour les installer ou les mettre à jour, exécutez la commande suivante dans votre interface de ligne de commande:

    pip3 install --upgrade google-api-python-client google-auth

  • Une application Chat publiée. Pour créer et publier une application Chat, consultez Créer une application Google Chat.

  • Autorisation configurée pour l'application Chat. L'application Chat doit disposer d'une autorité déléguée au niveau du domaine dans tous les domaines dans lesquels l'application importe du contenu. Consultez la section Autoriser les applications Chat.

Examiner les limites d'utilisation de l'API et planifier à l'avance

Le temps nécessaire pour importer des données dans Chat peut varier considérablement en fonction de la quantité de ressources Chat à importer. Planifiez à l'avance en examinant les limites d'utilisation de votre application Chat et la quantité de données dont l'importation est programmée à partir de la plate-forme de messagerie source, afin de déterminer une estimation du calendrier.

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. Afin de conserver l'heure de création de l'entité espace équivalente de la plate-forme de messagerie source, vous pouvez définir le paramètre createTime de l'espace. Cet createTime doit être défini sur une valeur comprise entre le 1er janvier 2000 et aujourd'hui.

Notez le name de l'espace que vous créez afin de pouvoir y faire référence par la suite lorsque vous y importerez du contenu.

À partir du moment où la méthode create est appelée, les applications Chat disposent de 30 jours pour importer des ressources dans l'espace, passer en mode importation et créer des ressources d'appartenance à l'aide du champ d'application chat.import. Les applications Chat peuvent toujours créer des adhésions après 30 jours avec les champs d'application d'adhésion standards de l'API Chat. Au bout de 30 jours, si l'espace est toujours en mode importation, il est automatiquement supprimé et devient inaccessible et irrécupérable. Planifiez à l'avance en examinant les limites d'utilisation de votre application Chat pour vous assurer que toutes les ressources planifiées peuvent être importées dans Chat pendant cette période.

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

Apps Script ;

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

Python

"""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': 'Import Mode Space',
            '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 auquel vous usurpez l'identité d'une autorité au niveau du domaine.

Importer des ressources

Pour importer des ressources d'autres plates-formes de messagerie, vous devez créer des ressources Google Chat (telles que des messages, des réactions et 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 à partir de laquelle vous effectuez la migration.

Messages

Vos applications Chat peuvent importer des messages en utilisant leur propre autorité ou au nom d'un utilisateur par le biais d'une usurpation d'identité. (L'auteur du message est défini sur le compte utilisateur emprunté.) 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 à partir de la plate-forme de messagerie source, vous pouvez définir le paramètre createTime du message. Cette valeur createTime doit être définie sur une valeur 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 le même createTime, même si les messages précédents associés à cette date sont supprimés.

Les messages contenant des URL tierces dans des espaces en mode importation ne peuvent pas afficher d'aperçu de lien dans Google Chat.

Lorsque vous créez les messages en mode importation, les espaces n'en avertissent aucun utilisateur et n'en envoient aucun e-mail, y compris les messages contenant des mentions utilisateur.

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

Python

"""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 :

Réactions

Votre application Chat peut importer des 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 dans les espaces en mode importation, consultez la section 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 dans les espaces en mode importation, consultez la section 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 de lier les URI des fichiers aux messages respectifs dans les espaces en mode importation. Vous pourrez ainsi importer des pièces jointes depuis d'autres plates-formes de messagerie pour éviter d'atteindre la limite interne de Google Chat pour l'importation de pièces jointes.

Historique des souscriptions

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

Dans de nombreux cas, lorsque ces membres historiques sont soumis à une règle de conservation des données dans Google, vous devez conserver les données (telles que les messages et les réactions) créées par les membres historiques d'un espace avant de les importer dans Chat. Lorsque l'espace est en mode importation, vous pouvez y importer ces adhésions historiques à l'aide de la méthode create sur la ressource Membership. Pour conserver la date de départ de l'ancienne adhésion, vous devez définir le deleteTime de l'abonnement. Ce délai de congés doit être précis, car il a une incidence sur les données qui sont conservées pour ces abonnements. De plus, cette valeur deleteTime doit être postérieure à 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 l'heure d'adhésion d'origine de l'historique d'adhésion. Contrairement à deleteTime, le createTime est facultatif. Si cette valeur n'est pas définie, createTime est automatiquement calculé en soustrayant 1 microseconde de deleteTime. Si cette valeur est définie, createTime doit être antérieur à deleteTime et doit être identique ou postérieure à l'heure de création de l'espace. Ces informations createTime ne sont pas utilisées pour déterminer la conservation des données et ne sont pas visibles dans les outils d'administration tels que la console d'administration Google et Google Vault.

Bien qu'un utilisateur puisse rejoindre et quitter un espace de différentes manières sur la plate-forme de messagerie source (via des invitations, une inscription par lui-même ou un ajout par un autre utilisateur), dans Chat, ces actions sont toutes représentées par les champs d'adhésion createTime et deleteTime de l'historique comme ayant été ajoutés ou supprimés.

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

Python

"""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 :

Valider les ressources importées

Votre application Chat peut lire 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 qu'au nom d'un utilisateur par emprunt d'identité. Pour en savoir plus, consultez Autoriser les applications Chat.

Votre application Chat peut également lire des messages individuels pour validation en appelant la méthode get sur la ressource Message. Les applications de 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 Chat peuvent également répertorier l'historique des adhésions en appelant la méthode list sur la ressource Membership. Une fois que l'espace a quitté le mode importation, la méthode list n'expose plus l'historique des adhésions. Les applications de chat ne peuvent appeler cette méthode que pour le compte d'un utilisateur par 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. Les applications de chat ne peuvent appeler cette méthode qu'en faisant preuve de leur propre autorité. Pour en savoir plus, consultez Autoriser les applications Chat.

Rapprocher les différences de ressources importées avec les 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é afin qu'il reflète le contenu actuel du message d'origine.

Messages

Pour mettre à jour les champs compatibles sur un message dans un espace en mode importation, appelez la méthode update sur la ressource Message. Les applications Chat ne peuvent appeler cette méthode qu'avec la même autorité que celle utilisée lors de la création initiale du message. Si vous avez utilisé l'emprunt d'identité lors de la création initiale du message, vous devez utiliser le même utilisateur 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 d'un espace en mode importation n'ont pas besoin d'être supprimés par leur créateur d'origine. Vous pouvez les supprimer en empruntant l'identité de n'importe quel utilisateur du domaine. Les applications de chat ne peuvent supprimer leurs propres messages que s'ils disposent de 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 dans les espaces en mode importation, consultez la section 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 dans les espaces en mode importation, consultez la section Autoriser les applications Chat.

Historique des souscriptions

Pour supprimer une appartenance historique à un espace en mode importation, utilisez la méthode delete sur la ressource Membership. Lorsqu'un espace quitte le mode importation, la méthode delete ne vous permet plus de supprimer l'historique des abonnements.

Vous ne pouvez pas mettre à jour l'historique des adhésions dans un espace en mode importation. Si vous souhaitez corriger un membre historique importé de manière incorrecte, vous devez d'abord le supprimer, puis le recréer lorsque l'espace est toujours 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 de prise en charge de l'authentification dans les espaces en mode importation, consultez la section Autoriser les applications Chat.

Mode d'importation complet

Avant d'appeler la méthode completeImport, vous devez vous assurer que la validation et le rapprochement des différences de ressources sont terminées. Quitter un espace en mode importation est un processus irréversible et permet de convertir l'espace du mode importation en espace standard. Aucun indicateur dans Chat n'attribue ces espaces à une importation de données.

Pour terminer 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 qu'au nom d'un utilisateur par emprunt d'identité. Pour en savoir plus, consultez Autoriser les applications Chat. Une fois cette méthode terminée, l'utilisateur dont l'identité est usurpée est ajouté à l'espace en tant que gestionnaire de l'espace. Cette méthode doit être appelée dans les 30 jours suivant l'appel initial de la méthode create.space. Si vous essayez d'appeler cette méthode une fois le délai de 30 jours écoulé, l'appel entraîne des échecs, car l'espace du 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.

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

Python

"""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 :

Créer des ressources d'adhésion

Pour ajouter des appartenances utilisateur à un espace qui est arrivé en mode importation, appelez la méthode create sur la ressource Membership. Les applications Chat peuvent continuer à utiliser le champ d'application chat.import et l'emprunt d'identité de l'utilisateur pour appeler cette méthode dans les 30 jours suivant l'appel de méthode create.space initial. L'utilisateur dont l'identité a été empruntée doit être le gestionnaire de l'espace.

Une fois le délai de 30 jours écoulé, les applications Chat nécessitent des niveaux d'adhésion supplémentaires pour appeler cette méthode.

Nous recommandons aux applications Chat de créer des ressources d'adhésion immédiatement après la fin de l'importation, afin que ces applications puissent continuer à utiliser le champ d'application chat.import pour la création d'adhésions et permettre à tous les membres d'accéder à l'espace importé.