Importar dados para o Google Chat

Com a API Google Chat, é possível importar dados de outras plataformas de mensagens para o Google Chat. É possível importar mensagens, anexos, reações, associações e entidades de espaço de outras plataformas de mensagens para recursos da API Chat correspondentes. Para importar esses dados, crie espaços do Chat no modo de importação e importe os dados para esses espaços. Depois que o processo for concluído, esses espaços vão virar espaços padrão do Chat.

Confira a seguir o processo de importação completo:

  1. Planejar a importação
  2. Configurar a autorização para o app Chat
  3. Criar um espaço no modo de importação
  4. Importar recursos
  5. Validar os recursos importados
  6. Reconciliar as diferenças de recursos importados com os dados de origem
  7. Modo de importação completo
  8. Dar acesso ao espaço após o modo de importação
  9. Solução de problemas

Pré-requisitos

Apps Script

Python

Planejar a importação

Planeje a quantidade de dados a serem importados, entenda como os limites e cotas de uso podem afetar o processo de importação e conheça os tipos de espaços do Chat com suporte à importação para um novo espaço. Se você for administrador, leia Importar dados de mensagens de outro serviço para o Google Chat e siga as etapas com atenção.

Analisar os limites de uso da API

O tempo necessário para importar dados para o Chat pode variar muito dependendo da quantidade de recursos do Chat a serem importados. Analise os limites de uso do app de chat e a quantidade de dados programados para importação da plataforma de mensagens de origem para determinar um cronograma estimado.

Ao importar mensagens para um espaço, recomendamos que você distribua as chamadas para o método messages.create() em diferentes linhas de mensagens.

Identifique os espaços compatíveis para importar

O modo de importação só aceita o SpaceType de SPACE e GROUP_CHAT. Ele não é compatível com DIRECT_MESSAGE. Consulte a documentação sobre SpaceType para mais informações.

Criar um espaço no modo de importação

Para criar um espaço no modo de importação, chame o método create no recurso Space e defina importMode como true.

Ao criar o espaço no modo de importação, observe o seguinte.

  • A data e a hora: lembre-se de que o modo de importação precisa ser concluído em até 90 dias. Se o espaço ainda estiver no modo de importação após 90 dias da chamada do método spaces.create(), ele será excluído automaticamente e ficará inacessível e irrecuperável.
    • Use o valor do campo importModeExpireTime para acompanhar a expiração do período de 90 dias.
    • Não use o valor do campo createTime para acompanhar a expiração do período de 90 dias. Isso não é sempre o mesmo que quando você chama o método spaces.create(). Ao usar o modo de importação, o campo createTime pode ser definido como o carimbo de data/hora histórico em que o espaço foi criado na origem para preservar o horário de criação original.
  • O nome do recurso do espaço (name): o identificador exclusivo usado para extrair informações sobre o espaço específico e referenciado em etapas posteriores ao importar conteúdo para o espaço.

Para preservar o horário de criação da entidade de espaço equivalente da plataforma de mensagens de origem, defina o createTime do espaço. O createTime precisa ser definido como um valor entre 1º de janeiro de 2000 e o momento atual.

Para criar um espaço externo no modo de importação, defina externalUserAllowed como true. Depois que a importação for concluída, você poderá adicionar usuários externos.

O exemplo a seguir mostra como criar um espaço no modo de importação:

Apps Script

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);
}

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': 'DISPLAY_NAME',
            'importMode': True,
            'createTime': f'{datetime.datetime(2000, 1, 1).isoformat()}Z',
        }
    )
    .execute()
)

print(result)

Substitua:

  • EMAIL: o endereço de e-mail da conta de usuário que você está falsificando com autoridade em todo o domínio.
  • DISPLAY_NAME: o nome do espaço criado no modo de importação. Esse precisa ser um nome exclusivo para o espaço exibido aos usuários do Chat. Recomendamos usar o mesmo nome de exibição do espaço de onde você está importando dados.

Importar recursos

Para importar recursos de outras plataformas de mensagens, crie recursos do Google Chat (como mensagens, reações e anexos) no espaço do modo de importação. Ao criar um recurso no espaço, você especifica os dados do recurso relacionado da plataforma de mensagens de onde você está migrando.

Mensagens

Os apps do Chat podem importar mensagens usando a própria autoridade ou em nome de um usuário por meio de falsificação de identidade. O autor da mensagem é definido como a conta de usuário falsificada. Para mais informações, consulte Autorizar apps do Chat. Para importar uma mensagem em um espaço de modo de importação, chame o método create no recurso Message. Para preservar o horário de criação da mensagem original da plataforma de mensagens de origem, defina o createTime da mensagem. O createTime precisa ser definido como um valor entre o horário de criação do espaço definido anteriormente e o horário atual.

As mensagens no mesmo espaço não podem conter o mesmo createTime, mesmo que as mensagens anteriores com esse horário sejam excluídas.

Mensagens com URLs de terceiros em espaços no modo de importação não podem renderizar pré-visualizações de links no Google Chat.

Quando você cria as mensagens no modo de importação, os espaços não notificam nem enviam e-mails a nenhum usuário, incluindo mensagens que contêm menções de usuários.

O exemplo a seguir mostra como criar uma mensagem em um espaço do modo de importação:

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)

Substitua:

Reações

O app de chat pode importar reações a mensagens usando a API Chat. Para saber mais sobre os métodos de recurso e os tipos de suporte à autenticação nos espaços do modo de importação, consulte Autorizar apps do Chat.

Anexos

Seu app de chat pode enviar anexos usando a API Chat. Para saber mais sobre os métodos de recurso e os tipos de suporte à autenticação nos espaços do modo de importação, consulte Autorizar apps do Chat. No entanto, recomendamos o uso da API Google Drive para fazer upload de anexos como arquivos do Google Drive e vincular os URIs de arquivo às respectivas mensagens nos espaços do modo de importação para importar anexos de outras plataformas de mensagens e evitar atingir o limite interno do Google Chat para upload de anexos.

Associações históricas

As assinaturas históricas são assinaturas criadas para usuários que já saíram da entidade do espaço original da plataforma de mensagens de origem, mas que você quer manter os dados no Chat. Para saber como adicionar novos participantes depois que o espaço não estiver mais no modo de importação, consulte Criar um recurso de associação.

Em muitos casos, quando esses membros históricos estão sujeitos a uma política de retenção de dados no Google, você quer preservar os dados (como mensagens e reações) criados por membros anteriores em um espaço antes de importá-los para o Chat. Enquanto o espaço estiver no modo de importação, você poderá importar essas associações históricas para o espaço usando o método create no recurso Membership. Para preservar o tempo de saída da assinatura histórica, defina o deleteTime dela. Esse tempo de saída precisa ser preciso porque ele impacta quais dados são retidos para esses planos. Além disso, o deleteTime precisa ser posterior ao carimbo de data/hora de criação do espaço e não pode ser um carimbo de data/hora futuro.

Além de deleteTime, você também pode definir createTime para preservar o horário de inscrição original da associação histórica. Ao contrário de deleteTime, o createTime é opcional. Se não for definido, o createTime será calculado automaticamente subtraindo 1 microssegundo de deleteTime. Se definido, createTime precisa estar antes de deleteTime e precisa estar no momento ou depois do horário de criação do espaço. Essas informações do createTime não são usadas para determinar a retenção de dados e não ficam visíveis em ferramentas de administrador, como o Google Admin Console e o Google Vault.

Embora um usuário possa entrar e sair de um espaço de várias maneiras na plataforma de mensagens de origem (por convites, participação própria, adição por outro usuário), no Chat, essas ações são representadas pelos campos históricos de associação createTime e deleteTime como adição ou remoção.

O exemplo a seguir mostra como criar uma associação histórica em um espaço de modo de importação:

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)

Substitua:

Importar recursos em um espaço externo

Só é possível criar um espaço externo com o modo de importação usando credenciais pertencentes a usuários da sua organização do Workspace. Isso se aplica apenas enquanto o espaço estiver no modo de importação. Quando o espaço concluir o modo de importação, os usuários externos poderão ser convidados para participar dos espaços importados (consulte a seção de acesso) e as credenciais deles poderão ser usadas para chamar a API Chat.

Validar recursos importados

O app do Chat pode ler e validar o conteúdo de um espaço do modo de importação chamando o método list no recurso Message. É possível ler os recursos Reaction e Attachment nos campos emojiReactionSummaries e attachment de qualquer mensagem retornada. Os apps de chat só podem chamar esse método em nome de um usuário por meio de falsificação de identidade. Para mais informações, consulte Autorizar apps do Chat.

O app de chat também pode ler mensagens individuais para validação chamando o método get no recurso Message. Os apps de chat só podem chamar esse método para ler as próprias mensagens usando a própria autoridade. Para mais informações, consulte Autorizar apps do Chat.

Os apps de chat também podem listar as assinaturas anteriores chamando o método list no recurso Membership. Depois que o espaço sai do modo de importação, o método list não expõe mais as assinaturas históricas. Os apps de chat só podem chamar esse método em nome de um usuário por meio de falsificação de identidade. Para mais informações, consulte Autorizar apps do Chat.

É possível ler as propriedades de um espaço do modo de importação chamando o método get no recurso Space. A resposta também terá o importModeExpireTime preenchido, para que você possa acompanhar adequadamente o período para concluir o processo de importação. Os apps de chat só podem chamar esse método usando a própria autoridade. Para mais informações, consulte Autorizar apps do Chat.

Conciliar as diferenças de recursos importados dos dados de origem

Se algum recurso importado não corresponder mais à entidade original da plataforma de mensagens de origem devido a mudanças na entidade original durante a importação, os apps de chat poderão chamar a API Chat para modificar o recurso de chat importado. Por exemplo, se um usuário editar uma mensagem na plataforma de mensagens de origem depois que ela foi criada no Chat, os apps do Chat poderão atualizar a mensagem importada para que ela reflita o conteúdo atual da mensagem original.

Mensagens

Para atualizar os campos com suporte em uma mensagem em um espaço do modo de importação, chame o método update no recurso Message. Os apps de chat só podem chamar esse método usando a mesma autoridade usada durante a criação inicial da mensagem. Se você usou a falsificação de identidade durante a criação inicial da mensagem, use o mesmo usuário falsificado para atualizar a mensagem.

Para excluir uma mensagem em um espaço do modo de importação, chame o método delete no recurso Message. As mensagens em um espaço no modo de importação não precisam ser excluídas pelo criador original e podem ser excluídas por qualquer usuário no domínio. Os apps de chat só podem excluir as próprias mensagens usando a própria autoridade. Para mais informações, consulte Autorizar apps do Chat.

Reações

Para excluir uma reação de uma mensagem em um espaço do modo de importação, use o método delete no recurso reactions. Para saber mais sobre os métodos de recurso e os tipos de suporte à autenticação nos espaços do modo de importação, consulte Autorizar apps do Chat.

Anexos

Para atualizar anexos de uma mensagem em um espaço do modo de importação, use o método upload no recurso media. Para informações sobre os métodos de recurso e os tipos de suporte de autenticação nos espaços do modo de importação, consulte Autorizar apps do Chat.

Associações históricas

Para excluir uma associação histórica em um espaço do modo de importação, use o método delete no recurso Membership. Depois que um espaço sai do modo de importação, o método delete não permite mais excluir assinaturas históricas.

Não é possível atualizar uma associação histórica em um espaço no modo de importação. Se você quiser corrigir uma associação histórica importada incorretamente, primeiro exclua ela e recrie enquanto o espaço ainda estiver no modo de importação.

Espaços

Para atualizar campos com suporte em um espaço de modo de importação, use o método patch no recurso spaces.

Para excluir um espaço do modo de importação, use o método delete no recurso spaces.

Para informações sobre os métodos de recurso e os tipos de suporte de autenticação nos espaços do modo de importação, consulte Autorizar apps do Chat.

Modo de importação completo

Antes de chamar o método completeImport, verifique se a validação e a reconciliação das diferenças de recursos foram concluídas. Sair do modo de importação é um processo irreversível e converte o espaço do modo de importação em um espaço comum. Não há um indicador no Chat que atribua esses espaços a uma importação de dados.

Anote a data e a hora em que você chamou completeImport, o nome do recurso do usuário que fez a chamada e a resposta retornada. Isso pode ser útil se você encontrar problemas e precisar investigá-los.

Para concluir o modo de importação e tornar o espaço acessível aos usuários, o app Chat pode chamar o método completeImport no recurso Space. Os apps de chat só podem chamar esse método em nome de um usuário por impersonação. Para mais informações, consulte Autorizar apps do Chat. O usuário falsificado é adicionado ao espaço como administrador quando o método é concluído. Esse método precisa ser chamado em até 90 dias após a chamada inicial do método create.space. Se você tentar chamar esse método após o período de 90 dias, a chamada vai resultar em falhas porque o espaço do modo de importação é excluído e não pode mais ser acessado pelo app Chat.

O usuário falsificado no método completeImport não precisa ser o criador do espaço.

Não chame completeImport muito próximo do importModeExpireTime, porque não podemos garantir que a solicitação chegue antes do importModeExpireTime, e pode haver conflitos com o processamento de dados em sistemas acionados no momento de expiração. Recomendamos chamar completeImport pelo menos 30 minutos antes de importModeExpireTime.

O exemplo a seguir mostra como concluir o modo de importação:

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)

Substitua:

Conceder acesso ao espaço após o modo de importação

Para dar aos usuários do Chat acesso ao espaço importado recentemente, os apps do Chat podem continuar usando o escopo chat.import e a falsificação de usuário em até 90 dias após a chamada inicial do método create.space() para fazer o seguinte:

Para usar esses métodos com o escopo chat.import, o usuário falsificado precisa ser um administrador de espaço.

Para espaços externos, o método create() de associação também permite convidar usuários de fora da sua organização do Workspace. Entenda todas as limitações conhecidas para usuários externos.

Solução de problemas

Se você tiver problemas ao importar espaços de chat, consulte os problemas a seguir para receber ajuda. Se você encontrar uma resposta de erro, anote-a (copie e cole o texto em um documento ou salve uma captura de tela) para referência futura e solução de problemas.

Quando um espaço é importado, CompleteImportSpace é concluído com um status de OK.

Não concluiu a importação antes do período de 90 dias expirar

Conforme descrito anteriormente em Criar um espaço no modo de importação, se o espaço ainda estiver no modo de importação após 90 dias a partir do momento em que o método de criação foi chamado, ele será excluído automaticamente e ficará inacessível e irrecuperável.

Infelizmente, o espaço excluído não está mais disponível ou recuperável, e o processo de importação precisa ser iniciado novamente.

Encontrar espaços ausentes

Se você não encontrar o novo espaço do Chat, consulte a tabela a seguir para conferir a resposta que recebeu de CompleteImportSpace e a explicação e a solução.

Resposta recebida Etapas da investigação Explicação Resolução
CompleteImportSpace gera uma exceção, e chamar GetSpace retorna PERMISSION_DENIED. Verifique seus registros para saber quando o espaço foi criado. Se ele tiver mais de 90 dias, ele foi excluído automaticamente. Além disso, não há registro do espaço importado na ferramenta de gerenciamento de espaço ou no registro de auditoria. Já se passaram mais de 90 dias desde o início do processo de importação e o espaço não conseguiu sair da migração. Crie um novo espaço e execute o processo de importação novamente.
CompleteImportSpace retorna OK, e chamar GetSpace retorna PERMISSION_DENIED. Não há registro do espaço importado na ferramenta de gerenciamento de espaço, mas o espaço aparece como excluído no registro de auditoria. O espaço foi importado, mas excluído em seguida. Crie um novo espaço e execute o processo de importação novamente.