Gmail コネクタのリファレンス

備考

ベータ版

この機能はベータ版です。

このページには、Databricks Lakeflow Connect の Gmail コネクタのリファレンスが含まれています。

一般的なコネクタの動作

• このコネクタは読み取り専用です。https://gmail.googleapis.com``https://www.googleapis.com/auth/gmail.readonlyとしか通信せず、defaultスコープを使用します。ソースのメールボックスは一切変更されません。
• 各接続で 1 つのメールボックスを取り込みます。コネクタは、すべての行の mailbox 列としてメールボックスの値をスタンプします。複数のメールボックスを取り込むには、メールボックスごとに個別の接続とパイプラインを作成します。
• ソーススキーマは default です。
• messages および message_labels テーブルは、Gmail History API を使用して増分同期されます。profile、labels、labels_details、drafts、およびfiltersのテーブルは完全更新のみとなります。
• メッセージの添付ファイルは、messages テーブルの payload 列（payload.parts[].body.attachmentId）に含まれています。個別の添付ファイルテーブルはありません。

サポートされているテーブル

コネクタは、default ソーススキーマから次のテーブルを取り込みます。

テーブル	プライマリーキー	同期モード
profile	emailAddress	フルリフレッシュ
labels	mailbox, id	フルリフレッシュ
labels_details	mailbox, id	フルリフレッシュ
drafts	id	フルリフレッシュ
filters	id	フルリフレッシュ
messages	id	増分（Gmail History API、historyId）
message_labels	message_id	増分（Gmail History API、historyId）

テーブル	プライマリーキー	同期モード
profile	emailAddress	フルリフレッシュ
labels	mailbox, id	フルリフレッシュ
labels_details	mailbox, id	フルリフレッシュ
drafts	id	フルリフレッシュ
filters	id	フルリフレッシュ
messages	id	増分（Gmail History API、historyId）
message_labels	message_id	増分（Gmail History API、historyId）

宛先スキーマ

以降のセクションでは、各送信先テーブルの列について説明します。

プロファイル

列	Type
emailAddress	string (主キー)
messagesTotal	long
threadsTotal	long
historyId	string
mailbox	string

列	Type
emailAddress	string (主キー)
messagesTotal	long
threadsTotal	long
historyId	string
mailbox	string

ラベル

列	Type
mailbox	string (主キー)
id	string (主キー)
name	string
messageListVisibility	string
labelListVisibility	string
type	string
messagesTotal	long
messagesUnread	long
threadsTotal	long
threadsUnread	long
color	struct{textColor: string, backgroundColor: string}

列	Type
mailbox	string (主キー)
id	string (主キー)
name	string
messageListVisibility	string
labelListVisibility	string
type	string
messagesTotal	long
messagesUnread	long
threadsTotal	long
threadsUnread	long
color	struct{textColor: string, backgroundColor: string}

ラベルの詳細

labels_details テーブルは、labels と同じ列（mailbox、id、name、type、可視性フィールド、メッセージおよびスレッド数、そしてcolor）を持っています。各ラベルは、labels.get APIからの応答でエンリッチメントされます。

下書き

列	Type
id	string (主キー)
message	struct{id: string, threadId: string}
mailbox	string

列	Type
id	string (主キー)
message	struct{id: string, threadId: string}
mailbox	string

フィルター

列	Type
id	string (主キー)
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

列	Type
id	string (主キー)
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

メッセージ

列	Type
id	string (主キー)
threadId	string
snippet	string
historyId	string
internalDate	string
payload	struct （ペイロード構造を参照）
sizeEstimate	long
mailbox	string
_ingestion_timestamp	timestamp
_row_deleted	boolean
_row_truncated	boolean

列	Type
id	string (主キー)
threadId	string
snippet	string
historyId	string
internalDate	string
payload	struct （ペイロード構造を参照）
sizeEstimate	long
mailbox	string
_ingestion_timestamp	timestamp
_row_deleted	boolean
_row_truncated	boolean

ペイロード構造

payload 列は、メッセージ MIME ツリーを最大 8 レベルのネストまで具体化します。各レベルの構造は次のとおりです。

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

添付ファイルは payload.parts[].body.attachmentId 内に含まれています。8レベルを超えてネストされたパーツは、構造体の列には展開されません。

message_labels

列	Type
message_id	string (主キー)
threadId	string
labelIds	array<string>
mailbox	string
_ingestion_timestamp	timestamp
_row_deleted	boolean
_row_truncated	boolean

列	Type
message_id	string (主キー)
threadId	string
labelIds	array<string>
mailbox	string
_ingestion_timestamp	timestamp
_row_deleted	boolean
_row_truncated	boolean

増分同期

messages テーブルと message_labels テーブルは段階的に同期されます：

• 最初のランでは、メールボックスの完全なブートストラップクロールを実行します。
• 後続のランでは、profileリソースから取得したhistoryIdカーソルをキーとしてusers.history.listを呼び出し、前回のラン以降の変更のみを取得します。
• 削除は _row_deleted tombstoneとして出力されます。
• Gmail が保存された historyId を期限切れにした場合（カーソルが Gmail の保持期間よりも古いため、History API が 404 を返す）、コネクタは自動的に影響を受けるテーブルの完全更新にフォールバックします。

重要

Gmail は、限られた期間（通常は約 7 日間）の履歴を保持します。保存された historyId がその期間内に収まるように、少なくとも 7 日に 1 回はパイプラインを実行するようにスケジュールを設定してください。カーソルが期限切れになると、次回のランで messages と message_labels の完全更新が実行されます。

messagesテーブルおよびmessage_labelsテーブルはSCDタイプ2の履歴追跡をサポートしていません。これらのテーブルにSCD Type 2を設定するとパイプライン検証が失敗します。

レート制限

Gmail が HTTP 403 レスポンスを返すと、コネクタは Retry-After ヘッダーを読み取り（最小バックオフは1秒）、自動的にリクエストを再試行します。