Azure Data Factory を使用して Azure Cosmos DB の MongoDB 用 API との間でデータを双方向にコピーするCopy data to or from Azure Cosmos DB's API for MongoDB by using Azure Data Factory

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

この記事では、Azure Data Factory のコピー アクティビティを使用して、Azure Cosmos DB の MongoDB 用 API をコピー元またはコピー先としてデータをコピーする方法について説明します。This article outlines how to use Copy Activity in Azure Data Factory to copy data from and to Azure Cosmos DB's API for MongoDB. この記事は、コピー アクティビティの概要が説明されている「Azure Data Factory のコピー アクティビティ」を基に作成されています。The article builds on Copy Activity in Azure Data Factory, which presents a general overview of Copy Activity.

注意

このコネクタでは、Azure Cosmos DB の MongoDB 用 API との間でのデータの双方向コピーのみがサポートされます。This connector only support copy data to/from Azure Cosmos DB's API for MongoDB. SQL API については、Cosmos DB SQL API コネクタに関する記事を参照してください。For SQL API, refer to Cosmos DB SQL API connector. 現在、他の種類の API はサポートされていません。Other API types are not supported now.

サポートされる機能Supported capabilities

Azure Cosmos DB の MongoDB 用 API のデータをサポートされる任意のシンク データ ストアにコピーしたり、サポートされる任意のソース データ ストアのデータを Azure Cosmos DB の MongoDB 用 API にコピーしたりできます。You can copy data from Azure Cosmos DB's API for MongoDB to any supported sink data store, or copy data from any supported source data store to Azure Cosmos DB's API for MongoDB. コピー アクティビティでソースおよびシンクとしてサポートされているデータ ストアの一覧については、「サポートされるデータ ストアと形式」を参照してください。For a list of data stores that Copy Activity supports as sources and sinks, see Supported data stores and formats.

Azure Cosmos DB の MongoDB 用 API コネクタを使用して次のことができます。You can use the Azure Cosmos DB's API for MongoDB connector to:

  • Azure Cosmos DB の MongoDB 用 API との間で双方向にデータをコピーします。Copy data from and to the Azure Cosmos DB's API for MongoDB.
  • 挿入または upsert として Azure Cosmos DB に書き込みます。Write to Azure Cosmos DB as insert or upsert.
  • JSON ドキュメントをインポートおよびエクスポートしたり、表形式データセットに、または表形式データセットからデータをコピーしたりします。Import and export JSON documents as-is, or copy data from or to a tabular dataset. 例としては、SQL データベースや CSV ファイルなどがあります。Examples include a SQL database and a CSV file. JSON ファイルまたは他の Azure Cosmos DB コレクションをコピー先またはコピー元としてドキュメントをそのままコピーするには、「JSON ドキュメントをインポートまたはエクスポートする」を参照してください。To copy documents as-is to or from JSON files or to or from another Azure Cosmos DB collection, see Import or export JSON documents.

はじめにGet started

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

以下のセクションでは、Azure Cosmos DB の MongoDB 用 API に固有の Data Factory エンティティを定義するために使用できるプロパティについて詳しく説明します。The following sections provide details about properties you can use to define Data Factory entities that are specific to Azure Cosmos DB's API for MongoDB.

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

Azure Cosmos DB の MongoDB 用 API のリンクされたサービスでは、次のプロパティがサポートされます。The following properties are supported for the Azure Cosmos DB's API for MongoDB linked service:

プロパティProperty 説明Description 必須Required
typetype type プロパティは CosmosDbMongoDbApi に設定する必要があります。The type property must be set to CosmosDbMongoDbApi. はいYes
connectionStringconnectionString Azure Cosmos DB の MongoDB 用 API 用の接続文字列を指定します。Specify the connection string for your Azure Cosmos DB's API for MongoDB. これは、Azure portal、Cosmos DB ブレード、プライマリまたはセカンダリの接続文字列の順に移動して確認できます。パターンは次のとおりです。mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.documents.azure.com:10255/?ssl=true&replicaSet=globaldbYou can find it in the Azure portal -> your Cosmos DB blade -> primary or secondary connection string, with the pattern of mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb.

パスワードを Azure Key Vault に格納して、接続文字列から  password  構成をプルすることもできます。You can also put a password in Azure Key Vault and pull the password configuration out of the connection string. 詳細については、「 Azure Key Vault への資格情報の格納 」を参照してください。 Refer to Store credentials in Azure Key Vault with more details.
はいYes
databasedatabase アクセスするデータベースの名前。Name of the database that you want to access. はいYes
connectViaconnectVia データ ストアに接続するために使用される Integration RuntimeThe Integration Runtime to use to connect to the data store. Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます (データ ストアがプライベート ネットワークにある場合)。You can use the Azure Integration Runtime or a self-hosted integration runtime (if your data store is located in a private network). このプロパティを指定しないと、既定の Azure Integration Runtime が使用されます。If this property isn't specified, the default Azure Integration Runtime is used. いいえNo

Example

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

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

データセットの定義に使用できるセクションとプロパティの完全な一覧については、「データセットとリンクされたサービス」を参照してください。For a full list of sections and properties that are available for defining datasets, see Datasets and linked services. Azure Cosmos DB の MongoDB 用 API データセットでは、次のプロパティがサポートされます。The following properties are supported for Azure Cosmos DB's API for MongoDB dataset:

プロパティProperty 説明Description 必須Required
typetype データセットの type プロパティは、CosmosDbMongoDbApiCollection に設定する必要があります。The type property of the dataset must be set to CosmosDbMongoDbApiCollection. はいYes
collectionNamecollectionName Azure Cosmos DB コレクションの名前。The name of the Azure Cosmos DB collection. はいYes

Example

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

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

このセクションでは、Azure Cosmos DB の MongoDB 用 API のソースとシンクでサポートされるプロパティの一覧を示します。This section provides a list of properties that the Azure Cosmos DB's API for MongoDB source and sink support.

アクティビティの定義に利用できるセクションとプロパティの完全な一覧については、パイプラインに関する記事を参照してください。For a full list of sections and properties that are available for defining activities, see Pipelines.

ソースとしての Azure Cosmos DB の MongoDB 用 APIAzure Cosmos DB's API for MongoDB as source

コピー アクティビティの source セクションでは、次のプロパティがサポートされます。The following properties are supported in the Copy Activity source section:

プロパティProperty 説明Description 必須Required
typetype コピー アクティビティのソースの type プロパティは CosmosDbMongoDbApiSource に設定する必要があります。The type property of the copy activity source must be set to CosmosDbMongoDbApiSource. はいYes
filterfilter クエリ演算子を使用して選択フィルターを指定します。Specifies selection filter using query operators. コレクション内のすべてのドキュメントを返すには、このパラメーターを省略するか、空のドキュメント ({}) を渡します。To return all documents in a collection, omit this parameter or pass an empty document ({}). いいえNo
cursorMethods.projectcursorMethods.project プロジェクションのドキュメントで返されるフィールドを指定します。Specifies the fields to return in the documents for projection. 一致するドキュメント内のすべてのフィールドを返すには、このパラメーターを省略します。To return all fields in the matching documents, omit this parameter. いいえNo
cursorMethods.sortcursorMethods.sort 一致するドキュメントがクエリによって返される順序を指定します。Specifies the order in which the query returns matching documents. cursor.sort()」を参照してください。Refer to cursor.sort(). いいえNo
cursorMethods.limitcursorMethods.limit サーバーが返すドキュメントの最大数を指定します。Specifies the maximum number of documents the server returns. cursor.limit()」を参照してください。Refer to cursor.limit(). いいえNo
cursorMethods.skipcursorMethods.skip スキップするドキュメントの数と、MongoDB が結果を返すときの開始位置を指定します。Specifies the number of documents to skip and from where MongoDB begins to return results. cursor.skip()」を参照してください。Refer to cursor.skip(). いいえNo
batchSizebatchSize MongoDB インスタンスからの応答の各バッチで返されるドキュメントの数を指定します。Specifies the number of documents to return in each batch of the response from MongoDB instance. ほとんどの場合、バッチ サイズを変更しても、ユーザーまたはアプリケーションへの影響はありません。In most cases, modifying the batch size will not affect the user or the application. Cosmos DB では各バッチのサイズが 40 MB を超過しないように制限されていますが、これはドキュメントが batchSize の数だけ存在するときの合計サイズなので、ドキュメントのサイズが大きくなる場合はこの値を減らしてください。Cosmos DB limits each batch cannot exceed 40MB in size, which is the sum of the batchSize number of documents' size, so decrease this value if your document size being large. いいえNo
(既定値は 100)(the default is 100)

ヒント

ADF は、厳格モードでの BSON ドキュメントの利用をサポートしています。ADF support consuming BSON document in Strict mode. フィルター クエリがシェル モードではなく厳格モードであることを確認してください。Make sure your filter query is in Strict mode instead of Shell mode. 詳細については、MongoDB のマニュアルを参照してください。More description can be found at MongoDB manual.

Example

"activities":[
    {
        "name": "CopyFromCosmosDBMongoDBAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure Cosmos DB's API 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 の MongoDB 用 APIAzure Cosmos DB's API for MongoDB as sink

コピー アクティビティの sink セクションでは、次のプロパティがサポートされます。The following properties are supported in the Copy Activity sink section:

プロパティProperty 説明Description 必須Required
typetype コピー アクティビティのシンクの type プロパティは CosmosDbMongoDbApiSink に設定する必要があります。The type property of the Copy Activity sink must be set to CosmosDbMongoDbApiSink. はいYes
writeBehaviorwriteBehavior Azure Cosmos DB にデータを書き込む方法を示します。Describes how to write data to Azure Cosmos DB. 使用可能な値は、InsertUpsert です。Allowed values: insert and upsert.

upsert の動作は、同じ _id を持つドキュメントが既に存在する場合、そのドキュメントを置き換えます。それ以外の場合は、ドキュメントを挿入します。The behavior of upsert is to replace the document if a document with the same _id already exists; otherwise, insert the document.

:元のドキュメントまたは列のマッピングで _id が指定されていない場合、Data Factory によってドキュメントの _id が自動的に生成されます。Note: Data Factory automatically generates an _id for a document if an _id isn't specified either in the original document or by column mapping. つまり、upsert が期待どおりに動作するには、ドキュメントに ID があることを確認する必要があります。This means that you must ensure that, for upsert to work as expected, your document has an ID.
いいえNo
(既定値は insert です)(the default is insert)
writeBatchSizewriteBatchSize writeBatchSize プロパティにより、各バッチで書き込むドキュメントのサイズが制御されます。The writeBatchSize property controls the size of documents to write in each batch. パフォーマンスを向上させるには writeBatchSize の値を大きくしてみて、ドキュメントのサイズが大きい場合は値を小さくしてみます。You can try increasing the value for writeBatchSize to improve performance and decreasing the value if your document size being large. いいえNo
(既定値は 10,000)(the default is 10,000)
writeBatchTimeoutwriteBatchTimeout タイムアウトする前に一括挿入操作の完了を待つ時間です。使用可能な値は timespan です。The wait time for the batch insert operation to finish before it times out. The allowed value is timespan. いいえNo
(既定値は 00:30:00 - 30 分)(the default is 00:30:00 - 30 minutes)

ヒント

JSON ドキュメントをそのままインポートするには、「JSON ドキュメントをインポートまたはエクスポートする」セクションを参照してください。表形式のデータからコピーするには、「スキーマ マッピング」を参照してください。To import JSON documents as-is, refer to Import or export JSON documents section; to copy from tabular-shaped data, refer to Schema mapping.

Example

"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 ドキュメントをインポートおよびエクスポートするImport and export JSON documents

Azure Cosmos DB コネクタを使用して簡単に次のことができます。You can use this Azure Cosmos DB connector to easily:

  • 2 つの Azure Cosmos DB コレクション間でドキュメントをそのままコピーします。Copy documents between two Azure Cosmos DB collections as-is.
  • MongoDB、Azure Blob Storage、Azure Data Lake Store、Azure Data Factory でサポートされているその他のファイル ベースのストアなど、さまざまなソースから Azure Cosmos DB に JSON ドキュメントをインポートします。Import JSON documents from various sources to Azure Cosmos DB, including from MongoDB, Azure Blob storage, Azure Data Lake Store, and other file-based stores that Azure Data Factory supports.
  • JSON ドキュメントを Azure Cosmos DB コレクションからさまざまなファイル ベースのストアにエクスポートします。Export JSON documents from an Azure Cosmos DB collection to various file-based stores.

スキーマに依存しないコピーを実行するには:To achieve schema-agnostic copy:

  • データ コピー ツールを使うときに、 [Export as-is to JSON files or Cosmos DB collection](JSON ファイルまたは Cosmos DB コレクションにそのままエクスポートする) オプションを選択します。When you use the Copy Data tool, select the Export as-is to JSON files or Cosmos DB collection option.
  • アクティビティの作成を使用する場合は、ソースまたはシンクの対応するファイル ストアで JSON 形式を選択します。When you use activity authoring, choose JSON format with the corresponding file store for source or sink.

スキーマ マッピングSchema mapping

Azure Cosmos DB の MongoDB 用 API から表形式のシンク、あるいはその逆の方向でデータをコピーするには、スキーマ マッピングに関するセクションを参照してください。To copy data from Azure Cosmos DB's API for MongoDB to tabular sink or reversed, refer to schema mapping.

特に Cosmos DB への書き込みでは、必ずソース データの正しいオブジェクト ID を Cosmos DB に入力する必要があります。たとえば、SQL データベース テーブルに "id" 列があり、その値を MongoDB での挿入/アップサート用のドキュメント ID として使用したい場合は、MongoDB の厳格モードの定義 (_id.$oid) に従って、以下のように適切なスキーマ マッピングを設定する必要があります。Specifically for writing into Cosmos DB, to make sure you populate Cosmos DB with the right object ID from your source data, for example, you have an "id" column in SQL database table and want to use the value of that as the document ID in MongoDB for insert/upsert, you need to set the proper schema mapping according to MongoDB strict mode definition (_id.$oid) as the following:

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

コピー アクティビティの実行後は、以下の BSON ObjectId がシンクに生成されます。After copy activity execution, below BSON ObjectId is generated in sink:

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

次のステップNext steps

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