Referência do conector do Gmail

Esta página contém material de referência para o conector Gmail no Databricks Lakeflow Connect.

Importante

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a esse recurso na página Visualizações . Ver Gerir as pré-visualizações de Azure Databricks.

Comportamento geral do conector

  • O conector é só de leitura. Fala apenas com https://gmail.googleapis.com o telescópio e usa https://www.googleapis.com/auth/gmail.readonly o telescópio por defeito. Nunca modifica a caixa de correio de origem.
  • Cada ligação ingere uma única caixa de correio. O conector carimba o valor da caixa de correio como uma mailbox coluna em cada linha. Para ingerir mais do que uma caixa de correio, crie uma ligação e pipeline separados para cada caixa.
  • O esquema fonte é default.
  • As messages tabelas e message_labels sincronizam-se incrementalmente usando a API de Histórico do Gmail. As profiletabelas , labels, labels_details, drafts, e filters são apenas de atualização completa.
  • Os anexos de mensagens estão contidos na messagespayload coluna (payload.parts[].body.attachmentId). Não existe uma tabela de anexos separada.

Tabelas suportadas

O conector ingere as seguintes tabelas do default esquema de origem.

Tabela Chave primária Modo de sincronização
profile emailAddress Atualização completa
labels mailbox, id Atualização completa
labels_details mailbox, id Atualização completa
drafts id Atualização completa
filters id Atualização completa
messages id Incremental (API de Histórico do Gmail, historyId)
message_labels message_id Incremental (API de Histórico do Gmail, historyId)

Esquema de destino

As secções seguintes descrevem as colunas em cada tabela de destino.

perfil

Column Tipo
emailAddress string (tonalidade primária)
messagesTotal long
threadsTotal long
historyId string
mailbox string

labels

Column Tipo
mailbox string (tonalidade primária)
id string (tonalidade primária)
name string
messageListVisibility string
labelListVisibility string
type string
messagesTotal long
messagesUnread long
threadsTotal long
threadsUnread long
color struct{textColor: string, backgroundColor: string}

labels_details

A labels_details tabela tem as mesmas colunas que labels (mailbox, id, name, type, os campos de visibilidade, as contagens de mensagens e threads, e color). Cada rótulo é enriquecido com a resposta da labels.get API.

Drafts

Column Tipo
id string (tonalidade primária)
message struct{id: string, threadId: string}
mailbox string

filters

Column Tipo
id string (tonalidade primária)
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 Tipo
id string (tonalidade primária)
threadId string
snippet string
historyId string
internalDate string
payload struct (ver estrutura da carga útil)
sizeEstimate long
mailbox string
_ingestion_timestamp timestamp
_row_deleted boolean
_row_truncated boolean

Estrutura da carga útil

A payload coluna materializa a árvore MIME da mensagem até 8 níveis de aninhamento. Cada nível tem a seguinte estrutura:

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

Os anexos estão contidos em payload.parts[].body.attachmentId. Partes aninhadas a mais de 8 níveis de profundidade não são expandidas em colunas estruturais.

message_labels

Column Tipo
message_id string (tonalidade primária)
threadId string
labelIds array<string>
mailbox string
_ingestion_timestamp timestamp
_row_deleted boolean
_row_truncated boolean

Sincronização incremental

As messages tabelas e message_labels sincronizam-se incrementalmente:

  • A primeira corrida faz um rastejamento completo da caixa de correio.
  • As execuções subsequentes chamam users.history.list, digitadas no historyId cursor retirado do profile recurso, para obter apenas as alterações desde a execução anterior.
  • As deleções são emitidas como _row_deleted lápides.
  • Se o Gmail expirar o armazenamento historyId (a API de Histórico devolve um 404 porque o cursor é mais antigo do que a janela de retenção do Gmail), o conector volta automaticamente a uma atualização completa da tabela afetada.

Importante

O Gmail mantém o histórico por uma janela limitada, normalmente cerca de sete dias. Agenda o pipeline para correr pelo menos uma vez a cada sete dias para que o armazenamento historyId fique dentro dessa janela. Se o cursor expirar, a próxima execução realiza uma atualização completa de messages e message_labels.

As messages tabelas e message_labels não suportam rastreio de histórico SCD Tipo 2; configurar SCD Tipo 2 para estas tabelas faz com que a validação do pipeline falhe.

Limitação de Velocidade

Quando o Gmail retorna uma resposta HTTP 403, o conector lê o Retry-After cabeçalho (com um mínimo de 1 segundo de recuo) e tenta o pedido automaticamente.

  • Last updated on