クイックスタート: PowerShell を使用した Azure データ ファクトリの作成

適用対象: Azure Data Factory Azure Synapse Analytics

このクイックスタートでは、PowerShell を使用して Azure データ ファクトリを作成する方法について説明します。 このデータ ファクトリに作成されたパイプラインは、データを Azure Blob Storage 内のあるフォルダーから別のフォルダーに コピー します。 Azure Data Factory を使用してデータを 変換 する方法のチュートリアルについては、Spark を使用したデータ変換のチュートリアルを参照してください。

注意

この記事では、Data Factory サービスの概要については詳しく取り上げません。 Azure Data Factory サービスの概要については、「Azure Data Factory の概要」をご覧ください。

前提条件

Azure サブスクリプション

Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。

Azure ロール

Data Factory インスタンスを作成するには、Azure へのサインインに使用するユーザー アカウントが、"共同作成者" ロールまたは "所有者" ロールのメンバーであるか、Azure サブスクリプションの "管理者" である必要があります。 サブスクリプションで自分が持っているアクセス許可を表示するには、Azure portal に移動し、右上にあるユーザー名を選択してください。" ... " アイコンを選択してその他のオプションを表示し、 [アクセス許可] を選択します。 複数のサブスクリプションにアクセスできる場合は、適切なサブスクリプションを選択します。

データセット、リンクされたサービス、パイプライン、トリガー、および統合ランタイムを含む Data Factory の子リソースを作成および管理するには、次の要件が適用されます。

  • Azure portal で子リソースを作成および管理するには、リソース グループ レベル以上で Data Factory 共同作成者 ロールに属している必要があります。
  • PowerShell または SDK を使用して子リソースを作成および管理する場合は、リソース レベル以上での 共同作成者 ロールで十分です。

ロールにユーザーを追加する方法に関するサンプル手順については、ロールの追加に関する記事を参照してください。

詳細については、次の記事を参照してください。

Azure ストレージ アカウント

このクイックスタートでは、"ソース" データ ストアと "コピー先" データ ストアの両方に汎用の Azure Storage アカウント (具体的には Blob Storage) を使用します。 汎用の Azure Storage アカウントがない場合、作成方法については、ストレージ アカウントの作成に関するページを参照してください。

ストレージ アカウント名を取得する

このクイックスタートには、Azure Storage アカウントの名前が必要です。 以下の手順に従って、ご利用のストレージ アカウントの名前を取得してください。

  1. Web ブラウザーで Azure portal にアクセスし、Azure のユーザー名とパスワードを使用してサインインします。
  2. [Azure portal] メニューで [すべてのサービス] を選択してから、 [ストレージ] > [ストレージ アカウント] の順に選択します。 また、任意のページから検索して、 [ストレージ アカウント] を選択することもできます。
  3. [ストレージ アカウント] ページで、ご利用のストレージ アカウントを (必要に応じて) フィルターで抽出し、該当するストレージ アカウントを選択します。

また、任意のページから検索して、 [ストレージ アカウント] を選択することもできます。

BLOB コンテナーを作成する

このセクションでは、adftutorial という名前の BLOB コンテナーを Azure Blob Storage に作成します。

  1. ストレージ アカウント ページで、 [概要] > [コンテナー] を選択します。

  2. <Account name> - [コンテナー] ページのツールバーで、 [コンテナー] を選択します。

  3. [新しいコンテナー] ダイアログ ボックスで、名前に「adftutorial」と入力し、 [OK] を選択します。 <Account name> - [コンテナー] ページが更新され、コンテナーの一覧に adftutorial が含まれるようになります。

    コンテナーの一覧

BLOB コンテナーの入力フォルダーとファイルを追加する

このセクションでは、作成したコンテナーに input という名前のフォルダーを作成し、入力フォルダーにサンプル ファイルをアップロードします。 開始する前に、メモ帳 などのテキスト エディターを開き、次の内容を含む emp.txt という名前のファイルを作成します。

John, Doe
Jane, Doe

C:\ADFv2QuickStartPSH フォルダーにファイルを保存します (フォルダーがまだ存在しない場合は作成します)。Azure portal に戻り、次の手順を実行します。

  1. 中断した <Account name> - [コンテナー] ページで、コンテナーの更新された一覧から [adftutorial] を選択します。

    1. ウィンドウを閉じた場合、または別のページに移動した場合は、[Azure portal] にもう一度サインインします。
    2. [Azure portal] メニューで [すべてのサービス] を選択してから、 [ストレージ] > [ストレージ アカウント] の順に選択します。 また、任意のページから検索して、 [ストレージ アカウント] を選択することもできます。
    3. ストレージ アカウントを選択してから、 [コンテナー] > [adftutorial] を選択します。
  2. adftutorial コンテナー ページのツールバーで、 [アップロード] を選択します。

  3. [BLOB のアップロード] ページで、 [ファイル] ボックスを選択し、emp.txt ファイルを参照して選択します。

  4. [詳細設定] の見出しを展開します。 次のようにページが表示されます。

    [詳細設定] リンクの選択

  5. [アップロード先のフォルダー] ボックスに「input」と入力します。

  6. [アップロード] ボタンを選択します。 一覧に emp.txt ファイルとアップロードの状態が表示されます。

  7. [閉じる] アイコン (X) を選択して、 [BLOB のアップロード] ページを閉じます。

adftutorial コンテナーのページを開いたままにしておきます。 このクイックスタートの最後で、このページを使用して出力を確認します。

Azure PowerShell

注意

この記事は、Azure Az PowerShell モジュールを使用するように更新されています。 Az PowerShell モジュールは、Azure と対話するために推奨される PowerShell モジュールです。 Az PowerShell モジュールの使用を開始するには、「Azure PowerShell をインストールする」を参照してください。 Az PowerShell モジュールに移行する方法については、「AzureRM から Az への Azure PowerShell の移行」を参照してください。

Azure PowerShell のインストールと構成の方法に関するページの手順に従って、最新の Azure PowerShell モジュールをインストールしてください。

警告

最新バージョンの PowerShell および Data Factory モジュールを使用しない場合は、コマンドの実行中に逆シリアル化エラーが発生する可能性があります。

PowerShell にログインする

  1. お使いのマシンで PowerShell を起動します。 PowerShell は、このクイックスタートが終わるまで開いたままにしておいてください。 Azure PowerShell を閉じて再度開いた場合は、これらのコマンドをもう一度実行する必要があります。

  2. 次のコマンドを実行して、Azure Portal へのサインインに使用するのと同じ Azure ユーザー名とパスワードを入力します。

    Connect-AzAccount
    
  3. 次のコマンドを実行して、このアカウントのすべてのサブスクリプションを表示します。

    Get-AzSubscription
    
  4. アカウントに複数のサブスクリプションが関連付けられている場合は、次のコマンドを実行して、使用するサブスクリプションを選択します。 SubscriptionId は、実際の Azure サブスクリプションの ID に置き換えてください。

    Select-AzSubscription -SubscriptionId "<SubscriptionId>"
    

Data Factory の作成

  1. 後で PowerShell コマンドで使用できるように、リソース グループ名の変数を定義します。 次のコマンド テキストを PowerShell にコピーし、Azure リソース グループの名前を二重引用符で囲んで指定し、コマンドを実行します。 (例: "ADFQuickStartRG")。

    $resourceGroupName = "ADFQuickStartRG";
    

    リソース グループが既に存在する場合、上書きしないようお勧めします。 $ResourceGroupName 変数に別の値を割り当てて、コマンドをもう一度実行します。

  2. Azure リソース グループを作成するには、次のコマンドを実行します。

    $ResGrp = New-AzResourceGroup $resourceGroupName -location 'East US'
    

    リソース グループが既に存在する場合、上書きしないようお勧めします。 $ResourceGroupName 変数に別の値を割り当てて、コマンドをもう一度実行します。

  3. データ ファクトリ名の変数を定義します。

    重要

    データ ファクトリ名は、グローバルに一意となるように更新してください。 たとえば、ADFTutorialFactorySP1127 です。

    $dataFactoryName = "ADFQuickStartFactory";
    
  4. データ ファクトリを作成するには、$ResGrp 変数の Location および ResourceGroupName プロパティを使用して、次の Set-AzDataFactoryV2 コマンドレットを実行します。

    $DataFactory = Set-AzDataFactoryV2 -ResourceGroupName $ResGrp.ResourceGroupName `
        -Location $ResGrp.Location -Name $dataFactoryName
    

以下の点に注意してください。

  • Azure Data Factory の名前はグローバルに一意にする必要があります。 次のエラーが発生した場合は、名前を変更してからもう一度実行してください。

    The specified Data Factory name 'ADFv2QuickStartDataFactory' is already in use. Data Factory names must be globally unique.
    
  • Data Factory インスタンスを作成するには、Azure へのログインに使用するユーザー アカウントが、共同作成者 ロールまたは 所有者 ロールのメンバーであるか、Azure サブスクリプションの 管理者 である必要があります。

  • 現在 Data Factory が利用できる Azure リージョンの一覧については、次のページで目的のリージョンを選択し、 [分析] を展開して [Data Factory] を探してください。リージョン別の利用可能な製品 データ ファクトリで使用するデータ ストア (Azure Storage、Azure SQL Database など) やコンピューティング (HDInsight など) は他のリージョンに配置できます。

リンクされたサービスを作成する

データ ストアおよびコンピューティング サービスをデータ ファクトリにリンクするには、リンクされたサービスをデータ ファクトリに作成します。 このクイックスタートでは、ソース ストアとシンク ストアの両方として使用される Azure Storage のリンクされたサービスを作成します。 リンクされたサービスは、Data Factory サービスが実行時に接続するために使用する接続情報を持っています。

ヒント

データ ストアの認証の種類として、このクイックスタートでは "アカウント キー" を使用しますが、サポートされている他の認証方法を選ぶこともできます。"SAS URI"、"サービス プリンシパル"、"マネージド ID" を必要に応じて使用してください。 詳細については、この記事の対応するセクションを参照してください。 さらに、データ ストアのシークレットを安全に格納するために、Azure Key Vault の使用をお勧めします。 詳細については、この記事を参照してください。

  1. 以下の内容を記述した AzureStorageLinkedService.json という名前の JSON ファイルを C:\ADFv2QuickStartPSH フォルダー内に作成します。まだ存在しない場合は、ADFv2QuickStartPSH フォルダーを作成してください。

    重要

    <accountName> と <accountKey> を実際の Azure ストレージ アカウントの名前とキーに置き換えてからファイルを保存してください。

    {
        "name": "AzureStorageLinkedService",
        "properties": {
            "annotations": [],
            "type": "AzureBlobStorage",
            "typeProperties": {
                "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountName>;AccountKey=<accountKey>;EndpointSuffix=core.windows.net"
            }
        }
    }
    

    メモ帳を使用している場合は、 [名前を付けて保存] ダイアログ ボックスの [ファイルの種類] フィールドで [すべてのファイル] を選択します。 そうしないと、ファイルに .txt 拡張子が追加されることがあります。 たとえば、「 AzureStorageLinkedService.json.txt 」のように入力します。 このファイルをエクスプローラーで作成してからメモ帳で開くと、.txt 拡張子は表示されない場合があります。これは、 [登録されている拡張子は表示しない] オプションが既定で設定されているためです。 .txt 拡張子を削除してから次の手順に進んでください。

  2. PowerShellADFv2QuickStartPSH フォルダーに切り替えます。

    Set-Location 'C:\ADFv2QuickStartPSH'
    
  3. Set-AzDataFactoryV2LinkedService コマンドレットを実行して、リンクされたサービス AzureStorageLinkedService を作成します。

    Set-AzDataFactoryV2LinkedService -DataFactoryName $DataFactory.DataFactoryName `
        -ResourceGroupName $ResGrp.ResourceGroupName -Name "AzureStorageLinkedService" `
        -DefinitionFile ".\AzureStorageLinkedService.json"
    

    出力例を次に示します。

    LinkedServiceName : AzureStorageLinkedService
    ResourceGroupName : <resourceGroupName>
    DataFactoryName   : <dataFactoryName>
    Properties        : Microsoft.Azure.Management.DataFactory.Models.AzureBlobStorageLinkedService
    

データセットを作成する

この手順では、InputDatasetOutputDataset。 これらのデータセットの種類は、Binary です。 これらは、前のセクションで作成した Azure Storage のリンクされたサービスを参照します。 入力データセットは、入力フォルダーのソース データを表します。 入力データセットの定義では、ソース データを格納している BLOB コンテナー (adftutorial)、フォルダー (input)、およびファイル (emp.txt) を指定します。 出力データセットは、ターゲットにコピーされるデータを表します。 出力データセットの定義では、データのコピー先の BLOB コンテナー (adftutorial)、フォルダー (output)、およびファイルを指定します。

  1. 以下の内容を記述した InputDataset.json という名前の JSON ファイルを C:\ADFv2QuickStartPSH フォルダー内に作成します。

    {
        "name": "InputDataset",
        "properties": {
            "linkedServiceName": {
                "referenceName": "AzureStorageLinkedService",
                "type": "LinkedServiceReference"
            },
            "annotations": [],
            "type": "Binary",
            "typeProperties": {
                "location": {
                    "type": "AzureBlobStorageLocation",
                    "fileName": "emp.txt",
                    "folderPath": "input",
                    "container": "adftutorial"
                }
            }
        }
    }
    
  2. データセット InputDataset を作成するには、Set-AzDataFactoryV2Dataset コマンドレットを実行します。

    Set-AzDataFactoryV2Dataset -DataFactoryName $DataFactory.DataFactoryName `
        -ResourceGroupName $ResGrp.ResourceGroupName -Name "InputDataset" `
        -DefinitionFile ".\InputDataset.json"
    

    出力例を次に示します。

    DatasetName       : InputDataset
    ResourceGroupName : <resourceGroupname>
    DataFactoryName   : <dataFactoryName>
    Structure         :
    Properties        : Microsoft.Azure.Management.DataFactory.Models.BinaryDataset
    
  3. 手順を繰り返して、出力データセットを作成します。 以下の内容を記述した OutputDataset.json という名前の JSON ファイルを C:\ADFv2QuickStartPSH フォルダー内に作成します。

    {
        "name": "OutputDataset",
        "properties": {
            "linkedServiceName": {
                "referenceName": "AzureStorageLinkedService",
                "type": "LinkedServiceReference"
            },
            "annotations": [],
            "type": "Binary",
            "typeProperties": {
                "location": {
                    "type": "AzureBlobStorageLocation",
                    "folderPath": "output",
                    "container": "adftutorial"
                }
            }
        }
    }
    
  4. Set-AzDataFactoryV2Dataset コマンドレットを実行して、OutDataset を作成します。

    Set-AzDataFactoryV2Dataset -DataFactoryName $DataFactory.DataFactoryName `
        -ResourceGroupName $ResGrp.ResourceGroupName -Name "OutputDataset" `
        -DefinitionFile ".\OutputDataset.json"
    

    出力例を次に示します。

    DatasetName       : OutputDataset
    ResourceGroupName : <resourceGroupname>
    DataFactoryName   : <dataFactoryName>
    Structure         :
    Properties        : Microsoft.Azure.Management.DataFactory.Models.BinaryDataset
    

パイプラインを作成する

この手順では、入力データセットと出力データセットを使用するコピー アクティビティを持つパイプラインを作成します。 コピー アクティビティにより、入力データセットの設定で指定されたファイルから、出力データセットの設定で指定されたファイルにデータがコピーされます。

  1. 以下の内容を記述した Adfv2QuickStartPipeline.json という名前の JSON ファイルを C:\ADFv2QuickStartPSH フォルダー内に作成します。

    {
        "name": "Adfv2QuickStartPipeline",
        "properties": {
            "activities": [
                {
                    "name": "CopyFromBlobToBlob",
                    "type": "Copy",
                    "dependsOn": [],
                    "policy": {
                        "timeout": "7.00:00:00",
                        "retry": 0,
                        "retryIntervalInSeconds": 30,
                        "secureOutput": false,
                        "secureInput": false
                    },
                    "userProperties": [],
                    "typeProperties": {
                        "source": {
                            "type": "BinarySource",
                            "storeSettings": {
                                "type": "AzureBlobStorageReadSettings",
                                "recursive": true
                            }
                        },
                        "sink": {
                            "type": "BinarySink",
                            "storeSettings": {
                                "type": "AzureBlobStorageWriteSettings"
                            }
                        },
                        "enableStaging": false
                    },
                    "inputs": [
                        {
                            "referenceName": "InputDataset",
                            "type": "DatasetReference"
                        }
                    ],
                    "outputs": [
                        {
                            "referenceName": "OutputDataset",
                            "type": "DatasetReference"
                        }
                    ]
                }
            ],
            "annotations": []
        }
    }
    
  2. パイプライン Adfv2QuickStartPipeline を作成するには、Set-AzDataFactoryV2Pipeline コマンドレットを実行します。

    $DFPipeLine = Set-AzDataFactoryV2Pipeline `
        -DataFactoryName $DataFactory.DataFactoryName `
        -ResourceGroupName $ResGrp.ResourceGroupName `
        -Name "Adfv2QuickStartPipeline" `
        -DefinitionFile ".\Adfv2QuickStartPipeline.json"
    

パイプラインの実行を作成する

この手順では、パイプラインの実行を作成します。

Invoke-AzDataFactoryV2Pipeline コマンドレットを実行して、パイプラインの実行を作成します。 コマンドレットは、将来の監視のために、パイプラインの実行 ID を返します。

$RunId = Invoke-AzDataFactoryV2Pipeline `
  -DataFactoryName $DataFactory.DataFactoryName `
  -ResourceGroupName $ResGrp.ResourceGroupName `
  -PipelineName $DFPipeLine.Name 

パイプラインの実行を監視します

  1. 次の PowerShell スクリプトを実行し、データのコピーが完了するまで、パイプラインの実行の状態を継続的にチェックします。 次のスクリプトをコピーして PowerShell ウィンドウに貼り付け、Enter キーを押します。

    while ($True) {
        $Run = Get-AzDataFactoryV2PipelineRun `
            -ResourceGroupName $ResGrp.ResourceGroupName `
            -DataFactoryName $DataFactory.DataFactoryName `
            -PipelineRunId $RunId
    
        if ($Run) {
            if ( ($Run.Status -ne "InProgress") -and ($Run.Status -ne "Queued") ) {
                Write-Output ("Pipeline run finished. The status is: " +  $Run.Status)
                $Run
                break
            }
            Write-Output ("Pipeline is running...status: " + $Run.Status)
        }
    
        Start-Sleep -Seconds 10
    }
    

    パイプラインの実行の出力例を次に示します。

    Pipeline is running...status: InProgress
    Pipeline run finished. The status is:  Succeeded
    
    ResourceGroupName : ADFQuickStartRG
    DataFactoryName   : ADFQuickStartFactory
    RunId             : 00000000-0000-0000-0000-0000000000000
    PipelineName      : Adfv2QuickStartPipeline
    LastUpdated       : 8/27/2019 7:23:07 AM
    Parameters        : {}
    RunStart          : 8/27/2019 7:22:56 AM
    RunEnd            : 8/27/2019 7:23:07 AM
    DurationInMs      : 11324
    Status            : Succeeded
    Message           : 
    
  2. 次のスクリプトを実行し、コピー アクティビティの実行の詳細 (たとえば、読み書きされたデータのサイズ) を取得します。

    Write-Output "Activity run details:"
    $Result = Get-AzDataFactoryV2ActivityRun -DataFactoryName $DataFactory.DataFactoryName -ResourceGroupName $ResGrp.ResourceGroupName -PipelineRunId $RunId -RunStartedAfter (Get-Date).AddMinutes(-30) -RunStartedBefore (Get-Date).AddMinutes(30)
    $Result
    
    Write-Output "Activity 'Output' section:"
    $Result.Output -join "`r`n"
    
    Write-Output "Activity 'Error' section:"
    $Result.Error -join "`r`n"
    
  3. アクティビティの実行の結果である次のサンプル出力のような出力が表示されることを確認します。

    ResourceGroupName : ADFQuickStartRG
    DataFactoryName   : ADFQuickStartFactory
    ActivityRunId     : 00000000-0000-0000-0000-000000000000
    ActivityName      : CopyFromBlobToBlob
    PipelineRunId     : 00000000-0000-0000-0000-000000000000
    PipelineName      : Adfv2QuickStartPipeline
    Input             : {source, sink, enableStaging}
    Output            : {dataRead, dataWritten, filesRead, filesWritten...}
    LinkedServiceName :
    ActivityRunStart  : 8/27/2019 7:22:58 AM
    ActivityRunEnd    : 8/27/2019 7:23:05 AM
    DurationInMs      : 6828
    Status            : Succeeded
    Error             : {errorCode, message, failureType, target}
    
    Activity 'Output' section:
    "dataRead": 20
    "dataWritten": 20
    "filesRead": 1
    "filesWritten": 1
    "sourcePeakConnections": 1
    "sinkPeakConnections": 1
    "copyDuration": 4
    "throughput": 0.01
    "errors": []
    "effectiveIntegrationRuntime": "DefaultIntegrationRuntime (Central US)"
    "usedDataIntegrationUnits": 4
    "usedParallelCopies": 1
    "executionDetails": [
      {
        "source": {
          "type": "AzureBlobStorage"
        },
        "sink": {
          "type": "AzureBlobStorage"
        },
        "status": "Succeeded",
        "start": "2019-08-27T07:22:59.1045645Z",
        "duration": 4,
        "usedDataIntegrationUnits": 4,
        "usedParallelCopies": 1,
        "detailedDurations": {
          "queuingDuration": 3,
          "transferDuration": 1
        }
      }
    ]
    
    Activity 'Error' section:
    "errorCode": ""
    "message": ""
    "failureType": ""
    "target": "CopyFromBlobToBlob"
    

デプロイされているリソースを確認する

このパイプラインは、adftutorial BLOB コンテナーに対して output フォルダーを自動的に作成します。 そのうえで、input フォルダーから output フォルダーに emp.txt ファイルをコピーします。

  1. Azure portal の adftutorial コンテナー ページで、 [最新の情報に更新] を選択して出力フォルダーを表示します。

    コンテナー ページのスクリーンショット。ここでページを最新の情報に更新することができます。

  2. フォルダー一覧で、 [output] を選択します。

  3. emp.txt が output フォルダーにコピーされていることを確認します。

    output フォルダーの内容を示すスクリーンショット。

リソースをクリーンアップする

このクイックスタートで作成したリソースは、2 とおりの方法でクリーンアップすることができます。 Azure リソース グループを削除した場合、そのリソース グループに含まれたすべてのリソースが対象となります。 他のリソースをそのまま維持する場合は、このチュートリアルで作成したデータ ファクトリだけを削除してください。

リソース グループを削除すると、その中のデータ ファクトリも含めて、すべてのリソースが削除されます。 次のコマンドを実行して、リソース グループ全体を削除します。

Remove-AzResourceGroup -ResourceGroupName $resourcegroupname

注意

リソース グループの削除には、しばらく時間がかかることがあります。 処理が完了するまでお待ちください。

リソース グループ全体ではなく、データ ファクトリだけを削除する場合は、次のコマンドを実行します。

Remove-AzDataFactoryV2 -Name $dataFactoryName -ResourceGroupName $resourceGroupName

次のステップ

このサンプルのパイプラインは、Azure Blob Storage 内のある場所から別の場所にデータをコピーするものです。 より多くのシナリオで Data Factory を使用する方法については、チュートリアルを参照してください。