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

  1. Esamina i limiti di utilizzo delle API e pianifica in anticipo.
  2. Configura l'autorizzazione per l'app Chat.
  3. Creare uno spazio in modalità di importazione.
  4. Importa le risorse.
  5. Convalida le risorse importate.
  6. Riconciliazione delle differenze tra le risorse importate e i dati di origine.
  7. Modalità di importazione completa.
  8. Crea risorse di abbonamento.

Prerequisiti

Apps Script

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:

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:

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:

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.