Importar dados para o Google Chat

Com a API Google Chat, é possível importar dados das suas outras plataformas de mensagens para o Google Chat. É possível importar mensagens, anexos, reações, assinaturas e entidades de espaço atuais de outras plataformas de mensagens para os 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 todo o processo de importação:

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

Planejar a importação

Planeje a quantidade de dados a ser importada, entenda como os limites e cotas de uso podem afetar o processo de importação e esteja ciente dos tipos de espaços do Chat compatíveis 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. Revise os limites de uso do app do 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 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.

• Data e hora: lembre-se de que o modo de importação precisa ser concluído em até 30 dias. Se o espaço ainda estiver no modo de importação 30 dias após o momento em que o método spaces.create() for chamado, ele será excluído automaticamente e ficará inacessível e irrecuperável.
  • Não use o valor do campo createTime para rastrear 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. Esse createTime precisa ser definido como um valor entre 1o de janeiro de 2000 e a data 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:

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 nome precisa ser exclusivo para o espaço que é exibido para os 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, você pode definir 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 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:

"""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á falsificando 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 do Chat pode fazer upload de 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, é altamente recomendável usar a API Google Drive para fazer upload de anexos como arquivos do Google Drive e vincular os URIs dos arquivos à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 associações históricas são criadas para usuários que já saíram da entidade original do espaço da plataforma de mensagens de origem, mas você quer reter 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 participaçã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 pelas associações históricas 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, também é possível definir createTime para preservar o tempo de junção original da associação histórica. Ao contrário de deleteTime, o createTime é opcional. Se não for definido, 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 possa haver várias maneiras de um usuário participar e sair de um espaço na plataforma de mensagens de origem (por convites, participando por conta própria ou sendo adicionado por outro usuário), no Chat essas ações são representadas pelos campos históricos de associação createTime e deleteTime à medida que são adicionadas ou removidas.

O exemplo a seguir mostra como criar uma associação histórica em um espaço do 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á representando 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 dentro da sua organização do Workspace. Isso só se aplica enquanto o espaço está 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 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. 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 alterações na entidade original durante a importação, os apps do 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 for criada no Chat, os apps do Chat poderão atualizar a mensagem importada para que ela reflita o conteúdo atual da 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 do 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á nenhum 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 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 a seguir 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 Deixar um espaço do Google Chat visí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 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/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 o status OK.

Não concluiu a importação antes do período 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 após 30 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.