Copiare e trasformare i dati in Azure Cosmos DB (API SQL) utilizzando Azure Data FactoryCopy and transform data in Azure Cosmos DB (SQL API) by using Azure Data Factory

Questo articolo illustra come usare l'attività di copia in Azure Data Factory per copiare dati da e in Azure Cosmos DB (API SQL) e usare il flusso di dati per trasformare i dati in Azure Cosmos DB (API SQL).This article outlines how to use Copy Activity in Azure Data Factory to copy data from and to Azure Cosmos DB (SQL API), and use Data Flow to transform data in Azure Cosmos DB (SQL API). Per altre informazioni su Azure Data Factory, vedere l'articolo introduttivo.To learn about Azure Data Factory, read the introductory article.

Nota

Questo connettore supporta solo Cosmos DB API SQL.This connector only support Cosmos DB SQL API. Per l'API MongoDB, fare riferimento al connettore per l'API di Azure Cosmos DB per MongoDB.For MongoDB API, refer to connector for Azure Cosmos DB's API for MongoDB. Al momento non sono supportati altri tipi di API.Other API types are not supported now.

Funzionalità supportateSupported capabilities

Questo connettore Azure Cosmos DB (API SQL) è supportato per le attività seguenti:This Azure Cosmos DB (SQL API) connector is supported for the following activities:

Per l'attività di copia, questo connettore Azure Cosmos DB (API SQL) supporta:For Copy activity, this Azure Cosmos DB (SQL API) connector supports:

  • Copiare dati da e verso l'API SQL di Azure Cosmos DB.Copy data from and to the Azure Cosmos DB SQL API.
  • 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.

Data Factory si integra con la libreria dell'executor bulk di Azure Cosmos DB per offrire le migliori prestazioni durante la scrittura in Azure Cosmos DB.Data Factory integrates with the Azure Cosmos DB bulk executor library to provide the best performance when you write to Azure Cosmos DB.

Suggerimento

Il video sulla migrazione dei dati illustra la procedura di copia dei dati da Archiviazione BLOB di Azure ad Azure Cosmos DB.The Data Migration video walks you through the steps of copying data from Azure Blob storage to Azure Cosmos DB. Il video presenta inoltre alcune considerazioni generali sull'ottimizzazione delle prestazioni per l'inserimento di dati in Azure Cosmos DB.The video also describes performance-tuning considerations for ingesting data to Azure Cosmos DB in general.

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 presentano informazioni dettagliate sulle proprietà che è possibile usare per definire entità di Data Factory specifiche per Azure Cosmos DB (API SQL).The following sections provide details about properties you can use to define Data Factory entities that are specific to Azure Cosmos DB (SQL API).

Proprietà del servizio collegatoLinked service properties

Per il servizio collegato di Azure Cosmos DB (API SQL) sono supportate le proprietà seguenti:The following properties are supported for the Azure Cosmos DB (SQL API) linked service:

ProprietàProperty DescriptionDescription ObbligatoriaRequired
typetype La proprietà type deve essere impostata su CosmosDb.The type property must be set to CosmosDb. Yes
connectionStringconnectionString Specificare le informazioni richieste per connettersi al database di Azure Cosmos DB.Specify information that's required to connect to the Azure Cosmos DB database.
Nota: è necessario specificare le informazioni sul database nella stringa di connessione come illustrato negli esempi seguenti.Note: You must specify database information in the connection string as shown in the examples that follow.
Contrassegnare questo campo come SecureString per archiviare la chiave in modo sicuro in Data Factory.Mark this field as a SecureString to store it securely in Data Factory. È anche possibile inserire la chiave dell'account in Azure Key Vault e rimuovere la configurazione di accountKey dalla stringa di connessione.You can also put account key in Azure Key Vault and pull the accountKey configuration out of the connection string. Vedere gli esempi seguenti e l'articolo Archiviare le credenziali in Azure Key Vault per altri dettagli.Refer to the following samples and Store credentials in Azure Key Vault article with more details.
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": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "connectionString": {
                "type": "SecureString",
                "value": "AccountEndpoint=<EndpointUrl>;AccountKey=<AccessKey>;Database=<Database>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Esempio: archiviare la chiave dell'account in Azure Key VaultExample: store account key in Azure Key Vault

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "connectionString": {
                "type": "SecureString",
                "value": "AccountEndpoint=<EndpointUrl>;Database=<Database>"
            },
            "accountKey": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName>" 
            }
        },
        "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 Azure Cosmos DB (API SQL) sono supportate le proprietà seguenti:The following properties are supported for Azure Cosmos DB (SQL API) dataset:

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

Se si usa il set di dati di tipo "DocumentDbCollection", è ancora supportato così com'è per la compatibilità con le versioni precedenti per l'attività di copia e ricerca, non è supportato per il flusso di dati.If you use "DocumentDbCollection" type dataset, it is still supported as-is for backward compatibility for Copy and Lookup activity, it's not supported for Data Flow. Si consiglia di utilizzare il nuovo modello in futuro.You are suggested to use the new model going forward.

EsempioExample

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

Schema da Data FactorySchema by Data Factory

Per gli archivi dati privi di schema come Azure Cosmos DB, l'attività di copia deduce lo schema in uno dei modi descritti nell'elenco seguente.For schema-free data stores like Azure Cosmos DB, Copy Activity infers the schema in one of the ways described in the following list. A meno che non si voglia importare o esportare documenti JSON come così sono, la procedura consigliata è quella di specificare la struttura di dati nella sezione structure.Unless you want to import or export JSON documents as-is, the best practice is to specify the structure of data in the structure section.

Data Factory rispetta il mapping specificato nell'attività.Data Factory honors the mapping you specified on the activity. Se una riga non contiene un valore per una colonna, viene inserito un valore null per il valore di colonna.If a row doesn't contain a value for a column, a null value is provided for the column value.

Se non si specifica un mapping, il servizio Data Factory deduce lo schema usando la prima riga dei dati.If you don't specify a mapping, the Data Factory service infers the schema by using the first row in the data. Se la prima riga non contiene lo schema completo, alcune colonne non saranno presenti nel risultato dell'operazione di attività.If the first row doesn't contain the full schema, some columns will be missing in the result of the activity operation.

Proprietà dell'attività di copiaCopy Activity properties

Questa sezione presenta un elenco delle proprietà supportate dall'origine e dal sink di Azure Cosmos DB (API SQL).This section provides a list of properties that the Azure Cosmos DB (SQL API) 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.

Azure Cosmos DB (API SQL) come origineAzure Cosmos DB (SQL API) as source

Per copiare dati da Azure Cosmos DB (API SQL), impostare il tipo source nell'attività di copia su DocumentDbCollectionSource.To copy data from Azure Cosmos DB (SQL API), set the source type in Copy Activity to DocumentDbCollectionSource.

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 CosmosDbSqlApiSource.The type property of the copy activity source must be set to CosmosDbSqlApiSource. Yes
queryquery Specificare la query Azure Cosmos DB per leggere i dati.Specify the Azure Cosmos DB query to read data.

Esempio:Example:
SELECT c.BusinessEntityID, c.Name.First AS FirstName, c.Name.Middle AS MiddleName, c.Name.Last AS LastName, c.Suffix, c.EmailPromotion FROM c WHERE c.ModifiedDate > \"2009-01-01T00:00:00\"
NoNo

Se non specificato, viene eseguita questa istruzione SQL: select <columns defined in structure> from mycollectionIf not specified, this SQL statement is executed: select <columns defined in structure> from mycollection
preferredRegionspreferredRegions Elenco preferito delle aree a cui connettersi quando recupera i dati da Cosmos DB.The preferred list of regions to connect to when retriving data from Cosmos DB. NoNo
pageSizepageSize Numero di documenti per pagina del risultato della query.The number of documents per page of the query result. Il valore predefinito è "-1", che indica l'utilizzo delle dimensioni di pagina dinamiche del lato servizio fino a 1000.Default is "-1" which means uses the service side dynamic page size up to 1000. NoNo

Se si usa l'origine del tipo "DocumentDbCollectionSource", è ancora supportata così com'è per la compatibilità con le versioni precedenti.If you use "DocumentDbCollectionSource" type source, it is still supported as-is for backward compatibility. Si consiglia di utilizzare il nuovo modello in futuro, che offre funzionalità più avanzate per la copia dei dati da Cosmos DB.You are suggested to use the new model going forward which provide richer capabilities to copy data from Cosmos DB.

EsempioExample

"activities":[
    {
        "name": "CopyFromCosmosDBSQLAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Cosmos DB SQL API input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "CosmosDbSqlApiSource",
                "query": "SELECT c.BusinessEntityID, c.Name.First AS FirstName, c.Name.Middle AS MiddleName, c.Name.Last AS LastName, c.Suffix, c.EmailPromotion FROM c WHERE c.ModifiedDate > \"2009-01-01T00:00:00\"",
                "preferredRegions": [
                    "East US"
                ]
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Azure Cosmos DB (API SQL) come sinkAzure Cosmos DB (SQL API) as sink

Per copiare dati in Azure Cosmos DB (API SQL), impostare il tipo sink nell'attività di copia su DocumentDbCollectionSink.To copy data to Azure Cosmos DB (SQL API), set the sink type in Copy Activity to DocumentDbCollectionSink.

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 del sink dell'attività di copia deve essere impostata su CosmosDbSqlApiSink.The type property of the Copy Activity sink must be set to CosmosDbSqlApiSink. 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 nella sostituzione del documento se esiste già un documento con lo stesso ID. In caso contrario, il documento viene inserito.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 nel documento originale o tramite il mapping di colonna.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 Data Factory usa la libreria dell'executor bulk di Azure Cosmos DB per scrivere dati in Azure Cosmos DB.Data Factory uses the Azure Cosmos DB bulk executor library to write data to Azure Cosmos DB. La proprietà writeBatchSize controlla le dimensioni dei documenti che Azure Data Factory fornisce alla libreria.The writeBatchSize property controls the size of documents that ADF provide to the library. È possibile provare ad aumentare il valore per writeBatchSize per migliorare le prestazioni e a ridurre il valore se le dimensioni dei documenti diventano grandi. Vedere i suggerimenti di seguito.You can try increasing the value for writeBatchSize to improve performance and decreasing the value if your document size being large - see below tips. NoNo
(il valore predefinito è 10.000)(the default is 10,000)
disableMetricsCollectiondisableMetricsCollection Data Factory raccoglie le metriche, ad esempio Cosmos DB ur per l'ottimizzazione delle prestazioni di copia e consigli.Data Factory collects metrics such as Cosmos DB RUs for copy performance optimization and recommendations. Se si è interessati a questo comportamento, specificare true per disattivarlo.If you are concerned with this behavior, specify true to turn it off. No (il valore predefinito è false)No (default is false)

Suggerimento

Cosmos DB limita le dimensioni per una singola richiesta a 2 MB.Cosmos DB limits single request's size to 2MB. La formula è Dimensioni richiesta = Dimensioni singolo documento * Dimensioni batch di scrittura.The formula is Request Size = Single Document Size * Write Batch Size. Se viene generato l'errore "Dimensioni della richiesta troppo grandi." , ridurre il valore writeBatchSize nella configurazione del sink di copia.If you hit error saying "Request size is too large.", reduce the writeBatchSize value in copy sink configuration.

Se si usa l'origine del tipo "DocumentDbCollectionSink", è ancora supportata così com'è per la compatibilità con le versioni precedenti.If you use "DocumentDbCollectionSink" type source, it is still supported as-is for backward compatibility. Si consiglia di utilizzare il nuovo modello in futuro, che offre funzionalità più avanzate per la copia dei dati da Cosmos DB.You are suggested to use the new model going forward which provide richer capabilities to copy data from Cosmos DB.

EsempioExample

"activities":[
    {
        "name": "CopyToCosmosDBSQLAPI",
        "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": "CosmosDbSqlApiSink",
                "writeBehavior": "upsert"
            }
        }
    }
]

Mapping delle proprietà del flusso di datiMapping data flow properties

Per informazioni dettagliate, vedere trasformazione origine e trasformazione sink nel flusso di dati del mapping.Learn details from source transformation and sink transformation in mapping data flow.

Proprietà attività di ricercaLookup activity properties

Per informazioni dettagliate sulle proprietà, controllare l' attività di ricerca.To learn details about the properties, check Lookup activity.

Importare o esportare documenti JSONImport or export JSON documents

È possibile usare questo connettore di Azure Cosmos DB (API SQL) per eseguire facilmente le operazioni seguenti:You can use this Azure Cosmos DB (SQL API) 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 la copia senza schema:To achieve schema-agnostic copy:

  • Quando si usa lo strumento Copia dati, selezionare l'opzione Export as-is to JSON files or Cosmos DB collection (Esportare così come sono nel file JSON o in una raccolta di Cosmos DB).When you use the Copy Data tool, select the Export as-is to JSON files or Cosmos DB collection option.
  • Quando si usa la creazione di attività, scegliere il formato JSON con l'archivio file corrispondente per origine o sink.When you use activity authoring, choose JSON format with the corresponding file store for source or sink.

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.