Gmail-Connector-Referenz

Diese Seite enthält Referenzmaterial für den Gmail-Connector in Databricks Lakeflow Connect.

Important

Dieses Feature befindet sich in der Betaversion. Arbeitsbereichsadministratoren können den Zugriff auf dieses Feature über die Vorschauseite steuern. Siehe Manage Azure Databricks Previews.

Allgemeines Verbinderverhalten

  • Der Verbinder ist schreibgeschützt. Standardmäßig spricht es nur mit https://gmail.googleapis.com und nutzt das https://www.googleapis.com/auth/gmail.readonly Zielfernrohr. Es verändert nie das Quellpostfach.
  • Jede Verbindung nimmt einen einzelnen Briefkasten auf. Der Verbinder stempelt den Briefkastenwert als Spalte mailbox in jeder Zeile. Um mehr als einen Postfach zu konsumieren, erstellen Sie für jede Mailbox eine separate Verbindung und Pipeline.
  • Das Quellschema ist default.
  • Die und message_labels die messages Tabellen synchronisieren sich schrittweise mit der Gmail History API. Die , labels, labels_details, , draftsund filters Tabellen profilesind ausschließlich bei vollständiger Aktualisierung.
  • Nachrichtenanhänge befinden sich in der messagespayload Tabellenspalte (payload.parts[].body.attachmentId). Es gibt keine separate Tabelle für Anhänge.

Unterstützte Tabellen

Der Connector speichert die folgenden Tabellen aus dem default Quellschema.

Tabelle Primärschlüssel Synchronisierungsmodus
profile emailAddress Vollständige Aktualisierung
labels mailbox, id Vollständige Aktualisierung
labels_details mailbox, id Vollständige Aktualisierung
drafts id Vollständige Aktualisierung
filters id Vollständige Aktualisierung
messages id Incremental (Gmail History API, historyId)
message_labels message_id Incremental (Gmail History API, historyId)

Zielschema

Die folgenden Abschnitte beschreiben die Spalten in jeder Zieltabelle.

profile

Column Typ
emailAddress string (Primärschlüssel)
messagesTotal long
threadsTotal long
historyId string
mailbox string

labels

Column Typ
mailbox string (Primärschlüssel)
id string (Primärschlüssel)
name string
messageListVisibility string
labelListVisibility string
type string
messagesTotal long
messagesUnread long
threadsTotal long
threadsUnread long
color struct{textColor: string, backgroundColor: string}

labels_details

Die Tabelle labels_details hat dieselben Spalten wie labels (mailbox, id, name, , type, die Sichtbarkeitsfelder, die Nachrichten- und Threadzählungen sowie color). Jedes Label wird mit der Antwort der labels.get API bereichert.

Entwürfe

Column Typ
id string (Primärschlüssel)
message struct{id: string, threadId: string}
mailbox string

Filter

Column Typ
id string (Primärschlüssel)
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 Typ
id string (Primärschlüssel)
threadId string
snippet string
historyId string
internalDate string
payload struct (siehe Nutzlaststruktur)
sizeEstimate long
mailbox string
_ingestion_timestamp timestamp
_row_deleted boolean
_row_truncated boolean

Nutzlaststruktur

Die Spalte payload materialisiert den MIME-Baum der Nachricht bis zu 8 Ebenen des Verschachtelns. Jedes Level hat folgende Struktur:

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

Anhänge sind in payload.parts[].body.attachmentIdenthalten. Teile, die mehr als 8 Ebenen tief verschachtelt sind, werden nicht zu Struktur-Säulen erweitert.

message_labels

Column Typ
message_id string (Primärschlüssel)
threadId string
labelIds array<string>
mailbox string
_ingestion_timestamp timestamp
_row_deleted boolean
_row_truncated boolean

Inkrementelle Synchronisierung

Die und message_labels Tabellen messages synchronisieren sich inkrementiell:

  • Der erste Durchlauf führt einen vollständigen Bootstrap-Crawl durch den Briefkasten durch.
  • Nachfolgende Durchläufe rufen users.history.list, auf dem historyId Cursor aus der Ressource profile aufgerufen, um nur die Änderungen seit dem vorherigen Durchlauf abzurufen.
  • Deletionen werden als _row_deleted Grabsteine ausgestrahlt.
  • Wenn Gmail das gespeicherte historyId Fenster abläuft (die History API gibt ein 404-Formular zurück, da der Cursor älter ist als das Speicherfenster von Gmail), fällt der Connector automatisch auf eine vollständige Aktualisierung der betroffenen Tabelle zurück.

Important

Gmail speichert die Geschichte für ein begrenztes Zeitfenster, typischerweise etwa sieben Tage. Plane die Pipeline so einmal, dass sie mindestens alle sieben Tage läuft, damit das gespeicherte historyId Formular innerhalb dieses Zeitfensters bleibt. Wenn der Cursor abläuft, führt der nächste Durchlauf eine vollständige Aktualisierung von messages und message_labelsdurch.

Die und message_labels Tabellen messages unterstützen keine SCD Type 2 History Tracking; die Konfiguration von SCD Type 2 für diese Tabellen führt dazu, dass die Pipeline-Validierung fehlschlägt.

Ratenbegrenzung

Wenn Gmail eine HTTP-403-Antwort zurückgibt, liest der Connector den Retry-After Header (mit mindestens 1 Sekunde Backoff) und versucht die Anfrage automatisch erneut.

  • Last updated on