はじめに
どうも、そらです。
業務でAzure Data Factory（以下ADF）を触るようになったのですが、最初に「ExcelファイルのデータをSQLのテーブルにコピーする」という一番基本的な作業でかなりつまずきました。
やること自体はシンプルなのに、設定する場所が細かく分かれていて、どこを触ればいいのか分かりにくいです。
この記事では、私が実際に手を動かして分かった「一番シンプルなデータコピーのやり方」を、初心者向けに手順としてまとめます。
※画面の名称やメニューの位置は、時期やポータルの更新によって変わることがあります。実際の画面と照らし合わせながら読んでください。
この記事でわかること
- ADFでExcelファイルのデータをSQLテーブルにコピーする手順
- 先に用意しておくべき2つのデータセット（ソースとシンク）
- Excelファイル側でやっておくべき準備
- ファイルがあるかどうかを事前にチェックする方法（Get Metadata）
- ステージングを有効にする場所
- 初心者がつまずきやすいポイント
前提：先に言葉を整理する
ADFは専用の言葉が多いので、先に最低限だけ整理します。
| 言葉 | ざっくりした意味 |
|---|---|
| リンクサービス | 接続先の情報（このExcelやSQLはここにある、という接続設定） |
| データセット | 実際び読み書き対象（Excelのこのシート、SQLのこのテーブル等） |
| パイプライン | 一連の処理のまとまり（作業全体の入れ物） |
| アクティビティ | パイプラインの中に置く1つ1つの処理（コピー、チェックなど） |
| ソース | コピー元（今回はExcel） |
| シンク | コピー先（今回はSQLのテーブル） |
つまり今回やることは、「ソース（Excel）のデータを、シンク（SQLテーブル）にコピーする」 という1本の流れです。
全体の流れ
先に完成形の流れを示します。この順番で進めます。
| 手順 | やること |
|---|---|
| 1 | ソースデータセットとシンクデータセットを先に作る |
| 2 | Excelファイルをテーブル形式にしておく |
| 3 | シンク側のSQLに、ソースと同じ列名のテーブルをCREATE TABLEで作る |
| 4 | データセットの接続設定（シート名・先頭行をヘッダーに）を整える |
| 5 | スキーマのインポートで列名が正しく取れているか確認する |
| 6 | （応用）Get Metadataでファイルの存在をチェックする |
| 7 | 必要ならステージングを有効にする |
手順1：ソースとシンクのデータセットを先に作る
コピーの設定を始める前に、ソースデータセット（Excel側）とシンクデータセット（SQL側）を先に作っておく のがコツです。
コピーアクティビティを置いてから慌てて作ると、行ったり来たりして混乱します。先に2つとも作っておくと、後の設定がスムーズです。
- ソースデータセット：コピー元のExcelファイルを指すデータセット
- シンクデータセット：コピー先のSQLテーブルを指すデータセット
データセットの作り方は公式ドキュメントに画面付きで載っています。
手順2：Excelファイルはテーブル形式にしておく
これが最初のつまずきポイントでした。
ExcelファイルはExcelの「テーブル形式」にしておくと、ADFが列を正しく読み取りやすくなります。
普通にセルに入力しただけの表よりも、Excelの機能で「テーブル」として範囲を指定しておいたほうが、後のスキーマのインポート（手順5）で列名がきれいに取れます。
手順3：シンク側に同じ列名のテーブルを作る
コピー先（シンク）のSQLに、ソースのExcelと同じ列名のテーブルを、CREATE TABLEであらかじめ作っておきます。
ここでのポイントは「列名を合わせる」ことです。ソースとシンクで列名がそろっていれば、コピーの列の対応づけ（マッピング）が素直に通ります。
例（列名をExcel側とそろえる）：
CREATE TABLE dbo.SampleTable (
id INT,
name NVARCHAR(100),
price INT
);
上の列名（id, name, price）は、Excel側の先頭行（見出し）と同じにしておきます。
手順4：データセットの接続設定（シート名・先頭行をヘッダーに）
ソースデータセット（Excel）の設定で、次の2つを必ず確認します。
ADFのデータセットを開き、「接続」タブ で設定します。
- 「シート名」 で、ソースデータとして使いたいシートの名前を選ぶ
-
「先頭行をヘッダーとして」 のチェックをオンにする
「先頭行をヘッダーとして」をオンにしないと、1行目の見出しがデータとして扱われてしまい、列名がうまく取れません。
補足として、Get Metadataで列の構造（Structure）を取りたい場合も、この「先頭行をヘッダー」をオンにしておく必要があります。これはExcelや区切りテキスト形式でのみ使える設定です。
参考（Get Metadataの公式、Structureと先頭行ヘッダーの説明あり）：
https://learn.microsoft.com/ja-jp/azure/data-factory/control-flow-get-metadata-activity
手順5：スキーマのインポートで列名を確認する
手順4まで設定したら、データセットの 「スキーマのインポート」 を実行します。
ここで、ソースデータの実際の列名と種類（型）が表示されればOK です。
もし列名が変な文字（Column1, Column2 など）になっている場合は、手順4の「先頭行をヘッダーとして」がオフになっている可能性が高いです。手順4に戻って確認してください。
手順6（応用）：ファイルの存在をチェックする（Get Metadata）
「Excelファイルがちゃんと置かれているか、コピー前に確認したい」という場合は、Get Metadata（メタデータの取得） というアクティビティを使います。
「既存（Exists）」を設定する
Get Metadataアクティビティを選び、「設定」タブ の 「フィールドリスト」 で、引数として 「既存（Exists）」 を追加します。
この「既存（Exists）」を指定しておくと、ファイルが無かったときにアクティビティがいきなり失敗せず、結果として exists: false を返してくれます。逆に「既存」を指定していないと、ファイルが見つからないときにGet Metadata自体がエラーで止まります（これは公式ドキュメントに明記されています）。
参考（公式）：
https://learn.microsoft.com/ja-jp/azure/data-factory/control-flow-get-metadata-activity
存在チェックの結果を後の処理で使う
Get Metadataの結果（存在するかどうか）は、後続の処理で次のような式で参照できます。
@activity('Excel1_metadata').output.exists
-
Excel1_metadataの部分は、自分が付けたGet Metadataアクティビティの名前に置き換えます -
.output.existsで「存在した？（true / false）」を取り出します
この式を「If条件（If Condition）」アクティビティなどに入れておくと、「ファイルがあるときだけコピーを実行する」という分岐が作れます。
手順7：ステージングを有効化する
コピーの組み合わせによっては、ステージングを有効にする 必要があります。
ステージングとは、ソースからシンクへ直接コピーできない場合に、いったんAzure Blob StorageなどにデータをためてからシンクへコピーするADFの仕組みです。ADFが2段階のコピーを自動でやってくれます。
有効にする場所は、コピーアクティビティの「設定」タブ にある 「ステージングを有効にする」 のチェックです。
参考（ステージングの公式説明）：
https://learn.microsoft.com/ja-jp/azure/data-factory/copy-activity-performance-features
なお「Excelソースだと必ずステージングが要るのか」という点については、コピー先やデータの状態によって変わります（推測です）。まずは有効にせず試し、直接コピーできないという趣旨のエラーが出たときに有効にする、という進め方が確実です。
初心者がつまずきやすいポイント
私が実際にハマった順に並べます。
1. データセットを先に作らずにコピーを組み始める
先にソースとシンクの2つを作っておくだけで、設定の行き来がかなり減ります。
2. 「先頭行をヘッダーとして」を入れ忘れる
これを忘れると、見出し行がデータになり、列名がうまく取れません。スキーマのインポートで列名がおかしいときは、まずここを疑ってください。
3. ソースとシンクで列名がそろっていない
シンク側のCREATE TABLEの列名を、Excelの見出しとそろえておくと、マッピングで悩まなくなります。
4. Get Metadataで「既存」を入れずにファイルが無くて止まる
存在チェックが目的なら、必ず「既存（Exists）」をフィールドリストに入れます。入れないと、無いときにアクティビティごと失敗します。
最後に
ADFのデータコピーは、1つ1つの設定はシンプルですが、「どこを・どの順番で触るか」 が分かりにくいのが最初のハードルだと感じました。
今回のポイントをまとめると、次の通りです。
- ソースとシンクのデータセットは先に作る
- Excelはテーブル形式にし、「先頭行をヘッダーとして」をオンにする
- シンク側は同じ列名でCREATE TABLEしておく
- スキーマのインポートで列名を確認する
- 存在チェックはGet Metadataの「既存（Exists）」を使う
- 直接コピーできないときはステージングを有効にする
この記事が、これからADFで初めてデータコピーをする方の参考になればうれしいです。
参考リンク（Microsoft公式）
- コピーアクティビティの概要：https://learn.microsoft.com/ja-jp/azure/data-factory/copy-activity-overview
- Get Metadata（メタデータの取得）アクティビティ：https://learn.microsoft.com/ja-jp/azure/data-factory/control-flow-get-metadata-activity
- コピーアクティビティのパフォーマンス機能（ステージング）：https://learn.microsoft.com/ja-jp/azure/data-factory/copy-activity-performance-features