次の方法で共有


Azure Data Factory または Synapse Analytics を使用して Azure Cosmos DB for MongoDB との間でデータを双方向にコピーする

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

企業向けのオールインワン分析ソリューション、Microsoft Fabric の Data Factory をお試しください。 Microsoft Fabric は、データ移動からデータ サイエンス、リアルタイム分析、ビジネス インテリジェンス、レポートまで、あらゆるものをカバーしています。 無料で新しい試用版を開始する方法について説明します。

この記事では、Azure Data Factory および Synapse Analytics パイプラインで Copy アクティビティを使用して、Azure Cosmos DB for MongoDB との間で双方向にデータをコピーする方法について説明します。 この記事は、Copy アクティビティの概要を説明する Copy アクティビティに関する記事に基づいています。

注意

このコネクタでは、Azure Cosmos DB for MongoDB との間でのデータの双方向コピーのみがサポートされます。 Azure Cosmos DB for NoSQL については、Azure Cosmos DB for NoSQL コネクタに関する記事を参照してください。 その他の API の種類は現在サポートされていません。

サポートされる機能

この Azure Cosmos DB for MongoDB コネクタは、次の機能についてサポートされています。

サポートされる機能 IR マネージド プライベート エンドポイント
Copy アクティビティ (ソース/シンク) ① ②

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

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

Azure Cosmos DB for MongoDB コネクタを使用して次のことができます。

  • Azure Cosmos DB for MongoDB との間で双方向にデータをコピーします。
  • 挿入または upsert として Azure Cosmos DB に書き込みます。
  • JSON ドキュメントをインポートおよびエクスポートしたり、表形式データセットに、または表形式データセットからデータをコピーしたりします。 例としては、SQL データベースや CSV ファイルなどがあります。 JSON ファイルまたは他の Azure Cosmos DB コレクションをコピー先またはコピー元としてドキュメントをそのままコピーするには、「JSON ドキュメントをインポートまたはエクスポートする」を参照してください。

はじめに

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

UI を使用して Azure Cosmos DB for MongoDB のリンク サービスを作成する

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

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

  2. Azure Cosmos DB for MongoDB を検索し、そのコネクタを選択します。

    Azure Cosmos DB for MongoDB コネクタを選択する。

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

    Azure Cosmos DB for MongoDB へのリンク サービスを構成する。

コネクタの構成の詳細

以下のセクションでは、Azure Cosmos DB for MongoDB に固有の Data Factory エンティティを定義するために使用できるプロパティについて詳しく説明します。

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

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

プロパティ 内容 必須
type type プロパティは CosmosDbMongoDbApi に設定する必要があります。 はい
connectionString Azure Cosmos DB for MongoDB 用の接続文字列を指定します。 これは、Azure portal、Azure Cosmos DB ブレード、プライマリまたはセカンダリ接続文字列の順に移動して確認できます。
3\.2 サーバー バージョンの場合、文字列パターンは mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb です。
3\.6 以上のサーバー バージョンの場合、文字列パターンは mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<cosmosdb-name>@ です。

パスワードを Azure Key Vault に格納して、接続文字列から password 構成をプルすることもできます。 詳細については、「Azure Key Vault への資格情報の格納」を参照してください。
はい
database アクセスするデータベースの名前。 はい
isServerVersionAbove32 サーバー バージョンが 3.2 より新しいかどうかを指定します。 使用できる値は truefalse (既定値) です。 これにより、サービスで使用するドライバーが決定されます。 はい
connectVia データ ストアに接続するために使用される Integration Runtime。 Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます (データ ストアがプライベート ネットワークにある場合)。 このプロパティを指定しないと、既定の Azure Integration Runtime が使用されます。 いいえ

{
    "name": "CosmosDbMongoDBAPILinkedService",
    "properties": {
        "type": "CosmosDbMongoDbApi",
        "typeProperties": {
            "connectionString": "mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb",
            "database": "myDatabase",
            "isServerVersionAbove32": "false"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

データセットの定義に使用できるセクションとプロパティの完全な一覧については、「データセットとリンクされたサービス」を参照してください。 Azure Cosmos DB for MongoDB データセットでは、次のプロパティがサポートされます。

プロパティ 内容 必須
type データセットの type プロパティは、CosmosDbMongoDbApiCollection に設定する必要があります。 はい
collectionName Azure Cosmos DB コレクションの名前。 はい

{
    "name": "CosmosDbMongoDBAPIDataset",
    "properties": {
        "type": "CosmosDbMongoDbApiCollection",
        "typeProperties": {
            "collectionName": "<collection name>"
        },
        "schema": [],
        "linkedServiceName":{
            "referenceName": "<Azure Cosmos DB for MongoDB linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

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

このセクションでは、Azure Cosmos DB for MongoDB のソースとシンクでサポートされるプロパティの一覧を示します。

アクティビティの定義に利用できるセクションとプロパティの完全な一覧については、パイプラインに関する記事を参照してください。

ソースとしての Azure Cosmos DB for MongoDB

コピー アクティビティの source セクションでは、次のプロパティがサポートされます。

プロパティ 内容 必須
type コピー アクティビティのソースの type プロパティは CosmosDbMongoDbApiSource に設定する必要があります。 はい
filter クエリ演算子を使用して選択フィルターを指定します。 コレクション内のすべてのドキュメントを返すには、このパラメーターを省略するか、空のドキュメント ({}) を渡します。 いいえ
cursorMethods.project プロジェクションのドキュメントで返されるフィールドを指定します。 一致するドキュメント内のすべてのフィールドを返すには、このパラメーターを省略します。 いいえ
cursorMethods.sort 一致するドキュメントがクエリによって返される順序を指定します。 「cursor.sort()」を参照してください。 いいえ
cursorMethods.limit サーバーが返すドキュメントの最大数を指定します。 「cursor.limit()」を参照してください。 いいえ
cursorMethods.skip スキップするドキュメントの数と、MongoDB が結果を返すときの開始位置を指定します。 「cursor.skip()」を参照してください。 いいえ
batchSize MongoDB インスタンスからの応答の各バッチで返されるドキュメントの数を指定します。 ほとんどの場合、バッチ サイズを変更しても、ユーザーまたはアプリケーションへの影響はありません。 Azure Cosmos DB では各バッチのサイズが 40 MB を超過しないように制限されていますが、これはドキュメントが batchSize の数だけ存在するときの合計サイズなので、ドキュメントのサイズが大きくなる場合はこの値を減らしてください。 いいえ
(既定値は 100)

ヒント

ADF は、厳格モードでの BSON ドキュメントの利用をサポートしています。 フィルター クエリがシェル モードではなく厳格モードであることを確認してください。 詳細については、MongoDB のマニュアルを参照してください。

"activities":[
    {
        "name": "CopyFromCosmosDBMongoDBAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure Cosmos DB for MongoDB input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "CosmosDbMongoDbApiSource",
                "filter": "{datetimeData: {$gte: ISODate(\"2018-12-11T00:00:00.000Z\"),$lt: ISODate(\"2018-12-12T00:00:00.000Z\")}, _id: ObjectId(\"5acd7c3d0000000000000000\") }",
                "cursorMethods": {
                    "project": "{ _id : 1, name : 1, age: 1, datetimeData: 1 }",
                    "sort": "{ age : 1 }",
                    "skip": 3,
                    "limit": 3
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

シンクとしての Azure Cosmos DB for MongoDB

コピー アクティビティの sink セクションでは、次のプロパティがサポートされます。

プロパティ 内容 必須
type コピー アクティビティのシンクの type プロパティは CosmosDbMongoDbApiSink に設定する必要があります。 はい
writeBehavior Azure Cosmos DB にデータを書き込む方法を示します。 使用可能な値は、InsertUpsert です。

upsert の動作は、同じ _id を持つドキュメントが既に存在する場合、そのドキュメントを置き換えます。それ以外の場合は、ドキュメントを挿入します。

: 元のドキュメントまたは列マッピングで _id が指定されていない場合は、サービスによってドキュメントの _id が自動的に生成されます。 つまり、upsert が期待どおりに動作するには、ドキュメントに ID があることを確認する必要があります。
いいえ
(既定値は insert です)
writeBatchSize writeBatchSize プロパティにより、各バッチで書き込むドキュメントのサイズが制御されます。 パフォーマンスを向上させるには writeBatchSize の値を大きくしてみて、ドキュメントのサイズが大きい場合は値を小さくしてみます。 いいえ
(既定値は 10,000)
writeBatchTimeout タイムアウトするまでに一括挿入操作の完了を待つ時間です。許容される値は期間です。 いいえ
(既定値は 00:30:00 - 30 分)

ヒント

JSON ドキュメントをそのままインポートするには、「JSON ドキュメントをインポートまたはエクスポートする」セクションを参照してください。表形式のデータからコピーするには、「スキーマ マッピング」を参照してください。

"activities":[
    {
        "name": "CopyToCosmosDBMongoDBAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Document DB output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "CosmosDbMongoDbApiSink",
                "writeBehavior": "upsert"
            }
        }
    }
]

JSON ドキュメントのインポートとエクスポート

Azure Cosmos DB コネクタを使用して簡単に次のことができます。

  • 2 つの Azure Cosmos DB コレクション間でドキュメントをそのままコピーします。
  • MongoDB、Azure Blob Storage、Azure Data Lake Store、サービスでサポートされている他のファイルベースのストアなど、さまざまなソースから Azure Cosmos DB に JSON ドキュメントをインポートします。
  • JSON ドキュメントを Azure Cosmos DB コレクションからさまざまなファイル ベースのストアにエクスポートします。

スキーマに依存しないコピーを実行するには:

  • データ コピー ツールを使うときに、[Export as-is to JSON files or Azure Cosmos DB collection](JSON ファイルまたは Azure Cosmos DB コレクションにそのままエクスポートする) オプションを選択します。
  • アクティビティの作成を使用する場合は、ソースまたはシンクの対応するファイル ストアで JSON 形式を選択します。

スキーマ マッピング

Azure Cosmos DB for MongoDB から表形式のシンク、あるいはその逆の方向でデータをコピーするには、スキーマ マッピングに関するセクションを参照してください。

特に Azure Cosmos DB への書き込みでは、必ずソース データの正しいオブジェクト ID を Azure Cosmos DB に入力する必要があります。たとえば、SQL データベース テーブルに "id" 列があり、その値を MongoDB での挿入/アップサート用のドキュメント ID として使用したい場合は、MongoDB の厳格モードの定義 (_id.$oid) に従って、以下のように適切なスキーマ マッピングを設定する必要があります。

MongoDB シンクに ID をマップする

コピー アクティビティの実行後は、以下の BSON ObjectId がシンクに生成されます。

{
    "_id": ObjectId("592e07800000000000000000")
}

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