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, 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:

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

Prerequisiti

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 metodo spaces.create(). Quando si utilizza la modalità di importazione, il campo createTime può essere impostato sul timestamp storico in cui lo spazio è stato creato nell'origine per preservare la data e l'ora di creazione originali.
• 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:

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 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:

"""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:

"""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:

"""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 risorsa Membership. Consigliamo alle app di Chat di creare risorse Membership subito dopo il completamento dell'importazione dello spazio, in modo che le app di Chat possano continuare a utilizzare l'ambito chat.import e che tutti i membri importati abbiano accesso allo spazio.
• Imposta un pubblico di destinazione: chiama il metodo update() sulla risorsa Space. 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.