Referência do conector do Gmail

info

Beta

Esse recurso está em Beta.

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

Comportamento geral do conector

• O conector é somente leitura. Ele se comunica apenas com https://gmail.googleapis.com e usa o escopo https://www.googleapis.com/auth/gmail.readonly por default. Ele nunca modifica a caixa de correio de origem.
• Cada conexão ingere uma única caixa de correio. O conector insere o valor da caixa de correio como uma coluna mailbox em cada linha. Para importar dados de mais de uma caixa de correio, crie uma conexão e um pipeline separados para cada caixa de correio.
• O esquema de origem é default.
• As tabelas messages e message_labels são sincronizadas incrementalmente usando a API Gmail History. As tabelas profile, labels, labels_details, drafts e filters são apenas para refresh completo.
• Os anexos de mensagem estão contidos na coluna payload da tabela messages (payload.parts[].body.attachmentId). Não existe uma tabela de anexos separada.

Tabelas suportadas

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

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

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

Esquema de destino

As seções a seguir descrevem as colunas em cada tabela de destino.

perfil

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

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

rótulo

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}

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}

detalhes_dos_rótulos

A tabela labels_details 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 API labels.get.

rascunhos

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

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

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

mensagens

Coluna	Tipo
id	string (chave primária)
threadId	string
snippet	string
historyId	string
internalDate	string
payload	struct (consulte estrutura do payload)
sizeEstimate	long
mailbox	string
_ingestion_timestamp	timestamp
_row_deleted	boolean
_row_truncated	boolean

Coluna	Tipo
id	string (chave primária)
threadId	string
snippet	string
historyId	string
internalDate	string
payload	struct (consulte estrutura do payload)
sizeEstimate	long
mailbox	string
_ingestion_timestamp	timestamp
_row_deleted	boolean
_row_truncated	boolean

estrutura de payload

A coluna payload materializa a árvore MIME da mensagem em 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 com mais de 8 níveis de profundidade não são expandidas em colunas de estrutura.

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

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 tabelas messages e message_labels são sincronizadas de forma incremental:

• A primeira execução realiza um rastreamento de bootstrap completo da caixa de correio.
• Execuções subsequentes chamam users.history.list, baseadas no cursor historyId obtido do recurso profile, para buscar apenas as alterações desde a execução anterior.
• As exclusões são emitidas como lápides _row_deleted.
• Se o Gmail expirar o historyId armazenado (a API de história retorna um 404 porque o cursor é mais antigo que a janela de retenção do Gmail), o conector automaticamente recorre a um refresh completo da tabela afetada.

importante

O Gmail retém o histórico por uma janela limitada, normalmente cerca de sete dias. Programe o pipeline para execução pelo menos uma vez a cada sete dias para que o historyId armazenado permaneça dentro dessa janela. Se o cursor expirar, a próxima execução realizará um refresh completo de messages e message_labels.

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

Limitação de taxa

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