Referencia de conector de Gmail

Esta página contiene material de referencia para el conector de Gmail en Databricks Lakeflow Connect.

Importante

Esta característica se encuentra en su versión beta. Los administradores del área de trabajo pueden controlar el acceso a esta característica desde la página Vistas previas . Consulte Administrar versiones preliminares de Azure Databricks.

Comportamiento general del conector

  • El conector es de solo lectura. Solo habla y https://gmail.googleapis.com usa el https://www.googleapis.com/auth/gmail.readonly telescopio por defecto. Nunca modifica el buzón de origen.
  • Cada conexión ingiere un único buzón. El conector marca el valor del buzón como una mailbox columna en cada fila. Para ingerir más de un buzón, crea una conexión y un pipeline separados para cada buzón.
  • El esquema fuente es default.
  • Las messages tablas y message_labels se sincronizan de forma incremental usando la API de Historial de Gmail. Las tablas profile, labels, labels_details, drafts, y filters solo son de refresco completo.
  • Los archivos adjuntos de mensajes están contenidos dentro de la messagespayload columna (payload.parts[].body.attachmentId). No hay una tabla de adjuntos separada.

Tablas compatibles

El conector ingiere las siguientes tablas del default esquema fuente.

Tabla Llave primaria Modo de sincronización
profile emailAddress Actualización completa
labels mailbox, id Actualización completa
labels_details mailbox, id Actualización completa
drafts id Actualización completa
filters id Actualización completa
messages id Incremental (API de Historial de Gmail, historyId)
message_labels message_id Incremental (API de Historial de Gmail, historyId)

Esquema de destino

Las siguientes secciones describen las columnas de cada tabla de destinos.

profile

Columna Tipo
emailAddress string (clave principal)
messagesTotal long
threadsTotal long
historyId string
mailbox string

labels

Columna Tipo
mailbox string (clave principal)
id string (clave principal)
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 tabla tiene las mismas columnas que labels (mailbox, id, name, type, los campos de visibilidad, el número de mensajes e hilos, y color). Cada etiqueta se enriquece con la respuesta de la labels.get API.

drafts

Columna Tipo
id string (clave principal)
message struct{id: string, threadId: string}
mailbox string

filtros

Columna Tipo
id string (clave principal)
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

Columna Tipo
id string (clave principal)
threadId string
snippet string
historyId string
internalDate string
payload struct (véase estructura de carga útil)
sizeEstimate long
mailbox string
_ingestion_timestamp timestamp
_row_deleted boolean
_row_truncated boolean

Estructura de la carga útil

La payload columna materializa el árbol MIME de mensajes hasta 8 niveles de anidación. Cada nivel tiene la siguiente estructura:

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

Los apegos están contenidos dentro de payload.parts[].body.attachmentId. Las partes anidadas a más de 8 niveles de profundidad no se expanden en columnas estructurales.

message_labels

Columna Tipo
message_id string (clave principal)
threadId string
labelIds array<string>
mailbox string
_ingestion_timestamp timestamp
_row_deleted boolean
_row_truncated boolean

Sincronización incremental

Las messages tablas y message_labels se sincronizan de forma incremental:

  • La primera prueba realiza un rastreo bootstrap completo del buzón.
  • Las partidas posteriores llaman users.history.list, clavetado en el historyId cursor tomado del profile recurso, para obtener solo los cambios desde la ejecución anterior.
  • Las eliminaciones se emiten como _row_deleted lápidas.
  • Si Gmail caduca el almacenamiento historyId almacenado (la API de Historial devuelve un 404 porque el cursor es más antiguo que la ventana de retención de Gmail), el conector automáticamente vuelve a una actualización completa de la tabla afectada.

Importante

Gmail conserva el historial durante una ventana limitada, normalmente de unos siete días. Programa la pipeline para que se ejecute al menos una vez cada siete días para que el almacenamiento historyId se mantenga dentro de esa ventana. Si el cursor expira, la siguiente ejecución realiza un refresco completo de messages y message_labels.

Las messages tablas y message_labels no soportan seguimiento de historial SCD Tipo 2; configurar SCD Tipo 2 para estas tablas provoca fallos en la validación de la tubería.

Limitación de velocidad

Cuando Gmail devuelve una respuesta HTTP 403, el conector lee la Retry-After cabecera (con un mínimo de 1 segundo de interrupción) y vuelve a intentar la solicitud automáticamente.

  • Last updated on