LoginSignup
2
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 3 years have passed since last update.

@nakazax(Hiroyuki Nakazato)

Azure Data Factory 上のリソース群を Azure Synapse Analytics ワークスペースに移行する

Last updated at Posted at 2021-03-12

はじめに

本記事では Azure Data Factory (ADF) 上のリソース群を Azure Synapse Analytics ワークスペースに移行する方法についてまとめます。先人が分かりやすくまとめて下さっている記事をかなり参考にしていますので、そちらも合わせてご覧ください。お約束ですが、本記事は公式のドキュメントではありませんので、お手元で作業される際は参考扱いとしてご覧頂ければと思います。

追記

2021 年 7 月に AzureSamples の GitHub リポジトリに ADF から Synapse への移行にお使い頂ける PowerShell スクリプトが公開されています。本 Qiita は手作業で進める流れとしていますが、スクリプトがお好みの場合は以下をお試しください。
https://github.com/Azure-Samples/Synapse/tree/main/Pipelines/ImportADFtoSynapse

参考リンク

移行の流れ

ADF & Synapse パイプライン上のリソースは以下のような依存関係になっています。矢印の終端が依存先 (依存されている) リソースです。依存先リソースが存在しない場合、依存元リソースを移行してもエラーになってしまいます。

qiita-adf-synapse-resource-relation.png

ADF で既定の統合ランタイム AutoResolveIntegrationRuntime しか利用していない場合は統合ランタイムの移行作業は特段不要です。セルフホステッド統合ランタイムなどを利用している場合は Synapse 側でもセットアップが必要です。

Linked service の中の Azure Key Vault は他の Linked service から参照されるリソースになります。ADF で Azure Key Vault を利用している場合は他の Linked service よりも先に移行する必要があります。

残りのリソースについて、本記事では Git 連携の強みを活かした方法で移行していきます。

事前作業 (必要なもののみ実施)

先んじて対応が必要なものを記載していきます。自身の環境に合わせて必要なもののみ実施すれば OK です。

ADF で既定以外の統合ランタイムを利用している場合

Synapse ワークスペースでも統合ランタイムをセットアップしておきます。その際、統合ランタイムの名前は ADF と Synapse ワークスペースで揃えた方が後続の移行作業がスムーズに行えます。

  • ADF の統合ランタイム一覧画面の例: 既定の統合ランタイム以外に 2 つのセルフホステッド統合ランタイムが存在
    image.png

  • Synapse Studio の統合ランタイム一覧画面の例: 既定の統合ランタイム以外に 2 つのセルフホステッド統合ランタイムを作成
    image.png

ADF の Linked service で Key Vault を利用している場合

Synapse ワークスペースのマネージド ID に Key Vault の参照権限を付与しておきます。

  • Key Vault のアクセス ポリシーの例: Synapse ワークスペースのマネージド ID にシークレットの取得と一覧を許可
    image.png

その後、Synapse Studio で Key Vault 用の Linked service を作成します。ADF 上の Linked service と名前は揃えておきます。作成後、Publish しておきます。

  • Key Vault 用の Linked service の作成画面
    image.png

ADF の Linked service でマネージド ID 認証を利用している場合

Synapse ワークスペースのマネージド ID に ADF と同等の Azure RBAC ロールを付与しておきます。

  • ストレージ アカウントのアクセス制御の例: Synapse ワークスペースのマネージド ID に「ストレージ BLOB データ共同作成者」を付与
    image.png

移行準備

ここから移行準備をしていきます。あらかじめ手元で以下のツールが使えるようにしておくと作業がスムーズです。

  • Git
  • 複数ファイルの文字列の一括置換が行えるツール (VSCode など)

1. ADF と Synapse ワークスペースの Git リポジトリ設定

以下のドキュメントを参考に ADF と Synapse ワークスペースの Git リポジトリを設定します。Azure DevOps Git または GitHub が選択できますが、どちらを選んでも OK です。既に Git リポジトリを設定済みの場合は本手順はスキップして OK です。

以下は参考の画面キャプチャです。

  • ADF の Git リポジトリ設定
    image.png

  • Synapse ワークスペースの Git リポジトリ設定
    image.png

2. 手元環境に Git リポジトリを clone

前段で設定した Git リポジトリを手元に clone しておきます。以下はコマンド例ですが、自身の環境に合わせて読み替えてください。

GitCloneExample(RepoForAdf)
$ git clone https://org-nakazax@dev.azure.com/org-nakazax/pj-nakazax/_git/openhack-mdw-adf-repo
Cloning into 'openhack-mdw-adf-repo'...
remote: Azure Repos
remote: Found 184 objects to send. (18 ms)
Receiving objects: 100% (184/184), 115.28 KiB | 123.00 KiB/s, done.
GitCloneExample(RepoForSynapse)
$ git clone https://org-nakazax@dev.azure.com/org-nakazax/pj-nakazax/_git/openhack-mdw-synapse-repo
Cloning into 'openhack-mdw-synapse-repo'...
remote: Azure Repos
remote: Found 12 objects to send. (36 ms)
Unpacking objects: 100% (12/12), 1.71 KiB | 12.00 KiB/s, done.

ADF 用のリポジトリは以下のようなフォルダ・ファイル構成になっているはずです。機能の利用有無によっては存在しないフォルダもあります。各 JSON ファイルが ADF 上のリソースに対応しています。

ADF用リポジトリ_フォルダ・ファイル構成
C:.
│  readme.md
│
├─dataflow
│      DataflowCustomers.json
│      (中略)
│      DataflowSalesOrders.json
│
├─dataset
│      FourAdlsCsvActors.json
│      (中略)
│      VanSqlTransactions.json
│
├─factory
│      df-hinakaza-openhack-mdw.json
│
├─integrationRuntime
│      SelfHostedIntegrationRuntimeFourthCoffee.json
│      SelfHostedIntegrationRuntimeVanArsdelLtd.json
│
├─linkedService
│      AzureDataLakeStorage_sthinakazaopenhackmdw.json
│      (中略)
│      SqlServer_Rentals.json
│
├─managedVirtualNetwork
│      default.json
│
├─pipeline
│      FourthCopyActors.json
│      (中略)
│      VanCopyTransactions.json
│
└─trigger
        ScheduleTriggerFourthCopyActors.json

移行作業

ここから移行作業に入っていきます。

1. 移行作業用 Git ブランチの作成

作業に失敗してもすぐにやり直しができるように Synapse ワークスペース用 Git リポジトリに移行作業用のブランチを作成しておきます。以下はブランチ作成例です。ここでは SourceTree という Git クライアントを利用していますが、お好みのツールをご利用ください。

  • 移行作業用ブランチの作成
    image.png

以降はこのブランチ上で作業を進めて行きます。

2. Linked service の移行

最初に Linked service を移行していきます。Linked service はデータストア等の接続情報を表す ADF & Synapse のリソースです。

注意点として、アカウント キーやパスワード等のいわゆるシークレットを直接設定している Linked service は Git を用いた移行ができません。ADF 側でマネージド ID や Key Vault を用いた認証方式に変更するか、Synapse ワークスペースに手動で設定する必要があります。

以下はマネージド ID や Key Vault での認証を設定した Linked service の作業ステップです。(Linked service の移行は他に比べるとややハマりどころが多いです。数が多くない場合は Synapse Studio から手動で設定するのもアリだと思います)

  • ADF 用リポジトリの linkedService フォルダ配下の JSON ファイル群を Synapse 用リポジトリの linkedService フォルダにコピー (フォルダが存在しない場合は新規作成する)
    image.png

  • type 置換
    各 JSON ファイル内の type を以下のように置換します。ファイル数が少ない場合は手作業でも良いですが、多い場合は VSCode などのツールを使うとスムーズに行えると思います。

置換前(Linkedservice)
"type": "Microsoft.DataFactory/factories/linkedservices"
置換後(Linkedservice)
"type": "Microsoft.Synapse/workspaces/linkedservices"
  • (参考) 置換後の JSON 全体の例
置換後JSON全体(Linkedservice)
{
	"name": "AzureDataLakeStorage_sthinakazaopenhackmdw",
	"properties": {
		"annotations": [],
		"type": "AzureBlobFS",
		"typeProperties": {
			"url": "https://sthinakazaopenhackmdw.dfs.core.windows.net"
		}
	},
	"type": "Microsoft.Synapse/workspaces/linkedservices"
}

  • (参考) VSCode での一括置換のイメージ
    image.png

  • type の置換が完了したら Git にコミット & プッシュ
    image.png

  • Azure Repos で作業用ブランチに切り替えて JSON ファイル群が追加されていることを確認する
    image.png
    image.png

  • Synapse Studio で作業用ブランチに切り替えて Linked service が追加されていることを確認する (作業用ブランチが表示されていない場合はブラウザをリフレッシュ)
    image.png
    image.png

  • Test connection が成功することを確認する
    image.png

補足1: Key Vault を利用している場合の一時エラー

私の手元で試した際、上記の手順で移行した Linked service のうち、マネージド ID の認証は Test connection まで問題なく成功しました。一方、Key Vault を利用している Linked service は Test connection に失敗しました。どうも UI か何かのエラーのようで、Key Vault の Linked service を選択し直すなどして再度 Test connection を実施すると成功しました。

  • Test connection に失敗
    image.png

  • Key Vault の Linked service を選択し直し
    image.png

  • 再度 Test connection を実行、成功したので Apply
    image.png

  • 即時の Publish を求められるので [OK] をクリック
    image.png

補足2: シークレットを直接設定している Linked service のエラー

セクションの冒頭で記載した通り、アカウント キーやパスワードなどのいわゆるシークレットを直接設定している Linked service を Git のコミット & プッシュ方式で移行しようとすると、以下のようなエラー Failed to decrypt sub-resource payload が出ます。

Linkedserviceエラー例
Failed to decrypt sub-resource 'None' payload on cloud with error: Failed to decrypt sub-resource payload {
"name": "AzureDataLakeStorage_sthinakazaopenhackmdw",
"properties": {
"type": "AzureBlobFS",
"annotations": [],
"typeProperties": {
"url": "********************",
"encryptedCredential": "********************"
}
}
} and error is: Cloud stored credentials cannot be found with retry, please check whether related resource had been deleted before. Value is: {
"Version": "2017-11-30",
"ProtectionMode": "Key",
"SecretContentType": "Plaintext",
"CredentialId": "DF-HINAKAZA-OPENHACK-MDW_261c61c7-f712-4213-8adc-da61b19dd987"
}, type is Plaintext and credentialId is DF-HINAKAZA-OPENHACK-MDW_261c61c7-f712-4213-8adc-da61b19dd987.., status code: BadRequest.
. Activity ID: b6c89131-82ef-4d02-93f5-4261c048b4a6

シークレットは以下のように encryptedCredential の中で暗号化されて保存されるのですが、Synapse にインポートした際にこれが復号化できずにエラーになっていると推察されます。

アカウントキー認証のJSON例
{
	"name": "AzureDataLakeStorage_sthinakazaopenhackmdw",
	"type": "Microsoft.DataFactory/factories/linkedservices",
	"properties": {
		"annotations": [],
		"type": "AzureBlobFS",
		"typeProperties": {
			"url": "https://sthinakazaopenhackmdw.dfs.core.windows.net",
			"encryptedCredential": "ew0KICAiVmVyc2lvbiI6ICIyMDE3LTExLTMwIiwNCiAgIlByb3RlY3Rpb25Nb2RlIjogIktleSIsDQogICJTZWNyZXRDb250ZW50VHlwZSI6ICJQbGFpbnRleHQiLA0KICAiQ3JlZGVudGlhbElkIjogIkRGLUhJTkFLQVpBLU9QRU5IQUNLLU1EV18yNjFjNjFjNy1mNzEyLTQyMTMtOGFkYy1kYTYxYjE5ZGQ5ODciDQp9"
		}
	}
}

以下はマネージド ID 認証をしている Linked service の例です。encryptedCredential が存在しない = 復号化が不要なためエラーが起きないものと推察されます。

マネージドID認証のJSON例
{
	"name": "AzureDataLakeStorage_sthinakazaopenhackmdw",
	"properties": {
		"annotations": [],
		"type": "AzureBlobFS",
		"typeProperties": {
			"url": "https://sthinakazaopenhackmdw.dfs.core.windows.net"
		}
	},
	"type": "Microsoft.DataFactory/factories/linkedservices"
}

3. Dataset の移行

  • ADF 用リポジトリの dataset フォルダ配下の JSON ファイル群を Synapse 用リポジトリの dataset フォルダにコピー (フォルダが存在しない場合は新規作成する)

image.png

  • type 置換
    各 JSON ファイル内の type を以下のように置換します。
置換前(Dataset)
"type": "Microsoft.DataFactory/factories/datasets"
置換後(Dataset)
"type": "Microsoft.Synapse/workspaces/datasets"
  • (参考) 置換後の JSON 全体の例
置換後JSON全体(Dataset)
{
	"name": "FourAdlsCsvActors",
	"properties": {
		"linkedServiceName": {
			"referenceName": "AzureDataLakeStorage_sthinakazaopenhackmdw",
			"type": "LinkedServiceReference"
		},
		"folder": {
			"name": "FourthCoffeeRentals"
		},
		"annotations": [],
		"type": "DelimitedText",
		"typeProperties": {
			"location": {
				"type": "AzureBlobFSLocation",
				"fileName": "Actors.csv",
				"folderPath": "FourthCoffeeRentals",
				"fileSystem": "source-data-container"
			},
			"columnDelimiter": ",",
			"escapeChar": "\\",
			"firstRowAsHeader": true,
			"quoteChar": "\""
		},
		"schema": []
	},
	"type": "Microsoft.Synapse/workspaces/datasets"
}

  • type の置換が完了したら Git にコミット & プッシュ

  • Synapse Studio で作業用ブランチに切り替えて [Data] ハブ > [Linked] > [Integration datasets] に Dataset が追加されていることを確認する
    image.png

  • 代表的なデータをプレビューし正常に参照できるかを確認する
    image.png
    image.png

4. Data flow の移行

  • ADF 用リポジトリの dataflow フォルダ配下の JSON ファイル群を Synapse 用リポジトリの dataflow フォルダにコピー (フォルダが存在しない場合は新規作成する)
    image.png

  • Data flow の JSON には type は含まれないため、そのまま Git にコミット & プッシュ

  • Synapse Studio で作業用ブランチに切り替えて [Develop] ハブ > [Data flows] に Data flow が追加されていることを確認する
    image.png

5. Pipeline の移行

  • ADF 用リポジトリの pipeline フォルダ配下の JSON ファイル群を Synapse 用リポジトリの pipeline フォルダにコピー (フォルダが存在しない場合は新規作成する)
    image.png

  • type 置換
    各 JSON ファイル内の type を以下のように置換します。

置換前(Pipeline)
"type": "Microsoft.DataFactory/factories/pipelines"
置換後(Pipeline)
"type": "Microsoft.Synapse/workspaces/pipelines"
  • (参考) 置換後の JSON 全体の例
置換後JSON全体(Pipeline)
{
	"name": "FourthCopyActors",
	"properties": {
		"activities": [
			{
				"name": "CopyActors",
				"type": "Copy",
				"dependsOn": [],
				"policy": {
					"timeout": "7.00:00:00",
					"retry": 0,
					"retryIntervalInSeconds": 30,
					"secureOutput": false,
					"secureInput": false
				},
				"userProperties": [],
				"typeProperties": {
					"source": {
						"type": "DelimitedTextSource",
						"storeSettings": {
							"type": "FileServerReadSettings",
							"recursive": true
						},
						"formatSettings": {
							"type": "DelimitedTextReadSettings"
						}
					},
					"sink": {
						"type": "DelimitedTextSink",
						"storeSettings": {
							"type": "AzureBlobFSWriteSettings"
						},
						"formatSettings": {
							"type": "DelimitedTextWriteSettings",
							"quoteAllText": true,
							"fileExtension": ".txt"
						}
					},
					"enableStaging": false,
					"translator": {
						"type": "TabularTranslator",
						"typeConversion": true,
						"typeConversionSettings": {
							"allowDataTruncation": true,
							"treatBooleanAsNumber": false
						}
					}
				},
				"inputs": [
					{
						"referenceName": "FourFileServerCsvActors",
						"type": "DatasetReference"
					}
				],
				"outputs": [
					{
						"referenceName": "FourAdlsCsvActors",
						"type": "DatasetReference"
					}
				]
			}
		],
		"folder": {
			"name": "FourthCoffeeRentals"
		},
		"annotations": [],
		"lastPublishTime": "2020-11-09T19:39:57Z"
	},
	"type": "Microsoft.Synapse/workspaces/pipelines"
}

  • type の置換が完了したら Git にコミット & プッシュ

  • Synapse Studio で作業用ブランチに切り替えて [Integrate] ハブ > [Pipelines] に Pipeline が追加されていることを確認する
    image.png

  • 代表的なパイプラインをデバッグ実行して正常終了するかを確認する

6. Trigger の移行

  • ADF 用リポジトリの trigger フォルダ配下の JSON ファイル群を Synapse 用リポジトリの trigger フォルダにコピー (フォルダが存在しない場合は新規作成する)
    image.png

  • Trigger の JSON には type は含まれないため、そのまま Git にコミット & プッシュ

  • Synapse Studio で作業用ブランチに切り替えて [Manage] ハブ > [Triggers] に Trigger が追加されていることを確認する
    image.png

7. 移行作業用ブランチのマージ & Publish

Synapse ワークスペース用 Git リポジトリの移行作業用ブランチをコラボレーション ブランチ (ここでは master ブランチ) にマージし、Publish します。

  • Synapse Studio で作業用ブランチに切り替えて [Create pull request] をクリック
    image.png

  • Azure DevOps で Pull request を作成
    image.png

  • Pull request を Complete & merge
    image.png

  • Synapse Studio でコラボレーション ブランチ (ここでは master) に切り替えて [Publish] をクリック
    image.png

  • [OK] をクリック
    image.png

  • Publish が完了するのを待つ (数が多いと数分程度掛かる可能性があります)
    image.png

8. 後片付け

これで移行作業は完了です。必要に応じて移行元の ADF のクリーン アップなどを実施します。

以上です。

2
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?