Référence du connecteur Gmail

Cette page contient des documents de référence pour le connecteur Gmail dans Databricks Lakeflow Connect.

info

Bêta

Cette fonctionnalité est en version bêta. Les administrateurs de Workspace peuvent contrôler l’accès à cette fonctionnalité depuis la page Aperçus . Consultez Gérer les aperçus Databricks.

Comportement général des connecteurs

• Le connecteur est en lecture seule. Il communique uniquement avec https://gmail.googleapis.com et utilise la portée https://www.googleapis.com/auth/gmail.readonly default. Il ne modifie jamais la boîte aux lettres source.
• Chaque connexion ingère une seule boîte aux lettres. Le connecteur marque la valeur de la boîte aux lettres en tant que colonne mailbox sur chaque ligne. Pour ingérer plus d'une boîte aux lettres, créez une connexion et un pipeline distincts pour chaque boîte aux lettres.
• Le schéma source est default.
• Les tables messages et message_labels se synchronisent de manière incrémentielle à l’aide de l’API Gmail History. Les tables profile, labels, labels_details, drafts et filters sont uniquement en full-refresh.
• Les pièces jointes des messages sont contenues dans la colonne payload de la table messages (payload.parts[].body.attachmentId). Il n’existe pas de table de pièces jointes distincte.

Tables prises en charge

Le connecteur ingère les tables suivantes à partir du schéma source default.

Table	Clé primaire	Mode de synchronisation
profile	emailAddress	refresh complète
labels	mailbox, id	refresh complète
labels_details	mailbox, id	refresh complète
drafts	id	refresh complète
filters	id	refresh complète
messages	id	Incrémentiel (Gmail History API, historyId)
message_labels	message_id	Incrémentiel (Gmail History API, historyId)

Table	Clé primaire	Mode de synchronisation
profile	emailAddress	refresh complète
labels	mailbox, id	refresh complète
labels_details	mailbox, id	refresh complète
drafts	id	refresh complète
filters	id	refresh complète
messages	id	Incrémentiel (Gmail History API, historyId)
message_labels	message_id	Incrémentiel (Gmail History API, historyId)

Schéma de destination

Les sections suivantes décrivent les colonnes de chaque table de destination.

profil

Colonne	Type
emailAddress	string (clé principale)
messagesTotal	long
threadsTotal	long
historyId	string
mailbox	string

Colonne	Type
emailAddress	string (clé principale)
messagesTotal	long
threadsTotal	long
historyId	string
mailbox	string

étiquettes

Colonne	Type
mailbox	string (clé principale)
id	string (clé principale)
name	string
messageListVisibility	string
labelListVisibility	string
type	string
messagesTotal	long
messagesUnread	long
threadsTotal	long
threadsUnread	long
color	struct{textColor: string, backgroundColor: string}

Colonne	Type
mailbox	string (clé principale)
id	string (clé principale)
name	string
messageListVisibility	string
labelListVisibility	string
type	string
messagesTotal	long
messagesUnread	long
threadsTotal	long
threadsUnread	long
color	struct{textColor: string, backgroundColor: string}

détails_des_étiquettes

La table labels_details possède les mêmes colonnes que labels (mailbox, id, name, type, les champs de visibilité, les nombres de messages et de fils de discussion, et color). Chaque étiquette est enrichie par la réponse de l’API labels.get.

brouillons

Colonne	Type
id	string (clé principale)
message	struct{id: string, threadId: string}
mailbox	string

Colonne	Type
id	string (clé principale)
message	struct{id: string, threadId: string}
mailbox	string

filtres

Colonne	Type
id	string (clé principale)
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

Colonne	Type
id	string (clé principale)
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

Colonne	Type
id	string (clé principale)
threadId	string
snippet	string
historyId	string
internalDate	string
payload	struct (voir la structure de la charge utile)
sizeEstimate	long
mailbox	string
_ingestion_timestamp	timestamp
_row_deleted	boolean
_row_truncated	boolean

Colonne	Type
id	string (clé principale)
threadId	string
snippet	string
historyId	string
internalDate	string
payload	struct (voir la structure de la charge utile)
sizeEstimate	long
mailbox	string
_ingestion_timestamp	timestamp
_row_deleted	boolean
_row_truncated	boolean

structure de la charge utile

La colonne payload matérialise l'arborescence MIME du message jusqu'à 8 niveaux d'imbrication. Chaque niveau présente la structure suivante :

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

Les pièces jointes sont contenues dans payload.parts[].body.attachmentId. Les parties imbriquées à plus de 8 niveaux de profondeur ne sont pas développées en colonnes struct.

étiquettes_de_message

Colonne	Type
message_id	string (clé principale)
threadId	string
labelIds	array<string>
mailbox	string
_ingestion_timestamp	timestamp
_row_deleted	boolean
_row_truncated	boolean

Colonne	Type
message_id	string (clé principale)
threadId	string
labelIds	array<string>
mailbox	string
_ingestion_timestamp	timestamp
_row_deleted	boolean
_row_truncated	boolean

Synchronisation incrémentielle

Les tables messages et message_labels se synchronisent de manière incrémentielle :

• La première exécution effectue une exploration initiale complète de la boîte aux lettres.
• Les exécutions ultérieures appellent users.history.list, basées sur le curseur historyId extrait de la ressource profile, pour récupérer uniquement les modifications depuis l'exécution précédente.
• Les suppressions sont émises sous forme de « tombstones » _row_deleted.
• Si Gmail expire le historyId stocké (l’API History renvoie une erreur 404 car le curseur est plus ancien que la fenêtre de rétention de Gmail), le connecteur revient automatiquement à une full refresh de la table concernée.

important

Gmail conserve l’historique pendant une fenêtre limitée, généralement d’environ sept jours. Planifiez l'exécution du pipeline au moins une fois tous les sept jours afin que les historyId stockés restent dans cette fenêtre. Si le curseur expire, la prochaine exécution effectue un refresh complet de messages et message_labels.

Les tables messages et message_labels ne prennent pas en charge le suivi de l'historique SCD de type 2 ; la configuration du SCD de type 2 pour ces tables entraîne l'échec de la validation du pipeline.

Limitation de débit

Lorsque Gmail renvoie une réponse HTTP 403, le connecteur lit l'en-tête Retry-After (avec un délai d'attente minimal de 1 seconde) et réessaie la requête automatiquement.