Copiare dati da o verso l'API di Azure Cosmos DB per MongoDB usando Azure Data FactoryCopy data to or from Azure Cosmos DB's API for MongoDB by using Azure Data Factory

Questo articolo illustra come usare l'attività di copia in Azure Data Factory per copiare dati da o verso l'API di Azure Cosmos DB per MongoDB.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. L'articolo è basato su Attività di copia in Azure Data Factory, dove viene presentata una panoramica generale dell'attività di copia.The article builds on Copy Activity in Azure Data Factory, which presents a general overview of Copy Activity.

Nota

Questo connettore supporta solo la copia di dati da o verso l'API di Azure Cosmos DB per MongoDB.This connector only support copy data to/from Azure Cosmos DB's API for MongoDB. Per l'API SQL, vedere Connettore API SQL di Cosmos DB.For SQL API, refer to Cosmos DB SQL API connector. Al momento non sono supportati altri tipi di API.Other API types are not supported now.

Funzionalità supportateSupported capabilities

È possibile copiare dati dall'API di Azure Cosmos DB per MongoDB in qualsiasi archivio dati sink supportato o da qualsiasi archivio dati di origine supportato nell'API di Azure Cosmos DB per MongoDB.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. Per un elenco degli archivi dati supportati dall'attività di copia come origini e sink, vedere Archivi dati e formati supportati.For a list of data stores that Copy Activity supports as sources and sinks, see Supported data stores and formats.

È possibile usare il connettore API di Azure Cosmos DB per MongoDB per:You can use the Azure Cosmos DB's API for MongoDB connector to:

  • Copiare dati da e verso l'API di Azure Cosmos DB per MongoDB.Copy data from and to the Azure Cosmos DB's API for MongoDB.
  • Scrivere in Azure Cosmos DB tramite insert o upsert.Write to Azure Cosmos DB as insert or upsert.
  • Importare ed esportare documenti JSON come sono o copiare dati da o in un set di dati tabulari,Import and export JSON documents as-is, or copy data from or to a tabular dataset. ad esempio un database SQL e un file CSV.Examples include a SQL database and a CSV file. Per copiare documenti come sono da o in file JSON oppure da o in un'altra raccolta di Azure Cosmos DB, vedere Importare o esportare documenti 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.

Inizia oggi stessoGet started

È possibile usare l'attività di copia con una pipeline tramite uno degli strumenti o degli SDK seguenti.You can use one of the following tools or SDKs to use the copy activity with a pipeline. Per istruzioni dettagliate, selezionare un collegamento:Select a link for step-by-step instructions:

Le sezioni seguenti forniscono informazioni dettagliate sulle proprietà che è possibile usare per definire le entità di Data Factory specifiche per l'API di Azure Cosmos DB per MongoDB.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.

Proprietà del servizio collegatoLinked service properties

Per il servizio collegato dell'API di Azure Cosmos DB per MongoDB sono supportate le proprietà seguenti:The following properties are supported for the Azure Cosmos DB's API for MongoDB linked service:

ProprietàProperty DescriptionDescription ObbligatoriaRequired
typetype La proprietà type deve essere impostata su CosmosDbMongoDbApi.The type property must be set to CosmosDbMongoDbApi. Yes
connectionStringconnectionString Specificare la stringa di connessione per l'API di Azure Cosmos DB per MongoDB.Specify the connection string for your Azure Cosmos DB's API for MongoDB. È possibile trovarla nel portale di Azure -> pannello Cosmos DB -> stringa di connessione primaria o secondaria, con il modello mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb.You 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.

Contrassegnare questo campo come di tipo SecureString per l'archiviazione sicura in Data Factory.Mark this field as a SecureString type to store it securely in Data Factory. È anche possibile fare riferimento a un segreto archiviato in Azure Key Vault.You can also reference a secret stored in Azure Key Vault.
Yes
databasedatabase Nome del database a cui si vuole accedere.Name of the database that you want to access. Yes
connectViaconnectVia Runtime di integrazione da usare per la connessione all'archivio dati.The Integration Runtime to use to connect to the data store. È possibile usare Azure Integration Runtime o un runtime di integrazione self-hosted (se l'archivio dati si trova in una rete privata).You can use the Azure Integration Runtime or a self-hosted integration runtime (if your data store is located in a private network). Se questa proprietà non è specificata, come valore predefinito viene usato Azure Integration Runtime.If this property isn't specified, the default Azure Integration Runtime is used. NoNo

EsempioExample

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

Proprietà del set di datiDataset properties

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione dei set di dati, vedere Set di dati e servizi collegati.For a full list of sections and properties that are available for defining datasets, see Datasets and linked services. Per il set di dati dell'API di Azure Cosmos DB per MongoDB sono supportate le proprietà seguenti:The following properties are supported for Azure Cosmos DB's API for MongoDB dataset:

ProprietàProperty DescriptionDescription ObbligatoriaRequired
typetype La proprietà type del set di dati deve essere impostata su CosmosDbMongoDbApiCollection.The type property of the dataset must be set to CosmosDbMongoDbApiCollection. Yes
collectionNamecollectionName Nome della raccolta di Azure Cosmos DB.The name of the Azure Cosmos DB collection. Yes

EsempioExample

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

Proprietà dell'attività di copiaCopy Activity properties

Questa sezione fornisce un elenco delle proprietà supportate dall'origine e dal sink dell'API di Azure Cosmos DB per MongoDB.This section provides a list of properties that the Azure Cosmos DB's API for MongoDB source and sink support.

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, vedere Pipeline.For a full list of sections and properties that are available for defining activities, see Pipelines.

API di Azure Cosmos DB per MongoDB come origineAzure Cosmos DB's API for MongoDB as source

Nella sezione source dell'attività di copia sono supportate le proprietà seguenti:The following properties are supported in the Copy Activity source section:

ProprietàProperty DescriptionDescription ObbligatoriaRequired
typetype La proprietà type dell'origine dell'attività di copia deve essere impostata su CosmosDbMongoDbApiSource.The type property of the copy activity source must be set to CosmosDbMongoDbApiSource. Yes
filterfilter Specifica il filtro di selezione usando gli operatori di query.Specifies selection filter using query operators. Per restituire tutti i documenti in una raccolta, omettere questo parametro o passare un documento vuoto ({}).To return all documents in a collection, omit this parameter or pass an empty document ({}). NoNo
cursorMethods.projectcursorMethods.project Specifica i campi da restituire nei documenti per la proiezione.Specifies the fields to return in the documents for projection. Per restituire tutti i campi nei documenti corrispondenti, omettere questo parametro.To return all fields in the matching documents, omit this parameter. NoNo
cursorMethods.sortcursorMethods.sort Specifica l'ordine in cui la query restituisce i documenti corrispondenti.Specifies the order in which the query returns matching documents. Fare riferimento a cursor.sort().Refer to cursor.sort(). NoNo
cursorMethods.limitcursorMethods.limit Specifica il numero massimo di documenti restituiti dal server.Specifies the maximum number of documents the server returns. Fare riferimento a cursor.limit().Refer to cursor.limit(). NoNo
cursorMethods.skipcursorMethods.skip Specifica il numero di documenti da ignorare e la posizione da cui MongoDB inizia a restituire i risultati.Specifies the number of documents to skip and from where MongoDB begins to return results. Fare riferimento a cursor.skip().Refer to cursor.skip(). NoNo
batchSizebatchSize Specifica il numero di documenti da restituire in ogni batch di risposta dall'istanza di MongoDB.Specifies the number of documents to return in each batch of the response from MongoDB instance. Nella maggior parte dei casi, la modifica della dimensione del batch non influisce sull'utente o sull'applicazione.In most cases, modifying the batch size will not affect the user or the application. Il limite massimo di Cosmos DB per ogni batch è di 40 MB, che corrisponde alla somma delle dimensioni del numero di documenti definiti in batchSize. Diminuire questo valore se si hanno documenti di grandi dimensioni.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. NoNo
(il valore predefinito è 100)(the default is 100)

Suggerimento

Azure Data Factory supporta l'utilizzo di documenti BSON in modalità strict.ADF support consuming BSON document in Strict mode. Assicurarsi che la query di filtro sia in modalità strict anziché in modalità shell.Make sure your filter query is in Strict mode instead of Shell mode. Per altre informazioni consultare il manuale di MongoDB.More description can be found at MongoDB manual.

EsempioExample

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

API di Azure Cosmos DB per MongoDB come sinkAzure Cosmos DB's API for MongoDB as sink

Nella sezione sink dell'attività di copia sono supportate le proprietà seguenti:The following properties are supported in the Copy Activity sink section:

ProprietàProperty DescriptionDescription ObbligatoriaRequired
typetype La proprietà type del sink dell'attività di copia deve essere impostata su CosmosDbMongoDbApiSink.The type property of the Copy Activity sink must be set to CosmosDbMongoDbApiSink. Yes
writeBehaviorwriteBehavior Descrive come scrivere i dati in Azure Cosmos DB.Describes how to write data to Azure Cosmos DB. Valori consentiti: insert e upsert.Allowed values: insert and upsert.

Il comportamento di Upsert consiste nel sostituire il documento se esiste già un documento con lo stesso _id; in caso contrario, inserire il documento.The behavior of upsert is to replace the document if a document with the same _id already exists; otherwise, insert the document.

Nota: data factory genera automaticamente un _id per un documento se non è specificato alcun _id nel documento originale o in base al mapping delle colonne.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. È quindi necessario assicurarsi che il documento contenga un ID in modo che upsert funzioni come previsto.This means that you must ensure that, for upsert to work as expected, your document has an ID.
NoNo
(il valore predefinito è insert)(the default is insert)
writeBatchSizewriteBatchSize La proprietà writeBatchSize controlla le dimensioni dei documenti da scrivere in ogni batch.The writeBatchSize property controls the size of documents to write in each batch. È possibile provare ad aumentare il valore di writeBatchSize per migliorare le prestazioni e a ridurre il valore se le dimensioni dei documenti sono troppo grandi.You can try increasing the value for writeBatchSize to improve performance and decreasing the value if your document size being large. NoNo
(il valore predefinito è 10.000)(the default is 10,000)
writeBatchTimeoutwriteBatchTimeout Tempo di attesa per il completamento dell'operazione di inserimento batch prima del timeout. Il valore consentito è TimeSpan.The wait time for the batch insert operation to finish before it times out. The allowed value is timespan. NoNo
(il valore predefinito è 00:30:00 - 30 minuti)(the default is 00:30:00 - 30 minutes)

EsempioExample

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

Suggerimento

Per importare documenti JSON come sono, fare riferimento alla sezione Importare o esportare documenti JSON. Per copiare da dati in forma tabulare, fare riferimento a Mapping dello schema.To import JSON documents as-is, refer to Import or export JSON documents section; to copy from tabular-shaped data, refer to Schema mapping.

Importare o esportare documenti JSONImport or export JSON documents

È possibile usare questo connettore di Azure Cosmos DB per eseguire facilmente le operazioni seguenti:You can use this Azure Cosmos DB connector to easily:

  • Importare in Azure Cosmos DB documenti JSON da varie origini, tra cui Archiviazione BLOB di Azure, Azure Data Lake Storage e altri archivi basati su file supportati da Azure Data Factory.Import JSON documents from various sources to Azure Cosmos DB, including from Azure Blob storage, Azure Data Lake Store, and other file-based stores that Azure Data Factory supports.
  • Esportare documenti JSON da una raccolta di Azure Cosmos DB in diversi archivi basati su file.Export JSON documents from an Azure Cosmos DB collection to various file-based stores.
  • Copiare documenti come sono da una raccolta di Azure Cosmos DB a un'altra.Copy documents between two Azure Cosmos DB collections as-is.

Per ottenere una copia priva di schema, ignorare la sezione "structure" (chiamata anche schema) nel set di dati e il mapping dello schema nell'attività di copia.To achieve such schema-agnostic copy, skip the "structure" (also called schema) section in dataset and schema mapping in copy activity.

Mapping dello schemaSchema mapping

Per copiare dati dall'API di Azure Cosmos DB per MongoDB in un sink tabulare o viceversa, fare riferimento al mapping dello schema.To copy data from Azure Cosmos DB's API for MongoDB to tabular sink or reversed, refer to schema mapping.

In modo specifico per la scrittura in Cosmos DB, per inserire in Cosmos DB l'ID dell'oggetto corretto dai dati di origine (ad esempio, nella tabella del database SQL è presente una colonna "id" e si vuole usare il relativo valore come ID del documento in MongoDB per insert/upsert) è necessario impostare il mapping dello schema appropriato in base alla definizione della modalità strict di MongoDB (_id.$oid) come illustrato di seguito: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:

Eseguire il mapping dell'ID nel sink MongoDB

Dopo l'esecuzione dell'attività di copia, nel sink viene generato il valore ObjectId BSON indicato di seguito:After copy activity execution, below BSON ObjectId is generated in sink:

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

Passaggi successiviNext steps

Per un elenco degli archivi dati supportati come origini e sink dall'attività di copia in Azure Data Factory, vedere gli archivi dati supportati.For a list of data stores that Copy Activity supports as sources and sinks in Azure Data Factory, see supported data stores.