Azure Data Factory または Azure Synapse Analytics を使用して Google Cloud Storage のデータをコピーする

適用対象: Azure Data Factory Azure Synapse Analytics

この記事では、Google Cloud Storage (GCS) からデータをコピーする方法について説明します。 詳細については、Azure Data Factory および Azure Synapse Analytics の概要記事を参照してください。

サポートされる機能

この Google Cloud Storage コネクタでは、次の機能をサポートしています。

サポートされる機能 IR
Copy アクティビティ (ソース/-) ① ②
Lookup アクティビティ ① ②
GetMetadata アクティビティ ① ②
アクティビティを削除する ① ②

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

具体的には、この Google Cloud Storage コネクタでは、ファイルをそのままコピーするか、サポートされているファイル形式と圧縮コーデックを使用してファイルを解析することをサポートしています。 GCS の S3 互換の相互運用性が利用されます。

前提条件

Google Cloud Storage アカウントに対して次の設定が必要となります。

  1. Google Cloud Storage アカウントの相互運用性を有効にします。
  2. ターゲット GCS バケットからコピーするデータを含む既定のプロジェクトを設定します。
  3. GCP で Cloud IAM を使用して、サービス アカウントを作成し、適切なレベルのアクセス許可を定義します。
  4. このサービス アカウントのアクセス キーを生成します。

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

必要なアクセス許可

Google Cloud Storage からデータをコピーするには、オブジェクト操作に対する次のアクセス許可が付与されている必要があります: storage.objects.get および storage.objects.list

UI を使用して作成する場合は、リンクされたサービスへの接続のテストやルートからの参照などの操作に対して、追加の storage.buckets.list アクセス許可が必要です。 このアクセス許可を付与しない場合は、UI から [ファイル パスへの接続をテスト] または [指定されたパスから参照] オプションを選択できます。

Google Cloud Storage のロールと関連するアクセス許可の完全な一覧については、Google Cloud サイトの「Cloud Storage に適用される IAM のロール」を参照してください。

作業の開始

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

UI を使用して Google Cloud Storage のリンク サービスを作成する

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

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

  2. Google を検索し、Google Cloud Storage (S3 API) コネクタを選択します。

    Google Cloud Storage (S3 API) コネクタを選択します。

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

    Google Cloud Storage のリンク サービスを構成します。

コネクタの構成の詳細

次のセクションでは、Google Cloud Storage に固有の Data Factory エンティティを定義するために使用されるプロパティについて詳しく説明します。

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

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

プロパティ 説明 必須
type type プロパティは、GoogleCloudStorage に設定する必要があります。 はい
accessKeyId シークレット アクセス キーの ID。 アクセス キーとシークレットの見つけ方については、「前提条件」を参照してください。 はい
secretAccessKey シークレット アクセス キー自体。 このフィールドを SecureString とマークして安全に保存するか、Azure Key Vault に保存されているシークレットを参照します。 はい
serviceUrl カスタムの GCS エンドポイントを https://storage.googleapis.com として指定します。 はい
connectVia データ ストアに接続するために使用される統合ランタイム。 データ ストアがプライベート ネットワーク内にある場合、Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます。 このプロパティが指定されていない場合は、サービスでは、既定の Azure Integration Runtime が使用されます。 いいえ

次に例を示します。

{
    "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"
        }
    }
}

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

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

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

プロパティ 説明 必須
type データセットの locationtype プロパティは、GoogleCloudStorageLocation に設定する必要があります。 はい
bucketName GCS バケットの名前。 はい
folderPath 特定のバケットの下のフォルダーへのパス。 ワイルドカードを使用してフォルダーをフィルター処理する場合は、この設定をスキップし、アクティビティのソース設定でこれを指定します。 いいえ
fileName 特定のバケットおよびフォルダー パスの下のファイル名。 ワイルドカードを使用してファイルをフィルター処理する場合は、この設定をスキップし、アクティビティのソース設定でこれを指定します。 いいえ

例:

{
    "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"
        }
    }
}

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

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

ソース タイプとしての Google Cloud Storage

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

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

プロパティ 説明 必須
type storeSettingstype プロパティは GoogleCloudStorageReadSettings に設定する必要があります。 はい
コピーするファイルを特定する:
オプション 1: 静的パス
データセットに指定されている所定のバケットまたはフォルダー/ファイル パスからコピーします。 バケットまたはフォルダーからすべてのファイルをコピーする場合は、さらに * として wildcardFileName を指定します。
オプション 2: GCS プレフィックス
- prefix
ソース GCS ファイルをフィルター処理するために、データセットで構成されている、指定されたバケットにある GCS キー名のプレフィックス。 名前が bucket_in_dataset/this_prefix で始まる GCS キーが選択されます。 ワイルドカード フィルターより優れたパフォーマンスを提供する GCS サービス側のフィルターを利用します。 いいえ
オプション 3: ワイルドカード
- wildcardFolderPath
ソース フォルダーをフィルター処理するためにデータセットで構成されている、特定のバケットの下のワイルドカード文字を含むフォルダーのパス。
使用できるワイルドカードは、* (ゼロ文字以上の文字に一致) と ? (ゼロ文字または 1 文字に一致) です。 フォルダー名にワイルドカードまたはこのエスケープ文字が含まれている場合は、^ を使用してエスケープします。
フォルダーとファイル フィルターの例」の他の例をご覧ください。
いいえ
オプション 3: ワイルドカード
- wildcardFileName
ソース ファイルをフィルター処理するための、特定のバケットおよびフォルダー パス (またはワイルドカード フォルダー パス) の下のワイルドカード文字を含むファイル名。
使用できるワイルドカードは、* (ゼロ文字以上の文字に一致) と ? (ゼロ文字または 1 文字に一致) です。 ファイル名にワイルドカードまたはこのエスケープ文字が含まれている場合は、^ を使用してエスケープします。 「フォルダーとファイル フィルターの例」の他の例をご覧ください。
はい
オプション 3: ファイルの一覧
- fileListPath
指定されたファイル セットをコピーすることを示します。 コピーするファイルの一覧を含むテキスト ファイルをポイントします。データセットで構成されているパスへの相対パスであるファイルを 1 行につき 1 つずつ指定します。
このオプションを使用している場合は、データ セットにファイル名を指定しないでください。 その他の例については、ファイル リストの例を参照してください。
いいえ
追加の設定:
recursive データをサブフォルダーから再帰的に読み取るか、指定したフォルダーからのみ読み取るかを指定します。 recursivetrue に設定され、シンクがファイル ベースのストアである場合、空のフォルダーおよびサブフォルダーはシンクでコピーも作成もされないことに注意してください。
使用可能な値: true (既定値) および false
fileListPath を構成する場合、このプロパティは適用されません。
いいえ
deleteFilesAfterCompletion 宛先ストアに正常に移動した後、バイナリ ファイルをソース ストアから削除するかどうかを示します。 ファイルの削除はファイルごとに行われるので、コピー操作が失敗した場合、一部のファイルが既に宛先にコピーされソースからは削除されているが、他のファイルはまだソース ストアに残っていることがわかります。
このプロパティは、バイナリ ファイルのコピー シナリオでのみ有効です。 既定値: false。
いいえ
modifiedDatetimeStart ファイルは、属性 (最終変更日時) に基づいてフィルター処理されます。
ファイルは、最終変更日時が modifiedDatetimeStart と同じかそれよりも後であり、modifiedDatetimeEnd よりも前である場合に選択されます。 時刻は "2018-12-01T05:00:00Z" の形式で UTC タイム ゾーンに適用されます。
プロパティは、ファイル属性フィルターをデータセットに適用しないことを意味する NULL にすることができます。 modifiedDatetimeStart に datetime 値が設定されており、modifiedDatetimeEndNULL の場合は、最終変更日時属性が datetime 値以上であるファイルが選択されます。 modifiedDatetimeEnd に datetime 値が設定されており、modifiedDatetimeStartNULL の場合は、最終変更日時属性が datetime 値未満であるファイルが選択されます。
fileListPath を構成する場合、このプロパティは適用されません。
いいえ
modifiedDatetimeEnd 上記と同じです。 いいえ
enablePartitionDiscovery パーティション分割されているファイルの場合は、ファイル パスのパーティションを解析し、それを追加のソース列として追加するかどうかを指定します。
指定できる値は false (既定値) と true です。
いいえ
partitionRootPath パーティション検出が有効になっている場合は、パーティション分割されたフォルダーをデータ列として読み取るための絶対ルート パスを指定します。

これが指定されていない場合は、既定で次のようになります。
- ソース上のデータセットまたはファイルの一覧内のファイル パスを使用する場合、パーティションのルート パスはそのデータセットで構成されているパスです。
- ワイルドカード フォルダー フィルターを使用する場合、パーティションのルート パスは最初のワイルドカードの前のサブパスです。

たとえば、データセット内のパスを "root/folder/year=2020/month=08/day=27" として構成するとします。
- パーティションのルート パスを "root/folder/year=2020" として指定した場合は、コピー アクティビティによって、ファイル内の列とは別に、それぞれ "08" と "27" の値を持つ monthday という 2 つの追加の列が生成されます。
- パーティションのルート パスが指定されない場合、追加の列は生成されません。
いいえ
maxConcurrentConnections アクティビティの実行中にデータ ストアに対して確立されたコンカレント接続数の上限。 コンカレント接続を制限する場合にのみ、値を指定します。 いいえ

例:

"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>"
            }
        }
    }
]

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

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

bucket key recursive ソースのフォルダー構造とフィルターの結果 (太字のファイルが取得されます)
bucket Folder*/* false bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv
bucket Folder*/* true bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv
bucket Folder*/*.csv false bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv
bucket Folder*/*.csv true bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    AnotherFolderB
        File6.csv

ファイル リストの例

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

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

サンプルのソース構造 FileListToCopy.txt のコンテンツ 構成
bucket
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    メタデータ
        FileListToCopy.txt
File1.csv
Subfolder1/File3.csv
Subfolder1/File5.csv
データセット内:
- バケット: bucket
- フォルダー パス: FolderA

コピー アクティビティ ソース内:
- ファイル リストのパス: bucket/Metadata/FileListToCopy.txt

ファイル リストのパスは、コピーするファイルの一覧を含む同じデータ ストア内のテキスト ファイルをポイントします。データセットで構成されているパスへの相対パスで 1 行につき 1 つのファイルを指定します。

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

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

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

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

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

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

レガシ モデル

Amazon S3 コネクタを使用して Google Cloud Storage からデータをコピーした場合でも、これは下位互換性のために引き続きサポートされます。 前述の新しいモデルを使用することをお勧めします。 作成 UI は、新しいモデルの生成に切り替えられました。

次のステップ

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