Riferimento al connettore Gmail

Questa pagina contiene materiale di riferimento per il connettore Gmail in Databricks Lakeflow Connect.

Importante

Questa funzionalità è in versione beta. Gli amministratori dell'area di lavoro possono controllare l'accesso a questa funzionalità dalla pagina Anteprime . Vedere Gestire le anteprime di Azure Databricks.

Comportamento generale del connettore

  • Il connettore è di sola lettura. Parla solo con https://gmail.googleapis.com e usa il https://www.googleapis.com/auth/gmail.readonly telescopio di default. Non modifica mai la casella di sorgente.
  • Ogni connessione assume una singola cassetta postale. Il connettore timbra il valore della cassetta postale come mailbox colonna su ogni riga. Per ingerire più di una cassetta postale, crea una connessione e una pipeline separate per ogni cassetta postale.
  • Lo schema sorgente è default.
  • Le messages tabelle e message_labels si sincronizzano in modo incrementale usando l'API Cronologia di Gmail. Le profiletabelle , labels, labels_details, drafts, e filters sono solo a aggiornamento completo.
  • Gli allegati dei messaggi sono contenuti nella messagespayload colonna (payload.parts[].body.attachmentId). Non esiste una tabella di accessori separata.

Tabelle supportate

Il connettore assume le seguenti tabelle dallo default schema sorgente.

Tabella Chiave primaria Modalità di sincronizzazione
profile emailAddress Aggiornamento completo
labels mailbox, id Aggiornamento completo
labels_details mailbox, id Aggiornamento completo
drafts id Aggiornamento completo
filters id Aggiornamento completo
messages id Incrementale (API Storia Gmail, historyId)
message_labels message_id Incrementale (API Storia Gmail, historyId)

Schema di destinazione

Le sezioni seguenti descrivono le colonne in ciascuna tabella di destinazione.

profile

Column Type
emailAddress string (chiave primaria)
messagesTotal long
threadsTotal long
historyId string
mailbox string

labels

Column Type
mailbox string (chiave primaria)
id string (chiave primaria)
name string
messageListVisibility string
labelListVisibility string
type string
messagesTotal long
messagesUnread long
threadsTotal long
threadsUnread long
color struct{textColor: string, backgroundColor: string}

labels_details

La labels_details tabella ha le stesse colonne di labels (mailbox, id, name, type, i campi di visibilità, i conteggi di messaggi e thread, e color). Ogni etichetta è arricchita con la risposta dell'API labels.get .

Bozze

Column Type
id string (chiave primaria)
message struct{id: string, threadId: string}
mailbox string

filters

Column Type
id string (chiave primaria)
criteria struct{from: string, to: string, subject: string, query: string, negatedQuery: string, hasAttachment: boolean, excludeChats: boolean, size: long, sizeComparison: string}
action struct{addLabelIds: array<string>, removeLabelIds: array<string>, forward: string}
mailbox string

messages

Column Type
id string (chiave primaria)
threadId string
snippet string
historyId string
internalDate string
payload struct (vedi struttura del carico utile)
sizeEstimate long
mailbox string
_ingestion_timestamp timestamp
_row_deleted boolean
_row_truncated boolean

Struttura del carico utile

La payload colonna materializza l'albero MIME del messaggio fino a 8 livelli di annidamento. Ogni livello ha la seguente struttura:

struct{
  partId: string,
  mimeType: string,
  filename: string,
  headers: array<struct{name: string, value: string}>,
  body: struct{attachmentId: string, size: long, data: string},
  parts: array<payload>
}

Gli allegamenti sono contenuti all'interno payload.parts[].body.attachmentIddi . Le parti annidate a più di 8 livelli di profondità non vengono espanse in colonne di struttura.

message_labels

Column Type
message_id string (chiave primaria)
threadId string
labelIds array<string>
mailbox string
_ingestion_timestamp timestamp
_row_deleted boolean
_row_truncated boolean

Sincronizzazione incrementale

Le messages tabelle e message_labels si sincronizzano in modo incrementale:

  • La prima prova effettua un bootstrap crawl completo della cassetta postale.
  • Le run successive richiedono users.history.list, inserito sul historyId cursore preso dalla profile risorsa, per recuperare solo i cambiamenti dalla run precedente.
  • Le cancellazioni vengono emesse come _row_deleted lapidi.
  • Se Gmail scade la memoria historyId memorizzata (l'API Storia restituisce un 404 perché il cursore è più vecchio della finestra di conservazione di Gmail), il connettore torna automaticamente a un aggiornamento completo della tabella interessata.

Importante

Gmail conserva la cronologia per una finestra limitata, tipicamente di circa sette giorni. Programma la pipeline per farla funzionare almeno una volta ogni sette giorni in modo che lo stoccaggio historyId rimanga entro quella finestra. Se il cursore scade, la successiva esecuzione effettua un aggiornamento completo di messages e message_labels.

Le messages tabelle e message_labels non supportano il tracciamento della cronologia SCD Tipo 2; configurare SCD Tipo 2 per queste tabelle causa il guasto della validazione della pipeline.

Limitazione del tasso

Quando Gmail restituisce una risposta HTTP 403, il connettore legge l'intestazione Retry-After (con un minimo di 1 secondo di ritardo) e ritenta automaticamente la richiesta.

  • Last updated on