Con l'API Google Chat, puoi importare i dati dalle altre piattaforme di messaggistica in Google Chat. Puoi importare messaggi, allegati, reazioni, appartenenza e entità dello spazio esistenti dalle altre piattaforme di messaggistica alle corrispondente risorse dell'API Chat. Puoi importare questi dati creando spazi di Chat in modalità di importazione e importando i dati in questi spazi. Una volta completato con successo il processo, questi spazi diventano spazi di Chat standard.
Di seguito viene descritta la procedura di importazione completa:
- Pianificare l'importazione
- Configurare l'autorizzazione per l'app Chat
- Creare uno spazio in modalità di importazione
- Importare le risorse
- Convalidare le risorse importate
- Riconciliazione delle differenze delle risorse importate dai dati di origine
- Modalità di importazione completa
- Concedere l'accesso allo spazio dopo la modalità di importazione
- Risoluzione dei problemi
Prerequisiti
Apps Script
- Un account Google Workspace Business o Enterprise con accesso a Google Chat.
- Crea un progetto Google Cloud.
- Attiva e configura l'API Google Chat con un nome, un'icona e una descrizione per la tua app di chat.
- Crea un progetto Apps Script autonomo e attiva il servizio Chat avanzato.
- All'app Chat deve essere delegata l'autorità a livello di dominio in tutti i domini in cui l'app importa contenuti. Consulta Autorizzare le app di Chat.
Python
- Un account Google Workspace Business o Enterprise con accesso a Google Chat.
- Crea un progetto Google Cloud.
- Abilita e configura l'API Google Chat con un nome, un'icona e una descrizione per l'app Chat.
- Python 3.6 o versioni successive
- Lo strumento di gestione dei pacchetti pip
- All'app Chat deve essere delegata l'autorità a livello di dominio in tutti i domini in cui l'app importa contenuti. Consulta Autorizzare le app di Chat.
Pianifica l'importazione
Pianifica di conseguenza la quantità di dati da importare, comprendi in che modo i limiti e le quote di utilizzo possono influire sul processo di importazione e tieni presente i tipi di spazi di Chat supportati durante l'importazione in un nuovo spazio.
Esamina i limiti di utilizzo dell'API
Il tempo necessario per importare i dati in Chat può variare notevolmente in base alla quantità di risorse di Chat da importare. Esamina i limiti di utilizzo della tua app Chat e la quantità di dati pianificati per l'importazione dalla piattaforma di messaggistica di origine per determinare una tempistica stimata.
Quando importi i messaggi in uno spazio, ti consigliamo di distribuire le chiamate al metodo messages.create()
su diversi thread di messaggi.
Identifica gli spazi supportati da importare
La modalità di importazione supporta solo il SpaceType
di SPACE
e GROUP_CHAT
. Non supporta DIRECT_MESSAGE
.
Per ulteriori informazioni, consulta la documentazione relativa a SpaceType
.
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
.
Quando crei lo spazio in modalità di importazione, tieni presente quanto segue.
- Data e ora: ricorda che la modalità di importazione deve essere completata entro 30 giorni. Se lo spazio è ancora in modalità di importazione dopo 30 giorni dalla chiamata del metodo
spaces.create()
, viene eliminato automaticamente e diventa inaccessibile e non recuperabile.- Non utilizzare il valore del campo
createTime
per monitorare la scadenza del periodo di 30 giorni. Questo non è sempre uguale a quando chiami il metodospaces.create()
. Quando si utilizza la modalità di importazione, il campocreateTime
può essere impostato sul timestamp storico in cui lo spazio è stato creato nell'origine per preservare la data e l'ora di creazione originali.
- Non utilizzare il valore del campo
- Nome della risorsa dello spazio (
name
): l'identificatore univoco utilizzato per recuperare informazioni sullo spazio specifico e a cui viene fatto riferimento nei passaggi successivi durante l'importazione dei contenuti nello spazio.
Per conservare la data e l'ora di creazione dell'entità dello spazio equivalente dalla piattaforma di messaggistica di origine, puoi impostare il createTime
dello spazio. createTime
deve essere impostato su un valore compreso tra il 1° gennaio 2000 e la data odierna.
Per creare uno spazio esterno in modalità di importazione, imposta externalUserAllowed
su true
.
Una volta completata l'importazione, puoi aggiungere utenti esterni.
Il seguente esempio mostra come creare uno spazio in modalità di importazione:
Apps Script
function createSpaceInImportMode() {
const space = Chat.Spaces.create({
spaceType: 'SPACE',
displayName: 'DISPLAY_NAME',
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': 'DISPLAY_NAME',
'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 usurpi l'identità con autorità a livello di dominio.DISPLAY_NAME
: il nome dello spazio creato in modalità di importazione. Deve essere un nome univoco per lo spazio visualizzato agli utenti di Chat. Ti consigliamo di utilizzare lo stesso nome visualizzato dello spazio da cui stai importando i dati.
Importa risorse
Per importare risorse da altre piattaforme di messaggistica, crea risorse di Google Chat (come messaggi, reazioni, allegati) nello spazio in 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 tue app di Chat possono importare i messaggi utilizzando la propria autorità o per conto di un utente tramite furto d'identità. L'autore del messaggio è impostato sull'account utente impersonato. Per saperne di più, 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 valore createTime
deve essere impostato su un valore compreso tra la data e l'ora di creazione dello spazio impostate in precedenza e l'ora corrente.
I messaggi nello stesso spazio non possono contenere lo stesso createTime
, anche se
vengono eliminati i messaggi precedenti con quell'intervallo di tempo.
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 o 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 di cui stai usurpando l'identità con 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, 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, in modo da evitare di raggiungere il limite interno di Google Chat per il caricamento degli allegati.
Abbonamenti storici
Le abbonamenti storici sono abbonamenti creati per gli utenti che avevano già abbandonato la entità dello spazio originale dalla piattaforma di messaggistica di origine, ma che vuoi mantenere i loro 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 questi membri storici sono soggetti a norme sulla conservazione dei dati in Google, è consigliabile conservare i dati (ad esempio Messaggi e reazioni) creati dagli abbonamenti storici in uno spazio prima di importarli in Chat.
Quando lo spazio è in modalità di importazione, puoi importare le iscrizioni storiche
in questo spazio utilizzando il
metodo create
nella
risorsa Membership
.
Per conservare la data di recesso dell'abbonamento storico, devi impostare il deleteTime
dell'abbonamento. Questa data deve essere accurata 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 conservare la data di iscrizione originale dell'abbonamento storico. A differenza di deleteTime
, il valore createTime
è facoltativo. Se non è impostato, createTime
viene calcolato automaticamente sottraendo 1 microsecondo da deleteTime
. Se impostato, createTime
deve precederedeleteTime
e deve essere uguale o successiva all'ora di creazione dello spazio. Queste createTime
informazioni 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.
Il seguente esempio 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 di cui stai usurpando l'identità con autorità a livello di dominio.SPACE_NAME
: il nome dello spazio creato in modalità di importazione.USER_ID
: l'ID univoco dell'utente.
Importare risorse in uno spazio esterno
Puoi creare uno spazio esterno con la modalità di importazione solo utilizzando le credenziali appartenente agli utenti all'interno della tua organizzazione Workspace. Questo vale solo mentre lo spazio è in modalità di importazione. Una volta che lo spazio ha completato la modalità di importazione, gli utenti esterni possono essere invitati a partecipare agli spazi importati (vedi la sezione Accesso) e le loro credenziali possono essere utilizzate per chiamare l'API Chat.
Convalida le risorse importate
L'app Chat può leggere e convalidare i contenuti di uno spazio in modalità di importazione chiamando il metodo list
sulla 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 furto d'identità. 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 saperne di più, vedi
Autorizzare le app di Chat.
Le app di chat possono anche elencare gli abbonamenti storici chiamando il
metodo list
nella
risorsa Membership
.
Una volta che lo spazio esce dalla modalità di importazione, il metodo list
non mostra più le iscrizioni storiche. Le app di chat possono chiamare questo metodo per conto di un utente solo tramite furto d'identità. Per saperne di più, vedi
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 saperne di più, vedi
Autorizzare le app di Chat.
Riconciliare le 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 che è stato creato in Chat, le app Chat possono aggiornare il messaggio importato in modo che rifletta i contenuti attuali del messaggio originale.
Messaggi
Per aggiornare
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 l'inganno d'identità dell'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 del messaggio e possono essere eliminati rubando l'identità di qualsiasi utente del dominio.
Le app di chat possono eliminare i loro messaggi solo
utilizzando la loro autorità. Per saperne di più, vedi
Autorizzare le app di Chat.
Reazioni
Per eliminare una reazione a 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
sulla 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 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 abbonamento storico 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
sulla risorsa spaces
.
Per eliminare uno spazio in modalità di importazione, utilizza il
metodo delete
sulla risorsa spaces
.
Per informazioni sui metodi delle risorse e sui tipi di autenticazione supportati 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 delle risorse siano completate. L'uscita dalla modalità di importazione di uno spazio è un processo irreversibile e consente di convertire lo spazio in modalità di importazione in uno spazio normale. In Chat non è presente alcun indicatore che attribuisca questi spazi a un'importazione di dati.
Prendi nota della data e dell'ora in cui chiami completeImport
, del nome della risorsa
dell'utente che ha effettuato la chiamata e della risposta restituita. Questa opzione può essere utile se riscontri problemi e devi esaminarli.
Per completare la modalità di importazione e rendere lo spazio accessibile agli utenti, l'app Chat può chiamare il metodo completeImport
sulla risorsa Space
.
Le app di chat possono chiamare questo metodo per conto di un utente solo tramite rappresentazione. Per saperne di più, 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 del metodo create.space
. Se provi a chiamare questo metodo dopo il termine della durata di 30 giorni, la chiamata non va a buon fine perché lo spazio in modalità di importazione viene eliminato e non è più accessibile all'app Chat.
L'utente impersonato nel metodo completeImport
non deve necessariamente essere 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.
Concedere l'accesso allo spazio dopo la modalità di importazione
Per consentire agli utenti di Chat di accedere allo spazio importato di recente,
le app di Chat possono continuare a utilizzare l'ambito chat.import
e l'usurpazione di identità degli utenti entro 30 giorni dalla chiamata iniziale del metodo create.space()
per eseguire
quanto segue:
- Aggiungi membri allo spazio: chiama il metodo
create()
sulla risorsaMembership
. Consigliamo alle app di Chat di creare risorseMembership
subito dopo il completamento dell'importazione dello spazio, in modo che le app di Chat possano continuare a utilizzare l'ambitochat.import
e che tutti i membri importati abbiano accesso allo spazio. - Imposta un pubblico di destinazione: chiama il
metodo
update()
sulla risorsaSpace
. Per scoprire come creare e aggiungere segmenti di pubblico di destinazione, consulta Rendere uno spazio di Google Chat rilevabile per utenti specifici in un'organizzazione Google Workspace.
Per utilizzare questi metodi con l'ambito chat.import
, l'utente impersonato deve essere un gestore dello spazio.
Per gli spazi esterni, il metodo di appartenenza
create()
consente anche di invitare utenti esterni all'organizzazione Workspace. Assicurati di conoscere tutte le limitazioni note per gli utenti esterni.
Risoluzione dei problemi
Se riscontri un problema durante l'importazione degli spazi di Chat, consulta i seguenti problemi per ricevere assistenza. Se ricevi una risposta di errore, annotala (copia/incolla il testo in un documento o salva uno screenshot) per riferimento futuro e risoluzione dei problemi.
Quando uno spazio viene importato correttamente, CompleteImportSpace
viene completato con lo stato OK
.
Non hai completato l'importazione prima della scadenza del periodo di 30 giorni
Come descritto in precedenza in Creare uno spazio in modalità di importazione, se lo spazio è ancora in modalità di importazione dopo 30 giorni dal momento in cui è stato chiamato il metodo di creazione, viene eliminato automaticamente e diventa inaccessibile e non recuperabile.
Purtroppo, lo spazio eliminato non è più disponibile o recuperabile e il processo di importazione deve essere riavviato.
Trovare gli spazi mancanti
Se non riesci a trovare il nuovo spazio di Chat, consulta la
tabella seguente per la risposta che hai ricevuto da CompleteImportSpace
per
vedere la spiegazione e come risolverlo.
Risposta ricevuta | Passaggi dell'indagine | Spiegazione | Risoluzione |
---|---|---|---|
CompleteImportSpace genera un'eccezione e la chiamata a
GetSpace restituisce PERMISSION_DENIED . |
Controlla nei tuoi record quando è stato creato lo spazio e, se è più vecchio di 30 giorni, è stato eliminato automaticamente. Inoltre, nello strumento di gestione dello spazio o nell'audit log non è presente alcun record dello spazio importato. | Sono trascorsi più di 30 giorni dall'avvio del processo di importazione e non è stato possibile uscire dalla migrazione dello spazio. | Crea un nuovo spazio ed esegui di nuovo la procedura di importazione. |
CompleteImportSpace restituisce OK e la chiamata
GetSpace restituisce PERMISSION_DENIED . |
Non è presente alcun record dello spazio importato nello strumento di gestione dello spazio, ma lo spazio viene visualizzato come eliminato nel log di controllo. | Lo spazio è stato importato correttamente, ma successivamente è stato eliminato. | Crea un nuovo spazio ed esegui di nuovo il processo di importazione. |