Importare dati in Google Chat

Con l'API Google Chat, puoi importare i dati dalle altre piattaforme di messaggistica in Google Chat. Puoi importare messaggi, allegati, reazioni, iscrizioni 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. Una volta completato con successo il processo, questi spazi diventano spazi di Chat standard.

Di seguito è descritta la procedura di importazione completa:

1. Pianificare l'importazione
2. Configurare l'autorizzazione per l'app Chat
3. Creare uno spazio in modalità di importazione
4. Importare risorse
5. Convalidare le risorse importate
6. Riconciliare le differenze tra le risorse importate e i dati di origine
7. Modalità di importazione completa
8. Concedere l'accesso allo spazio dopo la modalità di importazione
9. Risoluzione dei problemi

Prerequisiti

Pianificare l'importazione

Pianifica di conseguenza la quantità di dati da importare, comprendi in che modo i limiti di utilizzo e le quote possono influire sul processo di importazione e tieni presente i tipi di spazi di Chat supportati durante l'importazione in un nuovo spazio. Se sei un amministratore, leggi Importare i dati dei messaggi in Google Chat da un altro servizio e segui attentamente i passaggi.

Esaminare i limiti di utilizzo dell'API

Il tempo necessario per importare i dati in Chat può variare notevolmente a seconda della quantità di risorse di Chat da importare. Esamina i limiti di utilizzo dell'app Chat e la quantità di dati pianificati per l'importazione dalla piattaforma di messaggistica di origine per determinare una cronologia stimata.

Quando importi messaggi in uno spazio, ti consigliamo di distribuire le chiamate al metodo messages.create() in thread di messaggi diversi.

Identifica gli spazi supportati da importare

La modalità di importazione supporta solo 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 90 giorni. Se lo spazio è ancora in modalità di importazione dopo 90 giorni dalla chiamata del metodo spaces.create(), viene eliminato automaticamente e diventa inaccessibile e non recuperabile.
  • Utilizza il valore del campo importModeExpireTime per monitorare la scadenza del periodo di 90 giorni.
  • Non utilizzare il valore del campo createTime per monitorare la scadenza del periodo di 90 giorni. Non sempre è uguale a quando chiami il metodo spaces.create(). Quando utilizzi la modalità di importazione, il campo createTime può essere impostato sul timestamp storico in cui è stato creato lo spazio nell'origine per preservare l'ora di creazione originale.
• Il nome della risorsa spazio (name): l'identificatore univoco utilizzato per recuperare informazioni sullo spazio specifico e a cui si fa riferimento nei passaggi successivi durante l'importazione di contenuti nello spazio.

Per conservare l'ora di creazione dell'entità spazio equivalente dalla piattaforma di messaggistica di origine, puoi impostare createTime dello spazio. Questo createTime deve essere impostato su un valore compreso tra il 1° gennaio 2000 e il momento attuale.

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:

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);
}

"""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 che stai rappresentando con l'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 dagli utenti di Chat. Ti consigliamo di utilizzare lo stesso nome visualizzato dello spazio da cui importi i dati.

Importazione delle risorse

Per importare risorse da altre piattaforme di messaggistica, devi creare risorse di Google Chat (come 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 stai eseguendo la migrazione.

Messaggi

Le tue app di chat possono importare i messaggi utilizzando la propria autorità o per conto di un utente tramite l'impersonificazione. L'autore del messaggio è impostato sull'account utente rappresentato. 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 preservare 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 che hai impostato 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 eseguire il rendering delle 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 di utenti.

L'esempio seguente mostra come creare un messaggio in uno spazio in modalità di importazione:

"""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 rappresentando con l'autorità a livello di dominio.
• SPACE_NAME: il nome dello spazio creato in modalità di importazione.

Reazioni

La tua app di chat può importare reazioni ai messaggi utilizzando l'API Chat. Per informazioni sui metodi e sui tipi di autenticazione delle risorse supportati negli spazi in modalità di importazione, vedi Autorizzare le app di Chat.

Allegati

La tua app di chat può caricare allegati utilizzando l'API Chat. Per informazioni sui metodi e sui tipi di autenticazione delle risorse supportati 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 della 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.

Abbonamenti storici

Le iscrizioni storiche sono iscrizioni create per utenti che avevano già abbandonato l'entità spazio originale della piattaforma di messaggistica di origine, ma vuoi conservare i loro dati in Chat. Per informazioni sull'aggiunta di nuovi membri dopo che lo spazio non è più in modalità di importazione, vedi Creare una risorsa di appartenenza.

In molti casi, quando questi membri storici sono soggetti a una norma di conservazione dei dati in Google, vuoi conservare i dati (come messaggi e reazioni) creati dalle iscrizioni storiche in uno spazio prima di importarli in Chat. Mentre lo spazio è in modalità di importazione, puoi importare queste iscrizioni storiche nello spazio utilizzando il metodo create nella risorsa Membership. Per conservare il tempo di assenza dell'abbonamento storico, devi impostare il deleteTime dell'abbonamento. Questo periodo di assenza deve essere accurato perché influisce sui dati da conservare per questi 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 conservare l'ora di iscrizione originale dell'abbonamento storico. A differenza di deleteTime, il createTime è facoltativo. Se non è impostato, createTime viene calcolato automaticamente sottraendo 1 microsecondo da deleteTime. Se impostato, createTime deve essere precedente a deleteTime e deve essere uguale o successivo all'ora di creazione dello spazio. Queste informazioni 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 un utente possa entrare e uscire da uno spazio in diversi modi nella piattaforma di messaggistica di origine (tramite inviti, partecipazione autonoma, aggiunta da parte di un altro utente), in Chat queste azioni sono tutte rappresentate dai campi createTime e deleteTime relativi all'appartenenza storica come aggiunta o rimozione.

Il seguente esempio mostra come creare un'iscrizione storica in uno spazio in modalità di importazione:

"""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 rappresentando con l'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 appartenenti a utenti all'interno della tua organizzazione Workspace. Questo vale solo mentre lo spazio è in modalità di importazione. Una volta che lo spazio completa la modalità di importazione, gli utenti esterni possono essere invitati a partecipare agli spazi importati (vedi la sezione di accesso) e le loro credenziali possono essere utilizzate per chiamare l'API Chat.

Convalida delle risorse importate

La tua 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 solo per conto di un utente tramite rappresentazione. Per maggiori informazioni, vedi Autorizzare le app di chat.

La tua app Chat può anche leggere i 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 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. Dopo che lo spazio esce dalla modalità di importazione, il metodo list non espone più le iscrizioni storiche. Le app di chat possono chiamare questo metodo solo per conto di un utente tramite rappresentazione. Per saperne di più, vedi Autorizzare le app di chat.

Puoi leggere le proprietà di uno spazio della modalità di importazione chiamando il metodo get nella risorsa Space. La risposta conterrà anche importModeExpireTime in modo da poter monitorare correttamente l'intervallo di tempo per completare il processo di importazione. 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 tra le risorse importate e i dati di origine

Se una risorsa importata non corrisponde più all'entità originale della piattaforma di messaggistica di origine a causa di modifiche apportate all'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 è stato creato 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 l'impersonificazione dell'utente durante la creazione del messaggio iniziale, 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 dal creatore del messaggio originale e possono essere eliminati impersonando qualsiasi utente del dominio. Le app di chat possono eliminare solo i propri messaggi utilizzando la propria 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 e sui tipi di autenticazione delle risorse supportati 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 e sui tipi di autenticazione delle risorse supportati negli spazi in modalità di importazione, vedi Autorizzare le app di Chat.

Abbonamenti storici

Per eliminare un'iscrizione storica in uno spazio in modalità di importazione, utilizza il metodo delete nella risorsa Membership. Dopo che uno spazio esce dalla modalità di importazione, il metodo delete non ti consente più di eliminare le iscrizioni storiche.

Non puoi aggiornare un abbonamento storico in uno spazio in modalità di importazione. Se vuoi correggere un abbonamento storico importato in modo errato, devi prima eliminarlo e poi ricrearlo mentre lo spazio è ancora in modalità di importazione.

Spazi

Per aggiornare i campi supportati in uno spazio con modalità di importazione, utilizza il metodo patch nella risorsa spaces.

Per eliminare uno spazio della 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.

Modalità di importazione completa

Prima di chiamare il metodo completeImport, devi assicurarti che la convalida e il riconciliamento delle differenze tra le risorse siano completati. L'uscita di uno spazio dalla modalità di importazione è un processo irreversibile e converte lo spazio in modalità di importazione in uno spazio normale. Non è presente alcun indicatore in Chat 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. Può essere utile se devi risolvere eventuali problemi.

Per completare la modalità di importazione e rendere lo spazio accessibile agli utenti, l'app di Chat può chiamare il metodo completeImport sulla risorsa Space. Le app di chat possono chiamare questo metodo solo per conto di un utente tramite l'impersonificazione. Per saperne di più, vedi Autorizzare le app di chat. L'utente rappresentato viene aggiunto allo spazio come gestore dello spazio al termine di questo metodo. Questo metodo deve essere chiamato entro 90 giorni dalla chiamata iniziale al metodo create.space. Se tenti di chiamare questo metodo dopo che sono trascorsi 90 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 rappresentato nel metodo completeImport non deve essere il creatore dello spazio.

Non chiamare completeImport troppo vicino alla data di importModeExpireTime, in quanto non possiamo garantire che la richiesta arrivi prima di importModeExpireTime e potrebbero verificarsi conflitti con l'elaborazione dei dati nei sistemi attivati al momento della scadenza. Ti consigliamo di chiamare il numero completeImport almeno 30 minuti prima delle importModeExpireTime.

Il seguente esempio mostra come completare la modalità di importazione:

"""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 rappresentando con l'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'imitazione dell'utente entro 90 giorni dalla chiamata iniziale al metodo create.space() per eseguire le seguenti operazioni:

• Aggiungi membri allo spazio: chiama il metodo create() sulla risorsa Membership. Consigliamo alle app di Chat di creare risorse Membership immediatamente dopo il completamento dell'importazione dello spazio, in modo che le app di Chat possano continuare a utilizzare l'ambito chat.import e garantire che tutti i membri importati abbiano accesso allo spazio. Ti consigliamo di dare la priorità all'aggiunta di membri che potrebbero essere soggetti al criterio di blocco di Vault, che consente la conservazione dei messaggi importati anche se non rientrano più nel periodo di conservazione.
• Imposta un pubblico di destinazione: chiama il metodo update() sulla risorsa Space. Per scoprire come creare e aggiungere segmenti di pubblico di destinazione, vedi Rendere rilevabile uno spazio Google Chat per utenti specifici in un'organizzazione Google Workspace.

Per utilizzare questi metodi con l'ambito chat.import, l'utente rappresentato deve essere un gestore dello spazio.

Per gli spazi esterni, il metodo di create() iscrizione consente anche di invitare utenti esterni all'organizzazione Workspace. Assicurati di comprendere 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, prendine nota (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 90 giorni

Come descritto in precedenza in Creare uno spazio in modalità di importazione, se lo spazio è ancora in modalità di importazione dopo 90 giorni dalla chiamata al metodo create, viene eliminato automaticamente e diventa inaccessibile e non recuperabile.

Purtroppo, lo spazio eliminato non è più disponibile o recuperabile e la procedura di importazione deve essere avviata di nuovo.

Se lo spazio non è stato importato perché contiene troppi dati da importare nella finestra di 90 giorni con gli attuali limiti di utilizzo, dividilo in due o più spazi più piccoli a scopo di archiviazione e avvia di nuovo la procedura di importazione.

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 risolvere il problema.