Importar dados para o Google Chat

Com a API Google Chat, você pode importar dados de outras plataformas de mensagens para o Google Chat. É possível importar mensagens, anexos, reações, assinaturas e entidades de espaço das outras plataformas de mensagens para os recursos da API Chat correspondentes. É possível importar esses dados criando espaços do Chat no modo de importação e importando dados para eles.

Esta é uma visão geral das etapas envolvidas na importação de dados usando um espaço do modo de importação:

  1. Confira os limites de uso da API e planeje com antecedência.
  2. Configurar a autorização para o app do Chat.
  3. Criar um espaço no modo de importação.
  4. Importar recursos.
  5. Valide os recursos importados.
  6. Reconciliar diferenças de recursos importadas dos dados de origem.
  7. Concluir o modo de importação.
  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 na 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 delegada em qualquer domínio em que o app importe conteúdo. Consulte Autorizar apps do Chat.

Revise 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. Analise os limites de uso do seu 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, é possível definir o createTime do espaço. Esse createTime precisa ser definido como um valor entre 1o de janeiro de 2000 e o momento atual.

Anote o name do espaço criado para 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, concluir 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á automaticamente excluído e ficará inacessível e irrecuperável pelo app do Chat. Planeje com antecedência analisando os limites de uso do seu app do Chat para garantir que todos os recursos programados possam ser importados para o Chat dentro desse período.

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: '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ê está representando com a 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, 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 da qual você está migrando.

Mensagens

Os 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 é definido como a conta de usuário personificada. Para saber mais, consulte Autorizar apps de 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, defina o createTime da mensagem. Esse createTime precisa ser definido como um valor entre o horário de criação do espaço definido anteriormente e o horário atual.

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 nos 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 contenham menções do usuário.

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 do Chat pode importar reações a mensagens usando a API Chat. Para saber mais sobre os métodos de recurso e tipos de suporte de autenticação em espaços do modo de importação, consulte Autorizar apps de chat.

Anexos

Seu app do Chat pode fazer upload de anexos usando a API Chat. Para saber mais sobre os métodos de recurso e tipos de suporte de autenticação em espaços do modo de importação, consulte Autorizar apps de chat.

Histórico de associações

Associações históricas são aquelas criadas para usuários que já deixaram a 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 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, é recomendável preservar os dados (como mensagens e reações) criados por 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 ele usando o método create no recurso Membership. Para preservar o horário de saída da associação histórica, é preciso definir o deleteTime da associação. Esse tempo de licença precisa ser preciso, porque afeta quais dados 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 futuro.

Além de deleteTime, também é possível definir createTime para preservar o horário de mesclagem original da associação histórica. Ao contrário de deleteTime, o createTime é opcional. Se não for definida, 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 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, mesclando-se por conta própria, sendo adicionado por outro usuário), no Chat, todas 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 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

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 de qualquer campo emojiReactionSummaries e attachment de mensagem retornada. Os apps de chat só podem chamar esse método em nome de um usuário por meio de representação. Para mais informações, consulte Autorizar apps de chat.

O 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 saber mais, consulte Autorizar apps de chat.

Os apps de chat também podem listar as 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 associações 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 saber mais, consulte Autorizar apps de chat.

Para ler as propriedades de um espaço no modo de importação, chame o método get no recurso Space. Os apps de chat só podem chamar esse método usando a própria autoridade. Para saber mais, consulte Autorizar apps de chat.

Reconciliar diferenças de recursos importadas 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 de chat importado. Por exemplo, se um usuário editar uma mensagem na plataforma de origem depois que ela foi criada no Chat, os apps do Chat podem atualizar a mensagem importada para que ela reflita o conteúdo atual da mensagem original.

Mensagens

Para atualizar campos compatíveis 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 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, utilize a mesma persona 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 do modo de importação não precisam ser excluídas pelo criador original e podem ser excluídas falsificando a identidade de qualquer usuário no domínio. Os apps de chat só podem excluir as próprias mensagens usando a própria autoridade. Para saber mais, consulte Autorizar apps de chat.

Reações

Para excluir uma reação a uma mensagem em um espaço no modo de importação, use o método delete no recurso reactions. Para saber mais sobre os métodos de recurso e tipos de suporte de autenticação em espaços do modo de importação, consulte Autorizar apps de 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 saber mais sobre os métodos de recurso e tipos de suporte de autenticação em espaços do modo de importação, consulte Autorizar apps de 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 associações 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, será necessário excluí-la primeiro e depois recriá-la 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 do modo de importação, use o método delete no recurso spaces.

Para saber mais sobre os métodos de recurso e tipos de suporte de autenticação em espaços do modo de importação, consulte Autorizar apps de chat.

Concluir o modo de importação

Antes de chamar o método completeImport, verifique se a validação e a reconciliação de 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.

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 usando a personificação. Para saber mais, consulte Autorizar apps de chat. O usuário representado é adicionado ao espaço como administrador do espaço quando esse método é concluído. Esse método precisa ser chamado em até 30 dias após a chamada inicial do método create.space. Se você tentar chamar esse método depois de 30 dias, a chamada vai resultar em falhas, 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 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:

Criar recursos de assinatura

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

Após o período de 30 dias, os apps de chat vão exigir outros escopos de assinatura para chamar esse método.

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