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 existentes 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 dados para esses espaços. Após a conclusão do processo, esses espaços se tornam espaços padrão do Chat.

  1. Analise os limites de uso da API e planeje com antecedência.
  2. Configure 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 dos dados de origem.
  7. Modo de importação completo.
  8. Criar recursos de assinatura.

Pré-requisitos

Apps Script

Python

  • Python 3.6 ou superior
  • A ferramenta de gerenciamento de pacotes pip

  • As bibliotecas de cliente mais recentes do Google para Python. Para instalá-los ou atualizá-los, execute o seguinte comando em sua interface de linha de comando:

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

  • Um app do Chat publicado. Para criar e publicar um app do Chat, consulte Criar um app do Google Chat.

  • Autorização configurada para o app do Chat. O app do Chat precisa ter autoridade em todo o domínio em qualquer domínio em que o app importe conteúdo. Consulte Autorizar apps do Chat.

Analise os limites de uso da API e planeje com antecedência

O tempo necessário para importar dados para o Chat pode variar muito, dependendo da quantidade de recursos do Chat a serem importados. Planeje com antecedência analisando 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.

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. 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.

Anote o name do espaço que você criar para poder referenciá-lo nas etapas posteriores ao importar conteúdo para o espaço.

A partir do momento em que o método create é chamado, os apps do Chat têm 30 dias para importar recursos para o espaço, completar o modo de importação e criar recursos de associação usando o escopo chat.import. Os apps do Chat ainda podem criar associações após 30 dias com os escopos de associação padrão da API Chat. Após 30 dias, se o espaço ainda estiver no modo de importação, ele será excluído automaticamente e ficará inacessível e irrecuperável. Planeje com antecedência analisando os limites de uso do app do Chat para garantir que todos os recursos programados possam ser importados para o Chat nesse período.

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

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)

Substitua:

  • EMAIL: o endereço de e-mail da conta de usuário que você representa com autoridade em todo o domínio.

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

Seus apps do Chat podem importar mensagens usando a própria autoridade ou em nome de um usuário por falsificação de identidade. O autor da mensagem está definido como a conta de usuário personificada. Para mais informações, consulte Autorizar apps do Chat. Para importar uma mensagem em um espaço do 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 dela. 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 para os usuários, incluindo mensagens que contêm menções aos usuários.

O exemplo abaixo 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

Seu app do Chat pode importar reações para mensagens usando a API Chat. Para mais informações sobre os métodos de recursos e os tipos de suporte a 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 mais informações sobre os métodos de recursos e os tipos de suporte a autenticação em 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.

Histórico de associações

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 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 históricos 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 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. Essa hora de licença precisa ser precisa porque afeta quais dados reter para essas associações. 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 ser anterior a deleteTime e ser igual ou posterior ao horário de criação do espaço. Essas informações de createTime não são usadas para determinar a retenção de dados e não são 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 abaixo mostra como criar uma associação histórica em um espaço do 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:

Validar recursos importados

Seu 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.

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 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.

Reconciliar 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 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 campos compatíveis em uma mensagem em 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 com a mesma autoridade usada durante a criação da mensagem inicial. Se você usou a representação de 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 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 mais informações sobre os métodos de recursos e os tipos de suporte a 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 mais informações sobre os métodos de recursos e os tipos de suporte a autenticação em espaços do modo de importação, consulte Autorizar apps do Chat.

Histórico de associações

Para excluir uma assinatura 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, exclua-a primeiro e, em seguida, recrie-a enquanto o espaço ainda estiver no modo de importação.

Espaços

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

Para excluir um espaço de 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 de 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 estão 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á nenhum indicador no Chat que atribua esses espaços a uma importação de dados.

Para concluir o modo de importação e tornar o espaço acessível aos usuários, o app do 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 personificado é adicionado ao espaço como um administrador quando esse 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 representado no método completeImport não precisa ser o criador do espaço.

O exemplo abaixo 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:

Criar recursos de assinatura

Para adicionar associações de usuários a um espaço que concluiu o modo de importação, chame o método create no recurso Membership. Os apps do Chat podem continuar usando o escopo chat.import e a representação do usuário para chamar esse método até 30 dias após a chamada inicial do método create.space. Essa pessoa precisa ser administradora do espaço.

Após o período de 30 dias, os apps do Chat exigem escopos de associação adicionais para chamar esse método.

Recomendamos que os apps do Chat criem recursos de associação imediatamente após a conclusão da importação. Assim, eles podem continuar usando o escopo chat.import para criar associações e fornecer a todos os membros acesso ao espaço importado.