Azure Data Factory を使用して Google Cloud Storage からデータをコピーするCopy data from Google Cloud Storage by using Azure Data Factory

適用対象: Azure Data Factory Azure Synapse Analytics (プレビュー)

この記事では、Google Cloud Storage (GCS) からデータをコピーする方法について説明します。This article outlines how to copy data from Google Cloud Storage (GCS). Azure Data Factory については、入門記事でをご覧ください。To learn about Azure Data Factory, read the introductory article.

サポートされる機能Supported capabilities

この Google Cloud Storage コネクタは、次のアクティビティでサポートされます。This Google Cloud Storage connector is supported for the following activities:

具体的には、この Google Cloud Storage コネクタでは、ファイルをそのままコピーするか、サポートされているファイル形式と圧縮コーデックを使用してファイルを解析することをサポートしています。Specifically, this Google Cloud Storage connector supports copying files as is or parsing files with the supported file formats and compression codecs. GCS の S3 互換の相互運用性が利用されます。It takes advantage of GCS's S3-compatible interoperability.

前提条件Prerequisites

Google Cloud Storage アカウントに対して次の設定が必要となります。The following setup is required on your Google Cloud Storage account:

  1. Google Cloud Storage アカウントの相互運用性を有効にします。Enable interoperability for your Google Cloud Storage account
  2. ターゲット GCS バケットからコピーするデータを含む既定のプロジェクトを設定します。Set the default project that contains the data you want to copy from the target GCS bucket.
  3. GCP で Cloud IAM を使用して、サービス アカウントを作成し、適切なレベルのアクセス許可を定義します。Create a service account and define the right levels of permissions by using Cloud IAM on GCP.
  4. このサービス アカウントのアクセス キーを生成します。Generate the access keys for this service account.

Google Cloud Storage のアクセス キーを取得する

必要なアクセス許可Required permissions

Google Cloud Storage からデータをコピーするには、オブジェクト操作に対する次のアクセス許可が付与されている必要があります: storage.objects.get および storage.objects.listTo copy data from Google Cloud Storage, make sure you've been granted the following permissions for object operations: storage.objects.get and storage.objects.list.

Data Factory UI を使用して作成する場合は、リンクされたサービスへの接続のテストやルートからの参照などの操作に対して、追加の storage.buckets.list アクセス許可が必要です。If you use Data Factory UI to author, additional storage.buckets.list permission is required for operations like testing connection to linked service and browsing from root. このアクセス許可を付与しない場合は、UI から [ファイル パスへの接続をテスト] または [指定されたパスから参照] オプションを選択できます。If you don't want to grant this permission, you can choose "Test connection to file path" or "Browse from specified path" options from the UI.

Google Cloud Storage のロールと関連するアクセス許可の完全な一覧については、Google Cloud サイトの「Cloud Storage に適用される IAM のロール」を参照してください。For the full list of Google Cloud Storage roles and associated permissions, see IAM roles for Cloud Storage on the Google Cloud site.

作業の開始Getting started

パイプラインでコピー アクティビティを実行するには、次のいずれかのツールまたは SDK を使用します。To perform the Copy activity with a pipeline, you can use one of the following tools or SDKs:

次のセクションでは、Google Cloud Storage に固有の Data Factory エンティティを定義するために使用されるプロパティについて詳しく説明します。The following sections provide details about properties that are used to define Data Factory entities specific to Google Cloud Storage.

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

Google Cloud Storage のリンクされたサービスでは、次のプロパティがサポートされます。The following properties are supported for Google Cloud Storage linked services:

プロパティProperty 説明Description 必須Required
typetype type プロパティは、GoogleCloudStorage に設定する必要があります。The type property must be set to GoogleCloudStorage. はいYes
accessKeyIdaccessKeyId シークレット アクセス キーの ID。ID of the secret access key. アクセス キーとシークレットの見つけ方については、「前提条件」を参照してください。To find the access key and secret, see Prerequisites. はいYes
secretAccessKeysecretAccessKey シークレット アクセス キー自体。The secret access key itself. このフィールドを SecureString としてマークして Data Factory に安全に保管するか、Azure Key Vault に格納されているシークレットを参照します。Mark this field as SecureString to store it securely in Data Factory, or reference a secret stored in Azure Key Vault. はいYes
serviceUrlserviceUrl カスタムの GCS エンドポイントを https://storage.googleapis.com として指定します。Specify the custom GCS endpoint as https://storage.googleapis.com. はいYes
connectViaconnectVia データ ストアに接続するために使用される統合ランタイムThe integration runtime to be used to connect to the data store. データ ストアがプライベート ネットワーク内にある場合、Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます。You can use the Azure integration runtime or the self-hosted integration runtime (if your data store is in a private network). このプロパティが指定されていない場合は、サービスでは、既定の Azure Integration Runtime が使用されます。If this property isn't specified, the service uses the default Azure integration runtime. いいえNo

次に例を示します。Here's an example:

{
    "name": "GoogleCloudStorageLinkedService",
    "properties": {
        "type": "GoogleCloudStorage",
        "typeProperties": {
            "accessKeyId": "<access key id>",
            "secretAccessKey": {
                "type": "SecureString",
                "value": "<secret access key>"
            },
            "serviceUrl": "https://storage.googleapis.com"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

Azure Data Factory では次のファイル形式がサポートされます。Azure Data Factory supports the following file formats. 形式ベースの設定については、各記事を参照してください。Refer to each article for format-based settings.

Google Cloud Storage では、形式ベースのデータセットの location 設定において、次のプロパティがサポートされています。The following properties are supported for Google Cloud Storage under location settings in a format-based dataset:

プロパティProperty 説明Description 必須Required
typetype データセットの locationtype プロパティは、GoogleCloudStorageLocation に設定する必要があります。The type property under location in the dataset must be set to GoogleCloudStorageLocation. はいYes
bucketNamebucketName GCS バケットの名前。The GCS bucket name. はいYes
folderPathfolderPath 特定のバケットの下のフォルダーへのパス。The path to folder under the given bucket. ワイルドカードを使用してフォルダーをフィルター処理する場合は、この設定をスキップし、アクティビティのソース設定でこれを指定します。If you want to use a wildcard to filter the folder, skip this setting and specify that in activity source settings. いいえNo
fileNamefileName 特定のバケットおよびフォルダー パスの下のファイル名。The file name under the given bucket and folder path. ワイルドカードを使用してファイルをフィルター処理する場合は、この設定をスキップし、アクティビティのソース設定でこれを指定します。If you want to use a wildcard to filter the files, skip this setting and specify that in activity source settings. いいえNo

例:Example:

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

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

アクティビティの定義に利用できるセクションとプロパティの完全な一覧については、パイプラインに関する記事を参照してください。For a full list of sections and properties available for defining activities, see the Pipelines article. このセクションでは、Google Cloud Storage ソースがサポートするプロパティの一覧を示します。This section provides a list of properties that the Google Cloud Storage source supports.

ソース タイプとしての Google Cloud StorageGoogle Cloud Storage as a source type

Azure Data Factory では次のファイル形式がサポートされます。Azure Data Factory supports the following file formats. 形式ベースの設定については、各記事を参照してください。Refer to each article for format-based settings.

Google Cloud Storage では、形式ベースのコピー ソースの storeSettings 設定において、次のプロパティがサポートされています。The following properties are supported for Google Cloud Storage under storeSettings settings in a format-based copy source:

プロパティProperty 説明Description 必須Required
typetype storeSettingstype プロパティは GoogleCloudStorageReadSettings に設定する必要があります。The type property under storeSettings must be set to GoogleCloudStorageReadSettings. はいYes
コピーするファイルを特定する:Locate the files to copy:
オプション 1: 静的パスOPTION 1: static path
データセットに指定されている所定のバケットまたはフォルダー/ファイル パスからコピーします。Copy from the given bucket or folder/file path specified in the dataset. バケットまたはフォルダーからすべてのファイルをコピーする場合は、さらに * として wildcardFileName を指定します。If you want to copy all files from a bucket or folder, additionally specify wildcardFileName as *.
オプション 2: GCS プレフィックスOPTION 2: GCS prefix
- prefix- prefix
ソース GCS ファイルをフィルター処理するために、データセットで構成されている、指定されたバケットにある GCS キー名のプレフィックス。Prefix for the GCS key name under the given bucket configured in the dataset to filter source GCS files. 名前が bucket_in_dataset/this_prefix で始まる GCS キーが選択されます。GCS keys whose names start with bucket_in_dataset/this_prefix are selected. ワイルドカード フィルターより優れたパフォーマンスを提供する GCS サービス側のフィルターを利用します。It utilizes GCS's service-side filter, which provides better performance than a wildcard filter. いいえNo
オプション 3: ワイルドカードOPTION 3: wildcard
- wildcardFolderPath- wildcardFolderPath
ソース フォルダーをフィルター処理するためにデータセットで構成されている、特定のバケットの下のワイルドカード文字を含むフォルダーのパス。The folder path with wildcard characters under the given bucket configured in a dataset to filter source folders.
使用できるワイルドカードは、* (ゼロ文字以上の文字に一致) と ? (ゼロ文字または 1 文字に一致) です。Allowed wildcards are: * (matches zero or more characters) and ? (matches zero or single character). フォルダー名にワイルドカードまたはこのエスケープ文字が含まれている場合は、^ を使用してエスケープします。Use ^ to escape if your folder name has a wildcard or this escape character inside.
フォルダーとファイル フィルターの例」の他の例をご覧ください。See more examples in Folder and file filter examples.
いいえNo
オプション 3: ワイルドカードOPTION 3: wildcard
- wildcardFileName- wildcardFileName
ソース ファイルをフィルター処理するための、特定のバケットおよびフォルダー パス (またはワイルドカード フォルダー パス) の下のワイルドカード文字を含むファイル名。The file name with wildcard characters under the given bucket and folder path (or wildcard folder path) to filter source files.
使用できるワイルドカードは、* (ゼロ文字以上の文字に一致) と ? (ゼロ文字または 1 文字に一致) です。Allowed wildcards are: * (matches zero or more characters) and ? (matches zero or single character). フォルダー名にワイルドカードまたはこのエスケープ文字が含まれている場合は、^ を使用してエスケープします。Use ^ to escape if your folder name has a wildcard or this escape character inside. フォルダーとファイル フィルターの例」の他の例をご覧ください。See more examples in Folder and file filter examples.
はいYes
オプション 3: ファイルの一覧OPTION 3: a list of files
- fileListPath- fileListPath
指定されたファイル セットをコピーすることを示します。Indicates to copy a given file set. コピーするファイルの一覧を含むテキスト ファイルをポイントします。データセットで構成されているパスへの相対パスであるファイルを 1 行につき 1 つずつ指定します。Point to a text file that includes a list of files you want to copy, one file per line, which is the relative path to the path configured in the dataset.
このオプションを使用している場合は、データ セットにファイル名を指定しないでください。When you're using this option, do not specify the file name in the dataset. その他の例については、ファイル リストの例を参照してください。See more examples in File list examples.
いいえNo
追加の設定:Additional settings:
recursiverecursive データをサブフォルダーから再帰的に読み取るか、指定したフォルダーからのみ読み取るかを指定します。Indicates whether the data is read recursively from the subfolders or only from the specified folder. recursivetrue に設定され、シンクがファイル ベースのストアである場合、空のフォルダーおよびサブフォルダーはシンクでコピーも作成もされないことに注意してください。Note that when recursive is set to true and the sink is a file-based store, an empty folder or subfolder isn't copied or created at the sink.
使用可能な値: true (既定値) および falseAllowed values are true (default) and false.
fileListPath を構成する場合、このプロパティは適用されません。This property doesn't apply when you configure fileListPath.
いいえNo
deleteFilesAfterCompletiondeleteFilesAfterCompletion 宛先ストアに正常に移動した後、バイナリ ファイルをソース ストアから削除するかどうかを示します。Indicates whether the binary files will be deleted from source store after successfully moving to the destination store. ファイルの削除はファイルごとに行われるので、コピー操作が失敗した場合、一部のファイルが既に宛先にコピーされソースからは削除されているが、他のファイルはまだソース ストアに残っていることがわかります。The file deletion is per file, so when copy activity fails, you will see some files have already been copied to the destination and deleted from source, while others are still remaining on source store.
このプロパティは、バイナリ ファイルのコピー シナリオでのみ有効です。This property is only valid in binary files copy scenario. 既定値: false。The default value: false.
いいえNo
modifiedDatetimeStartmodifiedDatetimeStart ファイルは、属性 (最終変更日時) に基づいてフィルター処理されます。Files are filtered based on the attribute: last modified.
最終変更時刻が modifiedDatetimeStart から modifiedDatetimeEnd の間に含まれる場合は、ファイルが選択されます。The files will be selected if their last modified time is within the time range between modifiedDatetimeStart and modifiedDatetimeEnd. 時刻は "2018-12-01T05:00:00Z" の形式で UTC タイム ゾーンに適用されます。The time is applied to the UTC time zone in the format of "2018-12-01T05:00:00Z".
プロパティは、ファイル属性フィルターをデータセットに適用しないことを意味する NULL にすることができます。The properties can be NULL, which means no file attribute filter will be applied to the dataset. modifiedDatetimeStart に datetime 値が設定されており、modifiedDatetimeEndNULL の場合は、最終変更日時属性が datetime 値以上であるファイルが選択されます。When modifiedDatetimeStart has a datetime value but modifiedDatetimeEnd is NULL, the files whose last modified attribute is greater than or equal to the datetime value will be selected. modifiedDatetimeEnd に datetime 値が設定されており、modifiedDatetimeStartNULL の場合は、最終変更日時属性が datetime 値未満であるファイルが選択されます。When modifiedDatetimeEnd has a datetime value but modifiedDatetimeStart is NULL, the files whose last modified attribute is less than the datetime value will be selected.
fileListPath を構成する場合、このプロパティは適用されません。This property doesn't apply when you configure fileListPath.
いいえNo
modifiedDatetimeEndmodifiedDatetimeEnd 上記と同じです。Same as above. いいえNo
enablePartitionDiscoveryenablePartitionDiscovery パーティション分割されているファイルの場合、ファイル パスからのパーティションを解析し、追加のソース列として追加するかどうかを指定します。For files that are partitioned, specify whether to parse the partitions from the file path and add them as additional source columns.
指定できる値は false (既定値) と true です。Allowed values are false (default) and true.
いいえNo
partitionRootPathpartitionRootPath パーティション検出が有効になっている場合、パーティション分割されているフォルダーをデータ列として読み取る目的で絶対ルート パスを指定します。When partition discovery is enabled, specify the absolute root path in order to read partitioned folders as data columns.

指定されない場合、既定では、If it is not specified, by default,
- ソースでファイルのデータセットまたはリストにあるファイル パスを使用するとき、パーティション ルート パスはデータセットに構成されているパスになります。- When you use file path in dataset or list of files on source, partition root path is the path configured in dataset.
- ワイルドカード フォルダー フィルターを使用する場合、パーティションのルート パスは最初のワイルドカードの前のサブパスです。- When you use wildcard folder filter, partition root path is the sub-path before the first wildcard.

たとえば、データセット内のパスを "root/folder/year=2020/month=08/day=27" として構成するとします。For example, assuming you configure the path in dataset as "root/folder/year=2020/month=08/day=27":
- パーティション ルート パスを "root/folder/year=2020" として指定する場合、コピー アクティビティによって、ファイル内の列に加え、さらに 2 つの列、monthday がそれぞれ値 "08" と "27" で生成されます。- If you specify partition root path as "root/folder/year=2020", copy activity will generate two more columns month and day with value "08" and "27" respectively, in addition to the columns inside the files.
- パーティション ルート パスが指定されない場合、追加の列は生成されません。- If partition root path is not specified, no extra column will be generated.
いいえNo
maxConcurrentConnectionsmaxConcurrentConnections ストレージへのコンカレント接続数。The number of the concurrent connections to storage. データ ストアへのコンカレント接続を制限する場合にのみ指定します。Specify only when you want to limit concurrent connections to the data store. いいえNo

例:Example:

"activities":[
    {
        "name": "CopyFromGoogleCloudStorage",
        "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": "GoogleCloudStorageReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

フォルダーとファイル フィルターの例Folder and file filter examples

このセクションでは、ワイルドカード フィルターを使用した結果のフォルダーのパスとファイル名の動作について説明します。This section describes the resulting behavior of the folder path and file name with wildcard filters.

bucketbucket keykey recursiverecursive ソースのフォルダー構造とフィルターの結果 (太字のファイルが取得されます)Source folder structure and filter result (files in bold are retrieved)
bucketbucket Folder*/* falsefalse bucketbucket
    FolderA    FolderA
        File1.csv        File1.csv
        File2.json        File2.json
        Subfolder1        Subfolder1
            File3.csv            File3.csv
            File4.json            File4.json
            File5.csv            File5.csv
    AnotherFolderB    AnotherFolderB
        File6.csv        File6.csv
bucketbucket Folder*/* truetrue bucketbucket
    FolderA    FolderA
        File1.csv        File1.csv
        File2.json        File2.json
        Subfolder1        Subfolder1
            File3.csv            File3.csv
            File4.json            File4.json
            File5.csv            File5.csv
    AnotherFolderB    AnotherFolderB
        File6.csv        File6.csv
bucketbucket Folder*/*.csv falsefalse bucketbucket
    FolderA    FolderA
        File1.csv        File1.csv
        File2.json        File2.json
        Subfolder1        Subfolder1
            File3.csv            File3.csv
            File4.json            File4.json
            File5.csv            File5.csv
    AnotherFolderB    AnotherFolderB
        File6.csv        File6.csv
bucketbucket Folder*/*.csv truetrue bucketbucket
    FolderA    FolderA
        File1.csv        File1.csv
        File2.json        File2.json
        Subfolder1        Subfolder1
            File3.csv            File3.csv
            File4.json            File4.json
            File5.csv            File5.csv
    AnotherFolderB    AnotherFolderB
        File6.csv        File6.csv

ファイル リストの例File list examples

このセクションでは、コピー アクティビティのソースでファイル リスト パスを使用した結果の動作について説明します。This section describes the resulting behavior of using a file list path in the Copy activity source.

次のソース フォルダー構造があり、太字のファイルをコピーするとします。Assume that you have the following source folder structure and want to copy the files in bold:

サンプルのソース構造Sample source structure FileListToCopy.txt のコンテンツContent in FileListToCopy.txt Data Factory の構成Data Factory configuration
bucketbucket
    FolderA    FolderA
        File1.csv        File1.csv
        File2.json        File2.json
        Subfolder1        Subfolder1
            File3.csv            File3.csv
            File4.json            File4.json
            File5.csv            File5.csv
    Metadata    Metadata
        FileListToCopy.txt        FileListToCopy.txt
File1.csvFile1.csv
Subfolder1/File3.csvSubfolder1/File3.csv
Subfolder1/File5.csvSubfolder1/File5.csv
データセット内:In dataset:
- バケット: bucket- Bucket: bucket
- フォルダー パス: FolderA- Folder path: FolderA

コピー アクティビティ ソース内:In copy activity source:
- ファイル リストのパス: bucket/Metadata/FileListToCopy.txt- File list path: bucket/Metadata/FileListToCopy.txt

ファイル リストのパスは、コピーするファイルの一覧を含む同じデータ ストア内のテキスト ファイルをポイントします。データセットで構成されているパスへの相対パスで 1 行につき 1 つのファイルを指定します。The file list path points to a text file in the same data store that includes a list of files you want to copy, one file per line, with the relative path to the path configured in the dataset.

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

プロパティの詳細については、Lookup アクティビティに関するページを参照してください。To learn details about the properties, check Lookup activity.

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

プロパティの詳細については、GetMetadata アクティビティに関するページを参照してください。To learn details about the properties, check GetMetadata activity.

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

プロパティの詳細については、Delete アクティビティに関するページを参照してください。To learn details about the properties, check Delete activity.

レガシ モデルLegacy models

Amazon S3 コネクタを使用して Google Cloud Storage からデータをコピーした場合でも、これは下位互換性のために引き続きサポートされます。If you were using an Amazon S3 connector to copy data from Google Cloud Storage, it's still supported as is for backward compatibility. 前述の新しいモデルを使用することをお勧めします。We suggest that you use the new model mentioned earlier. Data Factory 作成 UI は、新しいモデルの生成に切り替えられました。The Data Factory authoring UI has switched to generating the new model.

次のステップNext steps

Azure Data Factory のコピー アクティビティによってソースおよびシンクとしてサポートされるデータ ストアの一覧については、サポートされるデータ ストアをご覧ください。For a list of data stores that the Copy activity in Azure Data Factory supports as sources and sinks, see Supported data stores.