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 das suas 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 com êxito, esses espaços se tornarão espaços padrão do Chat.

Confira a seguir o processo completo 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 recursos importados
6. Conciliar diferenças de recursos importados dos dados de origem
7. Modo de importação completa
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 de acordo com 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 compatíveis ao importar 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 a serem importados. Analise os limites de uso do app 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 conversas por mensagens.

Identificar 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 do 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 em 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 o vencimento do período de 90 dias.
  • Não use o valor do campo createTime para acompanhar o vencimento do período de 90 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 recuperar 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:

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á representando 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 é mostrado aos usuários do Chat. Recomendamos usar o mesmo nome de exibição do espaço de onde você está importando os 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 dados do recurso relacionado da plataforma de mensagens de onde está migrando.

Mensagens

Os apps do Chat podem importar mensagens usando a própria autoridade ou em nome de um usuário por representação. O autor da mensagem é definido como a conta de usuário representada. Para mais informações, consulte Autorizar apps do Chat. Para importar uma mensagem em um espaço no modo de importação, chame o método create no recurso Message. Para preservar o horário de criação da mensagem original na 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 que você definiu anteriormente e o horário atual.

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

As mensagens com URLs de terceiros em espaços no modo de importação não podem renderizar prévias 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 para 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 no 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

Seu app Chat pode importar reações para mensagens usando a API Chat. Para informações sobre os métodos de recursos e tipos de suporte de autenticação em espaços do modo de importação, consulte Autorizar apps do Chat.

Anexos

Seu app do Chat pode fazer upload de anexos usando a API Chat. Para informações sobre os métodos de recursos e tipos de suporte de autenticação em espaços do modo de importação, consulte Autorizar apps do Chat. No entanto, recomendamos usar a 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.

Assinaturas históricas

As associações históricas são criadas para usuários que já tinham saído da entidade de espaço original da plataforma de mensagens de origem, mas você quer reter os dados deles no Chat. Para informações sobre como adicionar novos participantes 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 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 assinaturas históricas 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 da assinatura. Esse horário precisa estar correto porque afeta os dados que serão retidos para essas assinaturas. Além disso, esse 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 horário original de entrada da assinatura 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 ser anterior a deleteTime e estar no horário de criação do espaço ou depois dele. Essas informações createTime não são usadas para determinar a retenção de dados e não ficam visíveis em ferramentas de administração, como o Google Admin Console e o Google Vault.

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

O exemplo a seguir mostra como criar uma associação histórica em um espaço no 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 de usuários da sua organização do Workspace. Isso só se aplica enquanto o espaço está no modo de importação. Quando o espaço sair do modo de importação, os usuários externos poderão ser convidados a 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

Seu app do Chat pode ler e validar o conteúdo de um espaço no 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 representação. Para mais informações, consulte Autorizar apps do Chat.

Seu app do 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 associações históricas. Os apps de chat só podem chamar esse método em nome de um usuário por representação. Para mais informações, consulte Autorizar apps do Chat.

Para ler as propriedades de um espaço no modo de importação, chame o método get no recurso Space. A resposta também terá importModeExpireTime preenchido para que você possa acompanhar corretamente o período necessário 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.

Reconciliar diferenças de recursos importados dos dados de origem

Se um 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 do 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 refletir o conteúdo atual da mensagem original.

Mensagens

Para atualizar os campos compatíveis em uma mensagem de um espaço no 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 que foi usada durante a criação da mensagem inicial. Se você usou a representação do usuário durante a criação da mensagem inicial, use o mesmo usuário representado para atualizar essa mensagem.

Para excluir uma mensagem em um espaço no 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 da mensagem 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 no modo de importação, use o método delete no recurso reactions. Para informações sobre os métodos de recursos e tipos de suporte de autenticação em espaços do modo de importação, consulte Autorizar apps do Chat.

Anexos

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

Assinaturas históricas

Para excluir uma associação histórica em um espaço no 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 associações 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 e depois recrie enquanto o espaço ainda estiver no modo de importação.

Espaços

Para atualizar os campos compatíveis em um espaço de modo de importação, use o método patch no recurso spaces.

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

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

Modo de importação completa

Antes de chamar o método completeImport, confira 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 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ê chama 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 representação. Para mais informações, consulte Autorizar apps do Chat. O usuário representado é adicionado ao espaço como um administrador do espaço quando esse 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 falhar porque o espaço no modo de importação será excluído e não estará mais acessível ao app Chat.

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

Não chame completeImport muito perto de importModeExpireTime, porque não podemos garantir que a solicitação vai chegar antes de importModeExpireTime, e pode haver conflitos com o processamento de dados em sistemas acionados no horário de expiração. Recomendamos ligar para completeImport pelo menos 30 minutos antes de importModeExpireTime.

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á representando com autoridade em todo o domínio.
• SPACE_NAME: o nome do espaço criado no modo de importação.

Dar 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 representação do usuário em até 90 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 conclusão da importação do espaço. Assim, eles podem continuar usando o escopo chat.import e garantir que todos os membros importados tenham acesso ao espaço. Priorize a adição de membros que podem estar sujeitos à política de guarda do Vault, que permite a preservação de mensagens importadas mesmo que elas estejam fora do período de retençã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 representado precisa ser um gerente do espaço.

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

Solução de problemas

Se você tiver um problema ao importar espaços do Chat, consulte as questões a seguir para receber ajuda. Se você encontrar uma resposta de erro, anote (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 fim do período de 90 dias

Conforme descrito em Criar um espaço no modo de importação, se o espaço ainda estiver nesse modo após 90 dias da chamada do método de criação, ele será excluído automaticamente e ficará inacessível e irrecuperável.

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

Se o espaço não foi importado porque tem muitos dados para importar no período de 90 dias com os limites de uso atuais, divida o espaço em dois ou mais espaços menores para fins de arquivamento e inicie o processo de importação novamente.

Encontrar espaços ausentes

Se não for possível encontrar o novo espaço do Chat, consulte a tabela a seguir para ver a explicação e como resolver o problema de acordo com a resposta que você recebeu de CompleteImportSpace.