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.
- Analise os limites de uso da API e planeje com antecedência.
- Configure a autorização para o app do Chat.
- Criar um espaço no modo de importação.
- Importar recursos.
- Validar recursos importados
- Reconciliar as diferenças de recursos importados dos dados de origem.
- Modo de importação completo.
- Conceder acesso ao espaço após o modo de importação.
Pré-requisitos
Apps Script
- Uma conta do Google Workspace com acesso ao Google Chat.
- Um app do Chat publicado. Para criar um app do Chat, siga este quickstart.
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.
Após a chamada do método create
, os apps do Chat têm
30 dias para
importar recursos
para o espaço, completar o modo de importação e
conceder acesso ao espaç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:
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 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:
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.
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:
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.
Conceder acesso ao espaço após o modo de importação
Para conceder 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
de usuário 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 recursoMembership
. Recomendamos que os apps do Chat criem recursosMembership
imediatamente após a conclusão da importação do espaço para que eles possam continuar usando o escopochat.import
e garantir que todos os membros importados tenham acesso ao espaço. - Definir um público-alvo: chame o
método
update()
no recursoSpace
. 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.