Con l'API Google Chat, puoi importare i dati dalle altre piattaforme di messaggistica in Google Chat. Puoi importare messaggi, allegati, reazioni, membri ed entità spaziali 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 al loro interno.
Di seguito è riportata una panoramica dei passaggi necessari per importare i dati utilizzando uno spazio in modalità di importazione:
- Esamina i limiti di utilizzo delle API e pianifica in anticipo.
- Configura l'autorizzazione per l'app Chat.
- Creare uno spazio in modalità di importazione.
- Importa le risorse.
- Convalida le risorse importate.
- Riconciliazione delle differenze tra le risorse importate e i dati di origine.
- Modalità di importazione completa.
- Crea risorse di abbonamento.
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 installarle o aggiornarle, 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, consulta Creare un'app Google Chat.
Autorizzazione configurata per l'app Chat. L'app Chat deve essere un'autorità con delega a livello di dominio in tutti i domini in cui l'app importa contenuti. Consulta Autorizzare le app di Chat.
Esaminare i limiti di utilizzo delle API e pianificare 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 controllando 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 stima del tempo.
Creare uno spazio in modalità di importazione
Per creare uno spazio in modalità di importazione, chiama il metodo create
nella risorsa Space
e imposta importMode
su true
. Per preservare la data e l'ora di creazione dell'entità dello spazio equivalente dalla piattaforma di messaggistica di origine, puoi impostare il valore createTime
dello spazio. Questo valore createTime
deve essere impostato su un valore compreso tra
il 1° gennaio 2000 e l'ora attuale.
Prendi nota del name
dello spazio che crei in modo da poter fare riferimento nei passaggi successivi durante l'importazione di contenuti nello spazio.
Dal momento in cui viene chiamato il metodo create
, le app di Chat hanno
30 giorni di tempo per
importare risorse
nello spazio,
completare la modalità di importazione
e
creare risorse di appartenenza utilizzando l'ambito
chat.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, non sarà accessibile e non sarà recuperabile dall'app Chat. 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 che stai impersonando con autorità a livello di dominio.
Importa risorse
Per importare risorse da altre piattaforme di messaggistica, puoi creare risorse di Google Chat (ad esempio messaggi, reazioni, allegati) nello spazio in modalità di importazione. Quando crei una risorsa nello spazio, specifichi i dati della risorsa correlata dalla piattaforma di messaggistica da cui esegui la migrazione.
Messaggi
Le tue app di chat possono importare i messaggi utilizzando la propria autorità o per conto di un utente mediante furto d'identità. (l'autore del messaggio è impostato
sull'account utente con la figura dell'identità). Per maggiori informazioni, consulta
Autorizzare le app di chat.
Per importare un messaggio in uno spazio in modalità di importazione, chiama il metodo create
nella risorsa Message
.
Per preservare la data e l'ora di creazione del messaggio originale dalla piattaforma di messaggistica di origine, puoi impostare il 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 ad alcun 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 rubando l'autorità a livello di dominio.SPACE_NAME
: il nome dello spazio creato in modalità di importazione.
Reazioni
L'app Chat può importare reazioni per i messaggi utilizzando l'API Chat. Per informazioni sui metodi delle risorse e sui tipi di supporto dell'autenticazione negli spazi in modalità di importazione, consulta Autorizzare le app di Chat.
Allegati
La tua 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, consulta Autorizzare le app di Chat.
Abbonamenti storici
Gli abbonamenti storici sono abbonamenti creati per gli utenti che avevano già lasciato l'entità dello spazio originale dalla piattaforma di messaggistica di origine, ma vuoi conservare i loro dati in Chat. Per informazioni su come aggiungere nuovi membri quando lo spazio non è più in modalità di importazione, consulta Creare una risorsa di appartenenza.
In molti casi, quando i membri della cronologia sono soggetti a
criteri di conservazione dei dati di Google,
vuoi conservare i dati (ad esempio Messaggi e reazioni) creati dagli
abbonamenti storici a uno spazio prima di importarli in Chat.
Mentre lo spazio è in modalità di importazione, puoi importare gli abbonamenti storici nello spazio utilizzando il metodo create
nella risorsa Membership
.
Per conservare il periodo di interruzione dell'abbonamento storico, devi impostare
il valore deleteTime
dell'abbonamento. Il periodo di interruzione deve essere corretto 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 anche impostare createTime
per preservare la
data di iscrizione originale dell'abbonamento storico. A differenza di deleteTime
, il createTime
è facoltativo. Se non viene configurato, il valore createTime
viene calcolato automaticamente sottraendo 1 microsecondo da deleteTime
. Se impostato, il valore createTime
deve essere precedente a
deleteTime
e corrispondere o essere successiva all'ora di creazione dello spazio. Queste informazioni createTime
non vengono utilizzate per determinare la conservazione dei dati e non sono visibili in
strumenti di amministrazione come la Console di amministrazione Google e Google Vault.
Sebbene un utente possa partecipare a uno spazio e abbandonarlo nella piattaforma di messaggistica di origine in più modi (tramite inviti, la partecipazione autonomamente o l'aggiunta da parte di un altro utente), in Chat queste azioni sono tutte rappresentate dai campi della cronologia delle iscrizioni createTime
e deleteTime
come aggiunte o rimosse.
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 rubando l'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 di Chat può rileggere 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 solo per conto di un utente tramite il furto d'identità. Per saperne di più, consulta Autorizzare le app di Chat.
L'app Chat può anche leggere singoli messaggi per la convalida chiamando il metodo get
nella risorsa Message
.
Le app di chat possono chiamare questo metodo solo per leggere i propri messaggi
usando la propria autorità. Per maggiori informazioni, consulta
Autorizzare le app di chat.
Le app di chat possono anche elencare la cronologia degli abbonamenti chiamando il metodo list
nella risorsa Membership
.
Dopo che lo spazio esce dalla modalità di importazione, il metodo list
non mostra più gli abbonamenti storici. Le app di chat possono chiamare questo metodo
solo per conto di un utente tramite furto d'identità. Per maggiori informazioni, consulta
Autorizzare le app di chat.
Puoi leggere le proprietà di uno spazio in modalità di importazione chiamando il metodo get
nella risorsa Space
.
Le app di chat possono chiamare questo metodo solo utilizzando la propria autorità.
Per maggiori informazioni, consulta
Autorizzare le app di chat.
Riconciliare le differenze tra le risorse importate e i 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 di 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 che il messaggio è stato creato in Chat, le app di Chat possono aggiornare il messaggio importato in modo che rifletta i contenuti attuali 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 il furto d'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
nella risorsa Message
.
I messaggi in uno spazio in modalità di importazione non devono essere eliminati dall'autore originale dei messaggi e possono essere eliminati impersonando qualsiasi utente del dominio.
Le app di chat possono eliminare solo i propri messaggi
usando la propria autorevolezza. Per maggiori informazioni, consulta
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, consulta 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, consulta Autorizzare le app di Chat.
Abbonamenti storici
Per eliminare un'appartenenza storica a 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, consulta 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 tra risorse siano completate. L'uscita da uno spazio dalla modalità di importazione è un processo irreversibile e converte lo spazio in modalità di importazione in uno spazio normale. Non esiste un indicatore in Chat 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 solo per conto di un utente tramite il furto d'identità. Per maggiori informazioni, consulta
Autorizzare le app di chat.
Al termine di questo metodo, l'utente impersonato viene aggiunto allo spazio come gestore dello spazio. Questo metodo deve essere chiamato entro 30 giorni dalla
chiamata al metodo create.space
iniziale. Se tenti di chiamare questo metodo una volta trascorso il periodo di 30 giorni, la chiamata restituirà un errore perché lo spazio in modalità di importazione viene eliminato e non è più accessibile per l'app Chat.
Non è necessario che l'utente impersonato nel metodo completeImport
sia il creatore dello spazio.
Nell'esempio seguente viene illustrato 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 rubando l'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
nella risorsa Membership
.
Le app di chat possono continuare a utilizzare l'ambito chat.import
e il furto d'identità dell'utente per chiamare questo metodo entro 30 giorni dalla chiamata iniziale del 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 di iscrizione
subito dopo il completamento dell'importazione, in modo che le app di chat possano
continuare a utilizzare l'ambito chat.import
per la creazione di iscrizioni e
fornire a tutti i membri l'accesso allo spazio importato.