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. Após a conclusão do processo, esses espaços se tornam 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 do Chat
3. Criar um espaço no modo de importação
4. Importar recursos
5. Validar 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

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 saiba quais tipos de espaços do Chat são aceitos ao importar para um novo espaç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.

Identificar os espaços que podem ser importados

O modo de importação só oferece suporte às SpaceType de SPACE e GROUP_CHAT. Ele não é compatível com DIRECT_MESSAGE. Consulte a documentação de 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: o modo de importação precisa ser concluído em até 30 dias. Se o espaço ainda estiver no modo de importação após 30 dias a partir do momento em que o método spaces.create() foi chamado, ele será excluído automaticamente e ficará inacessível e irrecuperável.
  • Não use o valor do campo createTime para acompanhar a expiração do período de 30 dias. Isso nem 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 abaixo mostra como criar um espaço no modo de importação:

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)

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. Esse createTime precisa ser definido como um valor entre o horário de criação do espaço que você definiu 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 do modo de importação não podem renderizar 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:

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

• EMAIL: o endereço de e-mail da conta de usuário que você está representando com autoridade em todo o domínio.
• SPACE_NAME: o nome do espaço criado no modo de importação.

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

O 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 enviar 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 o envio 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 informações sobre como adicionar novos membros depois que o espaço não estiver mais no modo de importação, consulte Criar recurso de assinatura.

Em muitos casos, quando esses membros anteriores estão sujeitos a uma política de retenção de dados no Google, é necessário 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 está no modo de importação, é possível importar essas associações históricas para o espaço usando o método create no recurso Membership. Para preservar o horário de licença da associação histórica, você precisa definir o deleteTime da assinatura. Esse tempo de saída precisa ser preciso porque ele impacta quais dados serã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 após a 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:

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

• EMAIL: o endereço de e-mail da conta de usuário que você está falsificando com autoridade em todo o domínio.
• SPACE_NAME: o nome do espaço criado no modo de importação.
• USER_ID: o ID exclusivo do usuário.

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 recursos Reaction e Attachment dos 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 do Chat também podem listar associações históricas 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 de modo de importação chamando o método get no recurso Space. 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 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 de modo de importação não precisam ser excluídas pelo criador original da mensagem e podem ser excluídas se passando 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 para 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.

Histórico de associações

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 saber mais sobre os métodos de recursos e os tipos de suporte à autenticação em espaços do modo de importação, consulte Autorizar apps do Chat.

Concluir modo de importação

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 de um espaço do modo de importação é um processo irreversível e converte o espaço do modo de importação em um espaço normal. 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 meio de falsificação de identidade. 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 dentro de 30 dias da chamada inicial do método create.space. Se você tentar chamar esse método após 30 dias, a chamada vai falhar porque o espaço do modo de importação será excluído e não poderá mais ser acessado pelo app do Chat.

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

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

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

• EMAIL: o endereço de e-mail da conta de usuário que você está falsificando com autoridade em todo o domínio.
• SPACE_NAME: o nome do espaço criado no modo de importação.

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é 30 dias após a chamada inicial do método create.space() para fazer o seguinte:

• Adicionar participantes ao espaço: chame o método create() no recurso Membership. Recomendamos que os apps do Chat criem recursos Membership imediatamente após a importação do espaço ser concluída, para que os apps do Chat continuem usando o escopo chat.import e garantir que todos os membros importados tenham acesso ao espaço.
• Definir um público-alvo: chame o método update() no recurso Space. Para saber como criar e adicionar públicos-alvo, consulte Tornar um espaço do Google Chat detectável para usuários específicos em uma organização do Google Workspace.

Para usar esses métodos com o escopo chat.import, o usuário representado precisa ser um administrador do 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 e solução de problemas futuros.

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

A importação não foi concluída antes do prazo de 30 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 30 dias após a chamada do método de criação, ele será excluído automaticamente e se tornará 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.