OneDriveからデータを取り込む

備考

ベータ版

この機能はベータ版です。ワークスペース管理者は、 Lakeflow Connect for OneDrive For Business のプレビュー にオプトインすることで、 Previews ページからこの機能へのアクセスを制御できます。「Databricks プレビューの管理」を参照してください。

このページでは、Lakeflow Connectを使用して、管理対象のMicrosoft OneDrive取り込みパイプラインを作成する方法を説明します。このパイプラインは、OneDriveからDeltaテーブルにファイルを取り込み、ソースとの同期状態を維持します。

始める前に

• 取り込みパイプラインを作成するには、まず次の要件を満たす必要があります。

  • ワークスペースでUnity Catalogが有効になっている必要があります。

  • ワークスペースでServerlessコンピュートが有効になっている必要があります。Serverlessコンピュートの要件を参照してください。

  • 新しい接続を作成するには、メタストアに対する CREATE CONNECTION 特権が必要です。Unity Catalog での特権の管理を参照してください。

    コネクタが UI ベースのパイプライン オーサリングをサポートしている場合、管理者はこのページのステップを完了することで、接続とパイプラインを同時に作成できます。 ただし、パイプラインを作成するユーザーが API ベースのパイプライン オーサリングを使用している場合、または管理者以外のユーザーである場合、管理者はまずカタログ エクスプローラーで接続を作成する必要があります。 「管理対象取り込みソースへの接続」を参照してください。

  • 既存の接続を使用するには、接続オブジェクトに対する USE CONNECTION 特権または ALL PRIVILEGES が必要です。

  • ターゲットカタログに対するUSE CATALOG権限が必要です。

  • 既存のスキーマに対するUSE SCHEMA権限およびCREATE TABLE権限、またはターゲット カタログに対するCREATE SCHEMA権限が必要です。

• Databricks Runtime 19 以上を使用する必要があります。API パイプライン定義で、channelをPREVIEWに設定します。

• OneDrive から取り込むには、まずサポートされている認証方法を構成し、接続を作成する必要があります。「OneDrive 接続を作成」を参照してください。

取り込みパイプラインを作成する

サポートされているファイル形式の一覧については、file_ingestion_optionsパラメーターを参照してください。コネクタ固有の制限事項については、Microsoft OneDriveコネクタの制限事項を参照してください。

1. 次のノートブックをDatabricksワークスペースにインポートします：

ノートブックを新しいタブで開くOpen in Databricks

2. セル2を変更しないでください。

3. セル3を、パイプライン構成の詳細で変更します。Microsoft OneDrive コネクタのリファレンスおよび例を参照してください。

4. 「 すべて実行 」をクリックします。

ノートブックを実行すると、パイプラインは作成されますが、起動されません。パイプラインを起動してスケジュールする方法については、共通のパイプラインメンテナンスタスクを参照してください。

ソースURLを選択する

パイプライン定義内の各オブジェクトは、connector_options.onedrive_options.urlでソースを指定します。URLは、OneDrive for Businessの 「マイ ファイル」 ドライブ内にある、次のいずれかのリソースを指している必要があります：

• ドライブのルート
• フォルダ
• ファイル
• 有効な共有Link

URLは<tenant>-my.sharepoint.comのような個人用OneDriveホストを使用する必要があります。以下のURLはサポートされていません。

• SharePointサイトのURL（/sites/...）
• Consumer OneDrive URL（onedrive.live.comなど）または 1drv.ms
• ホスト URL のみ
• 個人用ドライブ外のパス

URLの例と、OneDriveからURLをコピーする手順については、OneDriveからファイルを読み取るを参照してください。

例

次の例を使用して、パイプラインを構成します。各プレースホルダーを、環境に合わせた値に置き換えます。

ファイルを非構造化データとして取り込む

OneDrive からファイルをバイナリコンテンツとして取り込みます。各ファイルは、ファイルのバイトデータとメタデータを含む行になります。たとえば RAG アプリケーションなど、後続処理を行う予定の PDF、Office ドキュメント、画像、その他のファイルには、このアプローチを使用します。

注記

ベータ版で利用可能なFILEタイプは、ファイルのバイトデータではなく、各ファイルとそのメタデータへのガバナンス管理された参照を保存するため、読み取りパフォーマンスが向上します。BINARYFILEタイプではなくFILEタイプとしてファイルを取り込むには、「FILEタイプとしてファイルを取り込む（ベータ版）」を参照してください。

Python

pipeline_spec = {
  "name": "onedrive_binary_pipeline",
  "catalog": "main",
  "schema": "ingest_destination_schema",
  "ingestion_definition": {
    "connection_name": "<onedrive-connection>",
    "objects": [
      {
        "table": {
          "destination_catalog": "main",
          "destination_schema": "ingest_destination_schema",
          "destination_table": "drive_files",
          "connector_options": {
            "onedrive_options": {
              "entity_type": "FILE",
              "url": "https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents",
              "file_ingestion_options": {
                "format": "BINARYFILE",
                "schema_evolution_mode": "NONE"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

ファイルをFILEタイプとして取り込む（ベータ版）

備考

ベータ版

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

各ソースファイルを Unity Catalog ボリュームにコピーし、各ファイルとそのメタデータへのガバナンス管理された参照を宛先テーブルに保存するため、ファイルをFILEタイプとして取り込みます。宛先テーブルには file 列が公開されており、ai_parse_documentなどの関数やユーザー定義関数（UDF）に渡すことができます。

FILEタイプを使用するには、パイプラインで次の項目を構成します：

• パイプラインのchannelをPREVIEWに設定します。
• file_ingestion_options.formatをFILEに設定します。
• databricks.filespace-previewテーブルプロパティを設定して、Unity Catalogがマネージドストレージとして使用するボリュームを宣言します。

FILEの要件と動作については、FILEタイプとしてファイルを取り込むを参照してください。

Python

pipeline_spec = {
  "name": "onedrive_file_pipeline",
  "catalog": "<catalog>",
  "schema": "<schema>",
  "ingestion_definition": {
    "connection_name": "<onedrive-connection>",
    "objects": [
      {
        "table": {
          "destination_catalog": "<catalog>",
          "destination_schema": "<schema>",
          "destination_table": "<destination-table>",
          "table_configuration": {
            "table_properties": {
              "databricks.filespace-preview": "/Volumes/<catalog>/<schema>/<volume>/"
            }
          },
          "connector_options": {
            "onedrive_options": {
              "entity_type": "FILE",
              "url": "https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents",
              "file_ingestion_options": {
                "format": "FILE",
                "schema_evolution_mode": "NONE"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

構造化ファイルを取り込む

OneDriveフォルダーから構造化ファイル（例：JSONファイル）を取り込みます。ソースファイルの各行が、送信先テーブルの1行になります。

Python

pipeline_spec = {
  "name": "onedrive_json_pipeline",
  "catalog": "main",
  "schema": "ingest_destination_schema",
  "ingestion_definition": {
    "connection_name": "<onedrive-connection>",
    "objects": [
      {
        "table": {
          "destination_catalog": "main",
          "destination_schema": "ingest_destination_schema",
          "destination_table": "json_files",
          "connector_options": {
            "onedrive_options": {
              "entity_type": "FILE",
              "url": "https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents/json_folder",
              "file_ingestion_options": {
                "format": "JSON",
                "schema_evolution_mode": "NONE"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

ファイルのメタデータのみを取り込む

ファイルのメタデータ（名前、サイズ、Timestamp、パス）を、ファイルの内容をdownloadせずに取り込みます。ファイルの内容を取り込むオーバーヘッドなしに、ファイルのインベントリが必要な場合は、このアプローチを使用します。

entity_typeをFILE_METADATAに設定してください。FILE_METADATAの取り込みにはBINARYFILE形式を使用する必要があります。メタデータのみの取り込みでは、構造化形式および半構造化形式はサポートされていません。

Python

pipeline_spec = {
  "name": "onedrive_metadata_pipeline",
  "catalog": "main",
  "schema": "ingest_destination_schema",
  "ingestion_definition": {
    "connection_name": "<onedrive-connection>",
    "objects": [
      {
        "table": {
          "destination_catalog": "main",
          "destination_schema": "ingest_destination_schema",
          "destination_table": "file_metadata",
          "connector_options": {
            "onedrive_options": {
              "entity_type": "FILE_METADATA",
              "url": "https://mytenant-my.sharepoint.com/personal/user_mytenant_onmicrosoft_com/Documents",
              "file_ingestion_options": {
                "format": "BINARYFILE",
                "schema_evolution_mode": "NONE"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

ファイル取り込みオプションを構成する

file_ingestion_optionsブロックは、ファイルの処理方法を制御します。すべてのオプションは、パイプライン定義のconnector_options.onedrive_options.file_ingestion_optionsブロック内で設定されます。次のスニペットは、パイプライン定義のfile_ingestion_optionsフラグメントを示しています。すべてのパラメーターについては、file_ingestion_optionsパラメーターをご覧ください。

ファイルフィルター

ソースURLから取り込むファイルを制限するには、file_filtersを使用します：

JSON

"file_ingestion_options": {
  "format": "CSV",
  "file_filters": [
    { "path_filter": "invoices/*.csv" },
    { "modified_after": "2026-01-01T00:00:00" }
  ]
}

スキーマ進化とスキーマヒント

schema_evolution_mode を設定して、受信ファイル内の新しい列の処理方法を制御します。schema_hints を使用して、推測された列の型を上書きします。

スキーマ進化は、CSV、JSON、XML、PARQUET、AVROにのみ適用されます。その他の形式（BINARYFILE、FILE、EXCEL、ORC）では、schema_evolution_modeをNONEに設定します。

JSON

"file_ingestion_options": {
  "format": "CSV",
  "schema_evolution_mode": "ADD_NEW_COLUMNS_WITH_TYPE_WIDENING",
  "schema_hints": "order_id INT, amount DOUBLE, ts TIMESTAMP"
}

スキーマ進化とスキーマヒントの情報については、Auto Loaderでスキーマ推論と進化を構成するを参照してください。

形式固有のオプション

形式固有のオプションはformat_optionsを使用して渡します：

JSON

"file_ingestion_options": {
  "format": "CSV",
  "format_options": {
    "header": "true",
    "sep": ","
  }
}

サポートされるキーは、標準の Auto Loader 形式オプションです。Spark データソースのオプションを参照してください。

一般的なパターン

高度なパイプライン構成については、「管理された取り込みパイプラインの一般的なパターン」を参照してください。

次のステップ

パイプラインを起動、スケジュール設定し、アラートを設定する。一般的なパイプラインのメンテナンスタスクを参照してください。

その他のリソース

• OneDrive コネクター
• Microsoft OneDriveコネクタの制限事項
• Microsoft OneDriveコネクタのリファレンス