Con l'API Google Chat, puoi importare i dati da altre piattaforme di messaggistica in Google Chat. Puoi importare messaggi, allegati, reazioni, abbonamenti ed entità dello spazio esistenti dalle altre piattaforme di messaggistica alle risorse dell'API Chat corrispondenti. Puoi importare questi dati creando spazi di Chat in modalità di importazione e importando i dati in questi spazi. Al termine del processo, questi spazi diventano spazi di Chat standard.
- Rivedi i limiti di utilizzo delle API e pianifica in anticipo.
- Configura l'autorizzazione per l'app Chat.
- Crea uno spazio in modalità di importazione.
- Importa risorse.
- Convalida le risorse importate.
- Riconciliazione delle differenze delle risorse importate dai dati di origine.
- Modalità di importazione completa.
- Crea risorse di iscrizione.
Prerequisiti
Apps Script
- Un account Google Workspace con accesso a Google Chat.
- Un'app di Chat pubblicata. Per creare un'app di Chat, segui questa quickstart.
Python
- Python 3.6 o versioni successive
- Lo strumento di gestione dei pacchetti pip
Le librerie client di Google più recenti per Python. Per installarli o aggiornarli, esegui questo comando nell'interfaccia a riga di comando:
pip3 install --upgrade google-api-python-client google-auth
Un'app di Chat pubblicata. Per creare e pubblicare un'app di Chat, vedi Creare un'app di Google Chat.
Autorizzazione configurata per l'app Chat. All'app Chat deve essere delegata l'autorità a livello di dominio in tutti i domini in cui l'app importa i contenuti. Vedi Autorizzare le app di Chat.
Rivedi i limiti di utilizzo delle API e pianifica in anticipo
Il tempo necessario per importare i dati in Chat può variare notevolmente a seconda della quantità di risorse di Chat da importare. Pianifica in anticipo esaminando i limiti di utilizzo dell'app di Chat e la quantità di dati pianificati per l'importazione dalla piattaforma di messaggistica di origine per determinare una tempistica stimata.
Crea uno spazio in modalità di importazione
Per creare uno spazio in modalità di importazione, chiama il metodo create
sulla risorsa Space
e imposta importMode
su true
. Per mantenere l'ora di creazione
dell'entità dello spazio equivalente dalla piattaforma di messaggistica di origine, puoi impostare
createTime
dello spazio. createTime
deve essere impostato su un valore compreso tra il 1° gennaio 2000 e la data odierna.
Prendi nota di name
dello spazio che crei in modo da potervi fare riferimento nei passaggi successivi durante l'importazione dei contenuti nello spazio.
Dal momento della chiamata del metodo create
, le app di Chat hanno
30 giorni di tempo per
importare risorse
nello spazio, per
completare la modalità di importazione
e per
creare risorse di appartenenza utilizzando
l'ambitochat.import
. Le app di chat possono comunque creare abbonamenti dopo 30 giorni con gli ambiti di appartenenza standard dell'API Chat.
Dopo 30 giorni, se lo spazio è ancora in modalità di importazione, viene
eliminato automaticamente e non sarà più accessibile e non recuperabile. Pianifica in anticipo esaminando i limiti di utilizzo dell'app Chat per assicurarti che tutte le risorse pianificate possano essere importate in Chat entro questo periodo di tempo.
L'esempio seguente mostra come creare uno spazio in modalità di importazione:
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)
Sostituisci quanto segue:
EMAIL
: l'indirizzo email dell'account utente di cui stai impersonando un'autorità a livello di dominio.
Importa risorse
Per importare risorse da altre piattaforme di messaggistica, crea risorse di Google Chat (ad esempio messaggi, reazioni, allegati) nello spazio della modalità di importazione. Quando crei una risorsa nello spazio, specifichi i dati della risorsa correlata della piattaforma di messaggistica da cui esegui la migrazione.
Messaggi
Le app di chat possono importare messaggi utilizzando la propria autorità o
per conto di un utente tramite furto d'identità. (l'autore del messaggio è impostato
sull'account utente con identità). Per maggiori informazioni, vedi Autorizzare le app di Chat.
Per importare un messaggio in uno spazio in modalità di importazione, chiama il metodo create
sulla risorsa Message
.
Per mantenere l'ora di creazione del messaggio originale dalla piattaforma di messaggistica di origine, puoi impostare il valore createTime
del messaggio. Questo createTime
deve essere impostato su un valore compreso tra l'ora di creazione dello spazio impostata in precedenza e l'ora attuale.
I messaggi nello stesso spazio non possono contenere lo stesso createTime
, anche se
i messaggi precedenti con quell'ora vengono eliminati.
I messaggi contenenti URL di terze parti negli spazi in modalità di importazione non possono visualizzare le anteprime dei link in Google Chat.
Quando crei i messaggi in modalità di importazione, gli spazi non inviano notifiche né inviano email a nessun utente, inclusi i messaggi che contengono menzioni degli utenti.
L'esempio seguente mostra come creare un messaggio in uno spazio in modalità di importazione:
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)
Sostituisci quanto segue:
EMAIL
: l'indirizzo email dell'account utente che stai impersonando con autorità a livello di dominio.SPACE_NAME
: il nome dello spazio creato in modalità di importazione.
Reazioni
L'app Chat può importare le reazioni ai messaggi utilizzando l'API Chat. Per informazioni sui metodi delle risorse e sui tipi di supporto dell'autenticazione negli spazi in modalità di importazione, vedi Autorizzare le app di Chat.
Allegati
L'app Chat può caricare allegati utilizzando l'API Chat. Per informazioni sui metodi delle risorse e sui tipi di supporto dell'autenticazione negli spazi in modalità di importazione, vedi Autorizzare le app di Chat. Tuttavia, ti consigliamo vivamente di utilizzare l'API Google Drive per caricare gli allegati come file di Google Drive e collegare gli URI dei file ai rispettivi messaggi negli spazi in modalità di importazione per importare gli allegati da altre piattaforme di messaggistica ed evitare di raggiungere il limite interno di Google Chat per il caricamento degli allegati.
Cronologia abbonamenti
Le iscrizioni storiche sono iscrizioni create per gli utenti che avevano già lasciato l'entità dello spazio originale dalla piattaforma di messaggistica di origine, ma vuoi conservare i propri dati in Chat. Per informazioni sull'aggiunta di nuovi membri dopo che lo spazio non è più in modalità di importazione, consulta Creare una risorsa di appartenenza.
In molti casi, quando la cronologia dei membri è soggetta a criteri di conservazione dei dati in Google, è opportuno conservare i dati (ad esempio i messaggi e le reazioni) creati dalle iscrizioni storiche a uno spazio prima di importarli in Chat.
Mentre lo spazio è in modalità di importazione, puoi importare le appartenenze storiche
nello spazio utilizzando il
metodo create
nella
risorsa Membership
.
Per mantenere il tempo di riposo dell'abbonamento storico, devi impostare
il deleteTime
dell'abbonamento. Il tempo di uscita deve essere preciso perché
influisce sui dati da conservare per gli abbonamenti. Inoltre, questo deleteTime
deve essere successivo al timestamp di creazione dello spazio e non deve essere un timestamp futuro.
Oltre a deleteTime
, puoi impostare anche createTime
per preservare la
data di iscrizione originale dell'abbonamento storico. A differenza di deleteTime
, createTime
è facoltativo. Se non viene configurato, il valore createTime
viene calcolato automaticamente
sottraendo 1 microsecondo da deleteTime
. Se impostato, createTime
deve essere precedente a
deleteTime
e deve essere corrispondente o successiva alla data di creazione dello spazio. Queste informazioni su createTime
non vengono utilizzate per determinare la conservazione dei dati e non sono visibili negli strumenti
di amministrazione come la Console di amministrazione Google e Google Vault.
Sebbene potrebbero esserci diversi modi in cui un utente può partecipare a uno spazio ed abbandonarlo
nella piattaforma di messaggistica di origine (tramite inviti, partecipazione da parte sua o aggiunta
da un altro utente), in Chat queste azioni sono tutte rappresentate dai campi
storici dell'appartenenza createTime
e deleteTime
come aggiunti
o rimossi.
L'esempio seguente mostra come creare un'appartenenza storica in uno spazio in modalità di importazione:
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)
Sostituisci quanto segue:
EMAIL
: l'indirizzo email dell'account utente che stai impersonando con autorità a livello di dominio.SPACE_NAME
: il nome dello spazio creato in modalità di importazione.USER_ID
: l'ID univoco dell'utente.
Convalida le risorse importate
L'app Chat può leggere e convalidare i contenuti
di uno spazio in modalità di importazione chiamando il
metodo list
nella
risorsa Message
.
Puoi leggere le risorse Reaction
e Attachment
dai campi emojiReactionSummaries
e attachment
di qualsiasi messaggio restituito. Le app di chat possono
chiamare questo metodo per conto di un utente solo tramite impersonificazione. Per maggiori
informazioni, vedi
Autorizzare le app di Chat.
L'app Chat può anche leggere i singoli messaggi per la convalida chiamando il metodo get
sulla risorsa Message
.
Le app di chat possono chiamare questo metodo solo per leggere i propri messaggi
utilizzando la propria autorità. Per maggiori informazioni, vedi Autorizzare le app di Chat.
Le app di chat possono anche elencare le iscrizioni storiche chiamando il
metodo list
nella
risorsa Membership
.
Quando lo spazio esce dalla modalità di importazione, il metodo list
non espone più
gli abbonamenti storici. Le app di chat possono chiamare questo metodo
solo per conto dell'utente tramite impersonificazione. Per maggiori informazioni, vedi Autorizzare le app di Chat.
Puoi leggere le proprietà di uno spazio in modalità di importazione chiamando il metodo get
sulla risorsa Space
.
Le app di chat possono chiamare questo metodo soltanto utilizzando la propria autorità.
Per maggiori informazioni, vedi Autorizzare le app di Chat.
Riconciliazione delle differenze delle risorse importate dai dati di origine
Se una risorsa importata non corrisponde più all'entità originale dalla piattaforma di messaggistica di origine a causa di modifiche nell'entità originale durante l'importazione, le app Chat possono chiamare l'API Chat per modificare la risorsa di chat importata. Ad esempio, se un utente modifica un messaggio nella piattaforma di messaggistica di origine dopo la sua creazione in Chat, le app di Chat possono aggiornare il messaggio importato in modo che rifletta il contenuto attuale del messaggio originale.
Messaggi
Per aggiornare i campi supportati in un messaggio in uno spazio in modalità di importazione, chiama il metodo update
nella risorsa Message
.
Le app di chat possono chiamare questo metodo solo utilizzando la stessa autorità
utilizzata durante la creazione iniziale del messaggio. Se hai utilizzato la simulazione dell'identità di un utente durante la creazione iniziale del messaggio, devi utilizzare lo stesso utente impersonato per aggiornare il messaggio.
Per eliminare un messaggio in uno spazio in modalità di importazione, chiama il metodo delete
sulla risorsa Message
.
I messaggi in uno spazio in modalità di importazione non devono essere eliminati dall'autore originale del messaggio e possono essere eliminati simulando l'identità di un utente nel dominio.
Le app di chat possono eliminare i propri messaggi solo
utilizzando la loro autorità. Per maggiori informazioni, vedi Autorizzare le app di Chat.
Reazioni
Per eliminare una reazione per un messaggio in uno spazio in modalità di importazione, utilizza il metodo delete
nella risorsa reactions
. Per informazioni sui metodi delle risorse e sui tipi di supporto dell'autenticazione negli spazi in modalità di importazione, vedi Autorizzare le app di Chat.
Allegati
Per aggiornare gli allegati di un messaggio in uno spazio in modalità di importazione, utilizza il metodo upload
nella risorsa media
. Per informazioni sui metodi delle risorse e sui tipi di autenticazione supportati negli spazi in modalità di importazione, vedi Autorizzare le app di chat.
Cronologia abbonamenti
Per eliminare un'appartenenza storica in uno spazio in modalità di importazione, utilizza il metodo delete
nella risorsa Membership
. Quando uno spazio esce dalla modalità di importazione, il metodo delete
non ti consente più di eliminare gli abbonamenti storici.
Non puoi aggiornare un'appartenenza storica in uno spazio in modalità di importazione. Se vuoi correggere un'appartenenza storica importata in modo errato, devi prima eliminarla e poi ricrearla mentre lo spazio è ancora in modalità di importazione.
Spaces
Per aggiornare i campi supportati in uno spazio in modalità di importazione, utilizza il metodo patch
nella risorsa spaces
.
Per eliminare uno spazio in modalità di importazione, utilizza il metodo delete
nella risorsa spaces
.
Per informazioni sui metodi delle risorse e sui tipi di supporto dell'autenticazione negli spazi in modalità di importazione, vedi Autorizzare le app di Chat.
Completa la modalità di importazione
Prima di chiamare il metodo completeImport
, devi assicurarti che la
convalida e la
riconciliazione delle differenze delle risorse
siano completate. L'uscita da uno spazio fuori dalla modalità di importazione è un processo irreversibile e
converte lo spazio della modalità di importazione in uno spazio normale. In Chat non c'è indicatore che attribuisca questi spazi a un'importazione dati.
Per completare la modalità di importazione e rendere lo spazio accessibile agli utenti, l'app Chat può chiamare il metodo completeImport
nella
risorsa Space
.
Le app di chat possono chiamare questo metodo per conto di un utente solo
tramite il furto d'identità. Per maggiori informazioni, vedi Autorizzare le app di Chat.
L'utente impersonato viene aggiunto allo spazio come gestore dello spazio al termine del metodo. Questo metodo deve essere chiamato entro 30 giorni dalla
chiamata iniziale al metodo create.space
. Se tenti di chiamare questo metodo una volta trascorsi i 30 giorni, la chiamata genera errori perché lo spazio in modalità di importazione viene eliminato e non è più accessibile all'app Chat.
L'utente impersonato nel metodo completeImport
non deve essere necessariamente il creatore dello spazio.
L'esempio seguente mostra come completare la modalità di importazione:
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)
Sostituisci quanto segue:
EMAIL
: l'indirizzo email dell'account utente che stai impersonando con autorità a livello di dominio.SPACE_NAME
: il nome dello spazio creato in modalità di importazione.
Crea risorse di appartenenza
Per aggiungere iscrizioni utente per uno spazio che ha completato la modalità di importazione, chiama il
metodo create
sulla
risorsa Membership
.
Le app di chat possono continuare a utilizzare l'ambito chat.import
e la simulazione dell'identità dell'utente per chiamare questo metodo entro 30 giorni dalla chiamata iniziale al metodo create.space
. L'utente impersonato deve essere un gestore dello spazio.
Una volta trascorso il periodo di 30 giorni, le app di Chat richiedono ambiti di appartenenza aggiuntivi per chiamare questo metodo.
Consigliamo alle app di Chat di creare risorse per l'abbonamento
immediatamente dopo il completamento dell'importazione, in modo che le app di chat possano
continuare a utilizzare l'ambito chat.import
per la creazione delle iscrizioni e per fornire
a tutti i membri l'accesso allo spazio importato.