Azure Data Factory を使用して Azure Files との間でデータをコピーする

適用対象: Azure Data Factory Azure Synapse Analytics

この記事では、Azure Files をコピー先またはコピー元としてデータをコピーする方法について説明します。 Azure Data Factory については、入門記事でをご覧ください。

サポートされる機能

この Azure Files コネクタは、次の機能でサポートされます。

① Azure 統合ランタイム ② セルフホステッド統合ランタイム

Azure Files から、サポートされる任意のシンク データ ストアにデータをコピーしたり、サポートされる任意のソース データ ストアから Azure Files にデータをコピーしたりできます。 コピー アクティビティでソースおよびシンクとしてサポートされているデータ ストアの一覧については、「サポートされるデータ ストアと形式」を参照してください。

具体的には、この Azure Files コネクタは、以下をサポートします。

• アカウント キーまたはサービス Shared Access Signature (SAS) の認証を使用したファイルのコピー。
• ファイルをそのままコピーするか、サポートされているファイル形式と圧縮コーデックを使用したファイルの解析/生成。

作業の開始

パイプラインでコピー アクティビティを実行するには、次のいずれかのツールまたは SDK を使用します。

• データ コピー ツール
• Azure ポータル
• .NET SDK
• Python SDK
• Azure PowerShell
• REST API
• Azure Resource Manager テンプレート

UI を使用して Azure Files のリンク サービスを作成する

次の手順を使用して、Azure portal UI で Azure Files のリンク サービスを作成します。

1. Azure Data Factory または Synapse ワークスペースの [管理] タブに移動し、[リンク サービス] を選択して、[新規] をクリックします。

   • Azure Data Factory
   • Azure Synapse

   

2. ファイルを検索し、Azure File Storage と表示される Azure Files のコネクタを選択します。

   

3. サービスの詳細を構成し、接続をテストして、新しいリンク サービスを作成します。

   

コネクタの構成の詳細

以下のセクションでは、Azure Files に固有のエンティティの定義に使用されるプロパティについて詳しく説明します。

リンクされたサービスのプロパティ

Azure Files コネクタでは、次の認証の種類がサポートされています。 詳細については、対応するセクションをご覧ください。

• アカウント キー認証
• Shared Access Signature 認証
• システム割り当てマネージド ID 認証
• ユーザー割り当てマネージド ID 認証

アカウント キー認証

Data Factory では、Azure Files アカウント キー認証用に次のプロパティがサポートされています。

例:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountName>;AccountKey=<accountKey>;EndpointSuffix=core.windows.net;",
            "fileShare": "<file share name>"
        },
        "connectVia": {
          "referenceName": "<name of Integration Runtime>",
          "type": "IntegrationRuntimeReference"
        }
    }
}

例: アカウント キーを Azure Key Vault に格納する

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountname>;",
            "fileShare": "<file share name>",
            "accountKey": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName>" 
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }            
    }
}

Shared Access Signature 認証

Shared Access Signature を使用すると、ストレージ アカウント内のリソースへの委任アクセスが可能になります。 Shared Access Signature を使用して、ストレージ アカウントのオブジェクトへの制限付きアクセス許可を、期間を指定してクライアントに付与できます。 Shared Access Signature について詳しくは、Shared Access Signature のモデルの概要に関するページをご覧ください。

サービスでは、Shared Access Signature 認証を使用するための次のプロパティがサポートされています。

例:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "sasUri": {
                "type": "SecureString",
                "value": "<SAS URI of the resource e.g. https://<accountname>.file.core.windows.net/?sv=<storage version>&st=<start time>&se=<expire time>&sr=<resource>&sp=<permissions>&sip=<ip range>&spr=<protocol>&sig=<signature>>"
            },
            "fileShare": "<file share name>",
            "snapshot": "<snapshot version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

例: SAS トークンを Azure Key Vault に格納する

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "sasUri": {
                "type": "SecureString",
                "value": "<SAS URI of the Azure Storage resource without token e.g. https://<accountname>.file.core.windows.net/>"
            },
            "sasToken": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName with value of SAS token e.g. ?sv=<storage version>&st=<start time>&se=<expire time>&sr=<resource>&sp=<permissions>&sip=<ip range>&spr=<protocol>&sig=<signature>>" 
            },
            "fileShare": "<file share name>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

システム割り当てマネージド ID 認証

データ ファクトリや Synapse パイプラインは、Azure リソースのシステム割り当てマネージド ID に関連付けできます。これは、他の Azure サービスに対する認証のためのリソースを表します。 このシステム割り当てマネージド ID を Azure Files 認証に使用できます。 Azure リソース用マネージド ID の詳細については、Azure リソース用マネージド ID に関するページを参照してください。

システム割り当てマネージド ID 認証を使用するには、次の手順に従います。

1. ファクトリまたは Synapse ワークスペースと共に生成されたシステム割り当てマネージド ID のオブジェクト ID の値をコピーして、システム割り当てマネージド ID 情報を取得します。

2. Azure Files でマネージド ID にアクセス許可を付与します。 ロールの詳細については、こちらの記事を参照してください。

   • ソースとして、アクセス制御 (IAM) 内で、少なくともストレージ ファイル データ特権を持つ閲覧者のロールを許可します。
   • シンクとして、アクセス制御 (IAM) 内で、少なくともストレージ ファイル データ特権を持つ共同作成者のロールを許可します。

Azure Files のリンクされたサービスでは、次のプロパティがサポートされます。

例:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {            
            "serviceEndpoint": "https://<accountName>.file.core.windows.net/",
            "fileShare": "<file share name>",
            "snapshot": "<snapshot version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

ユーザー割り当てマネージド ID 認証

データ ファクトリは、1 つ以上のユーザー割り当てマネージド ID に割り当てることができます。 このユーザー割り当てマネージド ID を Azure Files 認証に使用できます。これにより、Azure Files にアクセスしてそこに (またはそこから) データをコピーできます。 Azure リソース用マネージド ID の詳細については、Azure リソース用マネージド ID に関するページを参照してください。

ユーザー割り当てマネージド ID 認証を使用するには、次の手順に従います。

1. 1 つ以上のユーザー割り当てマネージド ID を作成して、Azure Files でアクセス許可を付与します。 ロールの詳細については、こちらの記事を参照してください。

   • ソースとして、アクセス制御 (IAM) 内で、少なくともストレージ ファイル データ特権を持つ閲覧者のロールを許可します。
   • シンクとして、アクセス制御 (IAM) 内で、少なくともストレージ ファイル データ特権を持つ共同作成者のロールを許可します。

2. 1 つ以上のユーザー割り当てマネージド ID をデータ ファクトリに割り当てて、ユーザー割り当てマネージド ID ごとに資格情報を作成します。

Azure Files のリンクされたサービスでは、次のプロパティがサポートされます。

例:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {            
            "serviceEndpoint": "https://<accountName>.file.core.windows.net/",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            },
            "fileShare": "<file share name>",
            "snapshot": "<snapshot version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

レガシ モデル

例:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "host": "\\\\<storage name>.file.core.windows.net\\<file service name>",
            "userid": "AZURE\\<storage name>",
            "password": {
                "type": "SecureString",
                "value": "<storage access key>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

データセットのプロパティ

データセットを定義するために使用できるセクションとプロパティの完全な一覧については、データセットに関する記事をご覧ください。

Azure Data Factory では次のファイル形式がサポートされます。 形式ベースの設定については、各記事を参照してください。

• Avro 形式
• バイナリ形式
• 区切りテキスト形式
• Excel 形式
• JSON 形式
• ORC 形式
• Parquet 形式
• XML 形式

Azure Files では、形式ベースのデータセットの location 設定において、次のプロパティがサポートされています。

例:

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<Azure File Storage linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "AzureFileStorageLocation",
                "folderPath": "root/folder/subfolder"
            },
            "columnDelimiter": ",",
            "quoteChar": "\"",
            "firstRowAsHeader": true,
            "compressionCodec": "gzip"
        }
    }
}

コピー アクティビティのプロパティ

アクティビティの定義に利用できるセクションとプロパティの完全な一覧については、パイプラインに関する記事を参照してください。 このセクションでは、Azure Files のソースとシンクでサポートされるプロパティの一覧を示します。

Azure Files をソースとして

Azure Data Factory では次のファイル形式がサポートされます。 形式ベースの設定については、各記事を参照してください。

• Avro 形式
• バイナリ形式
• 区切りテキスト形式
• Excel 形式
• JSON 形式
• ORC 形式
• Parquet 形式
• XML 形式

Azure Files では、形式ベースのコピー ソースの storeSettings 設定において、次のプロパティがサポートされています。

例:

"activities":[
    {
        "name": "CopyFromAzureFileStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Delimited text input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "DelimitedTextSource",
                "formatSettings":{
                    "type": "DelimitedTextReadSettings",
                    "skipLineCount": 10
                },
                "storeSettings":{
                    "type": "AzureFileStorageReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Azure Files をシンクとして

Azure Data Factory では次のファイル形式がサポートされます。 形式ベースの設定については、各記事を参照してください。

• Avro 形式
• バイナリ形式
• 区切りテキスト形式
• JSON 形式
• ORC 形式
• Parquet 形式

Azure Files では、形式ベースのコピー リンクの storeSettings 設定において、次のプロパティがサポートされています。

例:

"activities":[
    {
        "name": "CopyToAzureFileStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Parquet output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "ParquetSink",
                "storeSettings":{
                    "type": "AzureFileStorageWriteSettings",
                    "copyBehavior": "PreserveHierarchy"
                }
            }
        }
    }
]

フォルダーとファイル フィルターの例

このセクションでは、ワイルドカード フィルターを使用した結果のフォルダーのパスとファイル名の動作について説明します。

ファイル リストの例

このセクションでは、コピー アクティビティのソースでファイル リスト パスを使用した結果の動作について説明します。

次のソース フォルダー構造があり、太字のファイルをコピーするとします。

recursive と copyBehavior の例

このセクションでは、recursive 値と copyBhavior 値の組み合わせごとに、Copy 操作で行われる動作について説明します。

Lookup アクティビティのプロパティ

プロパティの詳細については、Lookup アクティビティに関するページを参照してください。

GetMetadata アクティビティのプロパティ

プロパティの詳細については、GetMetadata アクティビティに関するページを参照してください。

Delete アクティビティのプロパティ

プロパティの詳細については、Delete アクティビティに関するページを参照してください。

レガシ モデル

レガシ データセット モデル

例:

{
    "name": "AzureFileStorageDataset",
    "properties": {
        "type": "FileShare",
        "linkedServiceName":{
            "referenceName": "<Azure File Storage linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "folderPath": "folder/subfolder/",
            "fileName": "*",
            "modifiedDatetimeStart": "2018-12-01T05:00:00Z",
            "modifiedDatetimeEnd": "2018-12-01T06:00:00Z",
            "format": {
                "type": "TextFormat",
                "columnDelimiter": ",",
                "rowDelimiter": "\n"
            },
            "compression": {
                "type": "GZip",
                "level": "Optimal"
            }
        }
    }
}

レガシ コピー アクティビティ ソース モデル

例:

"activities":[
    {
        "name": "CopyFromAzureFileStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure File Storage input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "FileSystemSource",
                "recursive": true
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

レガシ コピー アクティビティ シンク モデル

例:

"activities":[
    {
        "name": "CopyToAzureFileStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Azure File Storage output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "FileSystemSink",
                "copyBehavior": "PreserveHierarchy"
            }
        }
    }
]

関連するコンテンツ

Copy アクティビティでソースおよびシンクとしてサポートされるデータ ストアの一覧については、サポートされるデータ ストアに関するセクションを参照してください。