Referência ao conector do Gmail

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

Importante

Esse recurso está em Beta. Os administradores do workspace podem controlar o acesso a esse recurso na página Visualizações . Consulte Gerenciar visualizações do Azure Databricks.

Comportamento geral do conector

  • O conector é somente leitura. Ele fala apenas com https://gmail.googleapis.com e usa o https://www.googleapis.com/auth/gmail.readonly telescópio por padrão. Ele nunca modifica a caixa de correio fonte.
  • Cada conexã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 de uma caixa de correio, crie uma conexão e um pipeline separados para cada caixa de correio.
  • O esquema fonte é default.
  • As messages tabelas e message_labels sincronizam incrementalmente usando a API de Histórico do Gmail. As profiletabelas , labels, labels_details, drafts, e filters são apenas para atualização completa.
  • Anexos de mensagens estão contidos na messagespayload coluna (payload.parts[].body.attachmentId). Não há 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 seções a seguir descrevem as colunas em cada tabela de destino.

analisar

Coluna Tipo
emailAddress string (chave primária)
messagesTotal long
threadsTotal long
historyId string
mailbox string

labels

Coluna Tipo
mailbox string (chave primária)
id string (chave 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.

rascunhos

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

filtros

Coluna Tipo
id string (chave 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

Coluna Tipo
id string (chave primária)
threadId string
snippet string
historyId string
internalDate string
payload struct (veja 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 possui 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>
}

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

message_labels

Coluna Tipo
message_id string (chave 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 incrementalmente:

  • A primeira execução faz um crawl completo da caixa de correio.
  • As execuções subsequentes chamam users.history.list, digitadas no historyId cursor retirado do profile recurso, para buscar apenas as mudanças 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 retorna um 404 porque o cursor é mais antigo que a janela de retenção do Gmail), o conector automaticamente retorna 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. Programe o pipeline para rodar 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 rastreamento de histórico SCD Tipo 2; configurar SCD Tipo 2 para essas tabelas causa falha na validação do pipeline.

Limitação de taxa

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

  • Last updated on