Gmailコネクターの参照

このページにはDatabricks Lakeflow ConnectのGmailコネクタに関する参考資料が含まれています。

Important

この機能は ベータ版です。 ワークスペース管理者は、[ プレビュー] ページからこの機能へのアクセスを制御できます。 Manage Azure Databricks プレビューを参照してください。

コネクタの一般的な動作

  • コネクタは読み取り専用です。 https://gmail.googleapis.comとしか通信せず、デフォルトでhttps://www.googleapis.com/auth/gmail.readonlyスコープを使用します。 送信元のメールボックスは一切変更されません。
  • 各接続は単一のメールボックスを取り込みます。 コネクターは郵便受けの値に各行に mailbox 列としてスタンプを付けます。 複数のメールボックスを取り込むには、それぞれのメールボックスごとに別々の接続とパイプラインを作成します。
  • ソーススキーマは defaultです。
  • messagesテーブルとmessage_labelsテーブルはGmail履歴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履歴API、 historyId)
message_labels message_id インクリメンタル(Gmail履歴API、 historyId)

変換先スキーマ

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

プロファイル

Column タイプ
emailAddress string (主キー)
messagesTotal long
threadsTotal long
historyId string
mailbox string

labels

Column タイプ
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_detailsテーブルはlabelsと同じ列(mailbox、id、name、type、可視フィールド、メッセージおよびスレッドカウント、color)を持ちます。 各ラベルは labels.get APIからの応答で強化されます。

下書き

Column タイプ
id string (主キー)
message struct{id: string, threadId: string}
mailbox string

フィルター

Column タイプ
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

messages

Column タイプ
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

Column タイプ
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 として発行されます。
  • Gmailが保存された historyId を期限切れにすると(履歴APIはカーソルがGmailの保持ウィンドウより古いため404を返します)、コネクターは自動的に影響を受けたテーブルのフルリフレッシュにフォールバックします。

Important

Gmailは履歴を約7日間だけ保持します。 パイプラインを少なくとも7日に1回稼働させ、貯蔵された historyId がその期間内に収まるようにしましょう。 カーソルが切れた場合、次の実行で messages と message_labelsの完全なリフレッシュが行われます。

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

レート制限

GmailがHTTP 403応答を返すと、コネクターは Retry-After ヘッダーを読み取り(最低1秒のバックオフ時間で)、自動的にリクエストを再試行します。

  • Last updated on