Importare dati in Google Chat

Con l'API Google Chat, puoi importare i dati da altre piattaforme di messaggistica in Google Chat. Puoi importare messaggi, allegati, reazioni, abbonamenti 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. Al termine del processo, questi spazi diventano spazi di Chat standard.

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

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 installarli o aggiornarli, 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, vedi Creare un'app di Google Chat.

  • Autorizzazione configurata per l'app Chat. All'app Chat deve essere delegata l'autorità a livello di dominio in tutti i domini in cui l'app importa i contenuti. Vedi Autorizzare le app di Chat.

Rivedi i limiti di utilizzo delle API e pianifica 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 esaminando 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 tempistica stimata.

Crea uno spazio in modalità di importazione

Per creare uno spazio in modalità di importazione, chiama il metodo create sulla risorsa Space e imposta importMode su true. Per mantenere l'ora di creazione dell'entità dello spazio equivalente dalla piattaforma di messaggistica di origine, puoi impostare createTime dello spazio. createTime deve essere impostato su un valore compreso tra il 1° gennaio 2000 e la data odierna.

Prendi nota di name dello spazio che crei in modo da potervi fare riferimento nei passaggi successivi durante l'importazione dei contenuti nello spazio.

Dal momento della chiamata del metodo create, le app di Chat hanno 30 giorni di tempo per importare risorse nello spazio, per completare la modalità di importazione e per creare risorse di appartenenza utilizzando l'ambitochat.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 e non sarà più accessibile e non recuperabile. 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 di cui stai impersonando un'autorità a livello di dominio.

Importa risorse

Per importare risorse da altre piattaforme di messaggistica, crea risorse di Google Chat (ad esempio 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 esegui la migrazione.

Messaggi

Le app di chat possono importare messaggi utilizzando la propria autorità o per conto di un utente tramite furto d'identità. (l'autore del messaggio è impostato sull'account utente con identità). Per maggiori informazioni, 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 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 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:

Reazioni

L'app Chat può importare le reazioni ai 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 ed evitare di raggiungere il limite interno di Google Chat per il caricamento degli allegati.

Cronologia abbonamenti

Le iscrizioni storiche sono iscrizioni create per gli utenti che avevano già lasciato l'entità dello spazio originale dalla piattaforma di messaggistica di origine, ma vuoi conservare i propri 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 la cronologia dei membri è soggetta a criteri di conservazione dei dati in Google, è opportuno conservare i dati (ad esempio i messaggi e le reazioni) creati dalle iscrizioni storiche a uno spazio prima di importarli in Chat. Mentre lo spazio è in modalità di importazione, puoi importare le appartenenze storiche nello spazio utilizzando il metodo create nella risorsa Membership. Per mantenere il tempo di riposo dell'abbonamento storico, devi impostare il deleteTime dell'abbonamento. Il tempo di uscita deve essere preciso 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 impostare anche createTime per preservare la data di iscrizione originale dell'abbonamento storico. A differenza di deleteTime, createTime è facoltativo. Se non viene configurato, il valore createTime viene calcolato automaticamente sottraendo 1 microsecondo da deleteTime. Se impostato, createTime deve essere precedente a deleteTime e deve essere corrispondente o successiva alla data di creazione dello spazio. Queste informazioni su 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 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.

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 Chat può leggere 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 per conto di un utente solo tramite impersonificazione. 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 maggiori informazioni, vedi Autorizzare le app di Chat.

Le app di chat possono anche elencare le iscrizioni storiche chiamando il metodo list nella risorsa Membership. Quando lo spazio esce dalla modalità di importazione, il metodo list non espone più gli abbonamenti storici. Le app di chat possono chiamare questo metodo solo per conto dell'utente tramite impersonificazione. Per maggiori informazioni, vedi Autorizzare le app di Chat.

Puoi leggere le proprietà di uno spazio in modalità di importazione chiamando il metodo get sulla risorsa Space. Le app di chat possono chiamare questo metodo soltanto utilizzando la propria autorità. Per maggiori informazioni, vedi Autorizzare le app di Chat.

Riconciliazione delle 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 la sua creazione 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 la simulazione dell'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 sulla risorsa Message. I messaggi in uno spazio in modalità di importazione non devono essere eliminati dall'autore originale del messaggio e possono essere eliminati simulando l'identità di un utente nel dominio. Le app di chat possono eliminare i propri messaggi solo utilizzando la loro autorità. Per maggiori informazioni, vedi 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, 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 nella risorsa media. Per informazioni sui metodi delle risorse e sui tipi di autenticazione supportati negli spazi in modalità di importazione, vedi Autorizzare le app di chat.

Cronologia abbonamenti

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'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, vedi 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 da uno spazio fuori dalla modalità di importazione è un processo irreversibile e converte lo spazio della modalità di importazione in uno spazio normale. In Chat non c'è indicatore 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 per conto di un utente solo tramite il furto d'identità. Per maggiori informazioni, 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 al metodo create.space. Se tenti di chiamare questo metodo una volta trascorsi i 30 giorni, la chiamata genera errori perché lo spazio in modalità di importazione viene eliminato e non è più accessibile all'app Chat.

L'utente impersonato nel metodo completeImport non deve essere necessariamente 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:

Crea risorse di appartenenza

Per aggiungere iscrizioni utente per uno spazio che ha completato la modalità di importazione, chiama il metodo create sulla risorsa Membership. Le app di chat possono continuare a utilizzare l'ambito chat.import e la simulazione dell'identità dell'utente per chiamare questo metodo entro 30 giorni dalla chiamata iniziale al 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 per l'abbonamento immediatamente dopo il completamento dell'importazione, in modo che le app di chat possano continuare a utilizzare l'ambito chat.import per la creazione delle iscrizioni e per fornire a tutti i membri l'accesso allo spazio importato.