Azure Cosmos DB: Utilità di migrazione datiAzure Cosmos DB: Data migration tool

Suggerimento

L'API SQL (DocumentDB) o API DocumentDB di Azure Cosmos DB è ora denominata API SQL di Azure Cosmos DB.The Azure Cosmos DB DocumentDB API or SQL (DocumentDB) API is now known as Azure Cosmos DB SQL API. Non è necessaria alcuna modifica per continuare a eseguire le app compilate con l'API DocumentDB.You don't need to change anything to continue running your apps built with DocumentDB API. Le funzionalità rimangono invariate.The functionality remains the same.

Questa esercitazione fornisce istruzioni sull'uso dell'Utilità di migrazione dati di Azure Cosmos DB, che consente di importare dati da diverse origini nelle raccolte e nelle tabelle di Azure Cosmos DB.This tutorial provides instructions on using the Azure Cosmos DB Data Migration tool, which can import data from various sources into Azure Cosmos DB collections and tables. È possibile importare da JSON file CSV file, SQL, MongoDB, tabelle di Azure storage, Amazon DynamoDB e anche le raccolte di API di SQL Azure Cosmos DB, e si esegue la migrazione che i dati per le raccolte e le tabelle per usati con Azure Cosmos DB.You can import from JSON files, CSV files, SQL, MongoDB, Azure Table storage, Amazon DynamoDB, and even Azure Cosmos DB SQL API collections, and you migrate that data to collections and tables for use with Azure Cosmos DB. Lo strumento di migrazione dei dati può essere utilizzato anche durante la migrazione da una raccolta di sola partizione per una raccolta di più partizioni per l'API di SQL.The Data Migration tool can also be used when migrating from a single partition collection to a multi-partition collection for the SQL API.

API da usare con Azure Cosmos DBWhich API are you going to use with Azure Cosmos DB?

  • API SQL -è possibile utilizzare una delle opzioni di origine fornite nello strumento di migrazione dei dati per importare i dati.SQL API - You can use any of the source options provided in the Data Migration tool to import data.
  • API Tabelle: è possibile usare l'Utilità di migrazione dati o AzCopy per importare i dati.Table API - You can use the Data Migration tool or AzCopy to import data. Per altre informazioni, vedere Importare i dati da usare con l'API Tabelle di Azure Cosmos DB.See Import data for use with the Azure Cosmos DB Table API for more information.
  • API di MongoDB -strumento di migrazione dei dati attualmente non supporta API di Azure Cosmos DB MongoDB come origine o come destinazione.MongoDB API - The Data Migration tool does not currently support Azure Cosmos DB MongoDB API either as a source or as a target. Se si desidera migrare i dati in o da raccolte di MongoDB API in Azure Cosmos DB, vedere DB Cosmos Azure: come eseguire la migrazione di dati per l'API di MongoDB per le istruzioni.If you want to migrate the data in or out of MongoDB API collections in Azure Cosmos DB, refer to Azure Cosmos DB: How to migrate data for the MongoDB API for instructions. Per esportare dati da MongoDB alle raccolte di API di SQL Azure Cosmos DB da utilizzare con l'API di SQL, è comunque possibile utilizzare lo strumento di migrazione dei dati.You can still use the Data Migration tool to export data from MongoDB to Azure Cosmos DB SQL API collections for use with the SQL API.
  • API Graph: l'Utilità di migrazione dati non è uno strumento di importazione attualmente supportato per gli account dell'API Graph.Graph API - The Data Migration tool is not a supported import tool for Graph API accounts at this time.

Questa esercitazione illustra le attività seguenti:This tutorial covers the following tasks:

  • Installazione dello strumento di migrazione datiInstalling the Data Migration tool
  • Importazione di dati da diverse origini datiImporting data from different data sources
  • Esportazione da Azure Cosmos DB a JSONExporting from Azure Cosmos DB to JSON

PrerequisitiPrerequisites

Prima di seguire le istruzioni di questo articolo, verificare che siano installati i seguenti elementi:Before following the instructions in this article, ensure that you have the following installed:

PanoramicaOverview

Lo strumento di migrazione dati è una soluzione open source che importa dati in Azure Cosmos DB da diverse origini, tra cui:The Data Migration tool is an open source solution that imports data to Azure Cosmos DB from a variety of sources, including:

  • File JSONJSON files
  • MongoDBMongoDB
  • SQL ServerSQL Server
  • File CSVCSV files
  • Archiviazione tabelle di AzureAzure Table storage
  • DynamoDB AmazonAmazon DynamoDB
  • hbaseHBase
  • Raccolte di Azure Cosmos DBAzure Cosmos DB collections

Lo strumento di importazione, anche se include un'interfaccia utente grafica (dtui.exe), può essere gestito anche dalla riga di comando (dt.exe).While the import tool includes a graphical user interface (dtui.exe), it can also be driven from the command line (dt.exe). Infatti, una speciale opzione consente di inviare il comando associato dopo aver configurato un'operazione di importazione nell'interfaccia utente.In fact, there is an option to output the associated command after setting up an import through the UI. I dati di origine tabulari (ad esempio, file CSV o SQL Server) possono essere trasformati in modo da poter creare relazioni gerarchiche (documenti secondari) durante l'importazione.Tabular source data (e.g. SQL Server or CSV files) can be transformed such that hierarchical relationships (subdocuments) can be created during import. Continuare a leggere per saperne di più sulle opzioni di origine, sulle righe di comando di esempio per l'importazione da ogni origine, sulle opzioni di destinazione e sulla visualizzazione dei risultati di importazione.Keep reading to learn more about source options, sample command lines to import from each source, target options, and viewing import results.

InstallazioneInstallation

Il codice sorgente dello strumento di migrazione è disponibile su GitHub in questo repository e una versione compilata è disponibile nell'Area download Microsoft.The migration tool source code is available on GitHub in this repository and a compiled version is available from Microsoft Download Center. È possibile compilare la soluzione o semplicemente scaricare ed estrarre la versione compilata nella directory desiderata.You may either compile the solution or simply download and extract the compiled version to a directory of your choice. Eseguire quindi:Then run either:

  • Dtui.exe: versione con interfaccia grafica dello strumentoDtui.exe: Graphical interface version of the tool
  • Dt.exe: versione con riga di comando dello strumentoDt.exe: Command-line version of the tool

Selezionare l'origine datiSelect data source

Dopo aver installato lo strumento, è necessario importare i dati.Once you've installed the tool, it's time to import your data. È possibile importare le tipologie di dati seguenti:What kind of data do you want to import?

Importare file JSONImport JSON files

L'opzione dell'utilità di importazione dell'origine file JSON consente di importare uno o più file JSON di singoli documenti o file JSON contenenti ciascuno una matrice di documenti JSON.The JSON file source importer option allows you to import one or more single document JSON files or JSON files that each contain an array of JSON documents. Quando si aggiungono le cartelle contenenti i file JSON da importare, è possibile eseguire una ricerca ricorsiva dei file nelle sottocartelle.When adding folders that contain JSON files to import, you have the option of recursively searching for files in subfolders.

Schermata delle opzioni dell'origine file JSON - Strumenti di migrazione del database

Ecco alcuni esempi di riga di comando per importare file JSON:Here are some command line samples to import JSON files:

#Import a single JSON file
dt.exe /s:JsonFile /s.Files:.\Sessions.json /t:CosmosDBBulk /t.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:Sessions /t.CollectionThroughput:2500

#Import a directory of JSON files
dt.exe /s:JsonFile /s.Files:C:\TESessions\*.json /t:CosmosDBBulk /t.ConnectionString:" AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:Sessions /t.CollectionThroughput:2500

#Import a directory (including sub-directories) of JSON files
dt.exe /s:JsonFile /s.Files:C:\LastFMMusic\**\*.json /t:CosmosDBBulk /t.ConnectionString:" AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:Music /t.CollectionThroughput:2500

#Import a directory (single), directory (recursive), and individual JSON files
dt.exe /s:JsonFile /s.Files:C:\Tweets\*.*;C:\LargeDocs\**\*.*;C:\TESessions\Session48172.json;C:\TESessions\Session48173.json;C:\TESessions\Session48174.json;C:\TESessions\Session48175.json;C:\TESessions\Session48177.json /t:CosmosDBBulk /t.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:subs /t.CollectionThroughput:2500

#Import a single JSON file and partition the data across 4 collections
dt.exe /s:JsonFile /s.Files:D:\\CompanyData\\Companies.json /t:CosmosDBBulk /t.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:comp[1-4] /t.PartitionKey:name /t.CollectionThroughput:2500

Importare da MongoDBImport from MongoDB

Importante

Se si esegue l'importazione in un account Azure Cosmos DB con supporto per MongoDB, seguire queste istruzioni.If you are importing to an Azure Cosmos DB account with Support for MongoDB, follow these instructions.

L'opzione dell'utilità di importazione dell'origine MongoDB consente di importare da una singola raccolta MongoDB e, facoltativamente, di filtrare i documenti usando una query e/o di modificare la struttura di documenti usando una proiezione.The MongoDB source importer option allows you to import from an individual MongoDB collection and optionally filter documents using a query and/or modify the document structure by using a projection.

Screenshot delle opzioni relative all'origine per MongoDB

La stringa di connessione è nel formato standard di MongoDB:The connection string is in the standard MongoDB format:

mongodb://<dbuser>:<dbpassword>@<host>:<port>/<database>

Nota

Usare il comando Verify per assicurarsi che l'istanza di MongoDB specificata nel campo della stringa di connessione sia accessibile.Use the Verify command to ensure that the MongoDB instance specified in the connection string field can be accessed.

Immettere il nome della raccolta da cui verranno importati i dati.Enter the name of the collection from which data will be imported. Se si preferisce, si può specificare o fornire un file per una query (ad esempio, {pop: {$gt:5000}}) e/o la proiezione (ad esempio, {loc:0}) sia per filtrare che per determinare i dati da importare.You may optionally specify or provide a file for a query (e.g. {pop: {$gt:5000}} ) and/or projection (e.g. {loc:0} ) to both filter and shape the data to be imported.

Ecco alcuni esempi di riga di comando per importare da MongoDB:Here are some command line samples to import from MongoDB:

#Import all documents from a MongoDB collection
dt.exe /s:MongoDB /s.ConnectionString:mongodb://<dbuser>:<dbpassword>@<host>:<port>/<database> /s.Collection:zips /t:CosmosDBBulk /t.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:BulkZips /t.IdField:_id /t.CollectionThroughput:2500

#Import documents from a MongoDB collection which match the query and exclude the loc field
dt.exe /s:MongoDB /s.ConnectionString:mongodb://<dbuser>:<dbpassword>@<host>:<port>/<database> /s.Collection:zips /s.Query:{pop:{$gt:50000}} /s.Projection:{loc:0} /t:CosmosDBBulk /t.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:BulkZipsTransform /t.IdField:_id/t.CollectionThroughput:2500

Importare file di esportazione MongoDBImport MongoDB export files

Importante

Se si esegue l'importazione in un account Azure Cosmos DB con supporto per MongoDB, seguire queste istruzioni.If you are importing to an Azure Cosmos DB account with support for MongoDB, follow these instructions.

L'opzione dell'utilità di importazione dell'origine file JSON di esportazione MongoDB consente di importare uno o più file JSON prodotti dall'utilità mongoexport.The MongoDB export JSON file source importer option allows you to import one or more JSON files produced from the mongoexport utility.

Screenshot delle opzioni relative all'origine per file di esportazione MongoDB

Quando si aggiungono le cartelle contenenti i file JSON di esportazione MongoDB da importare, è possibile eseguire una ricerca ricorsiva dei file nelle sottocartelle.When adding folders that contain MongoDB export JSON files for import, you have the option of recursively searching for files in subfolders.

Ecco un esempio di riga di comando per importare dai file JSON di esportazione MongoDB:Here is a command line sample to import from MongoDB export JSON files:

dt.exe /s:MongoDBExport /s.Files:D:\mongoemployees.json /t:CosmosDBBulk /t.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:employees /t.IdField:_id /t.Dates:Epoch /t.CollectionThroughput:2500

Importare da SQL ServerImport from SQL Server

L'opzione dell'utilità di importazione dell'origine SQL consente di importare da un singolo database SQL Server e, facoltativamente, di filtrare i record da importare usando una query.The SQL source importer option allows you to import from an individual SQL Server database and optionally filter the records to be imported using a query. Inoltre, è possibile modificare la struttura di documenti specificando un separatore di annidamento, di cui si parlerà tra poco.In addition, you can modify the document structure by specifying a nesting separator (more on that in a moment).

Schermata delle opzioni dell'origine SQL - Strumenti di migrazione del database

Il formato della stringa di connessione è il formato della stringa di connessione SQL standard.The format of the connection string is the standard SQL connection string format.

Nota

Usare il comando Verify per assicurarsi che l'istanza di SQL Server specificata nel campo della stringa di connessione sia accessibile.Use the Verify command to ensure that the SQL Server instance specified in the connection string field can be accessed.

La proprietà del separatore di annidamento viene usata per creare relazioni gerarchiche (documenti secondari) durante l'importazione.The nesting separator property is used to create hierarchical relationships (sub-documents) during import. Considerare la query SQL seguente:Consider the following SQL query:

select CAST(BusinessEntityID AS varchar) as Id, Name, AddressType as [Address.AddressType], AddressLine1 as [Address.AddressLine1], City as [Address.Location.City], StateProvinceName as [Address.Location.StateProvinceName], PostalCode as [Address.PostalCode], CountryRegionName as [Address.CountryRegionName] from Sales.vStoreWithAddresses WHERE AddressType='Main Office'select CAST(BusinessEntityID AS varchar) as Id, Name, AddressType as [Address.AddressType], AddressLine1 as [Address.AddressLine1], City as [Address.Location.City], StateProvinceName as [Address.Location.StateProvinceName], PostalCode as [Address.PostalCode], CountryRegionName as [Address.CountryRegionName] from Sales.vStoreWithAddresses WHERE AddressType='Main Office'

Che restituisce i risultati (parziali) seguenti:Which returns the following (partial) results:

Schermata dei risultati della query SQL

Si notino gli alias come Address.AddressType e Address.Location.StateProvinceName.Note the aliases such as Address.AddressType and Address.Location.StateProvinceName. Specificando un separatore di annidamento ".", lo strumento di importazione crea i documenti secondari Address e Address.Location durante l'importazione.By specifying a nesting separator of ‘.’, the import tool creates Address and Address.Location subdocuments during the import. Ecco un esempio di documento risultante in Azure Cosmos DB:Here is an example of a resulting document in Azure Cosmos DB:

{ "id": "956", "Name": "Finer Sales and Service", "Address": { "AddressType": "Main Office", "AddressLine1": "#500-75 O'Connor Street", "Location": { "City": "Ottawa", "StateProvinceName": "Ontario" }, "PostalCode": "K4B 1S2", "CountryRegionName": "Canada" } }{ "id": "956", "Name": "Finer Sales and Service", "Address": { "AddressType": "Main Office", "AddressLine1": "#500-75 O'Connor Street", "Location": { "City": "Ottawa", "StateProvinceName": "Ontario" }, "PostalCode": "K4B 1S2", "CountryRegionName": "Canada" } }

Ecco alcuni esempi di riga di comando per importare da SQL Server:Here are some command line samples to import from SQL Server:

#Import records from SQL which match a query
dt.exe /s:SQL /s.ConnectionString:"Data Source=<server>;Initial Catalog=AdventureWorks;User Id=advworks;Password=<password>;" /s.Query:"select CAST(BusinessEntityID AS varchar) as Id, * from Sales.vStoreWithAddresses WHERE AddressType='Main Office'" /t:CosmosDBBulk /t.ConnectionString:" AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:Stores /t.IdField:Id /t.CollectionThroughput:2500

#Import records from sql which match a query and create hierarchical relationships
dt.exe /s:SQL /s.ConnectionString:"Data Source=<server>;Initial Catalog=AdventureWorks;User Id=advworks;Password=<password>;" /s.Query:"select CAST(BusinessEntityID AS varchar) as Id, Name, AddressType as [Address.AddressType], AddressLine1 as [Address.AddressLine1], City as [Address.Location.City], StateProvinceName as [Address.Location.StateProvinceName], PostalCode as [Address.PostalCode], CountryRegionName as [Address.CountryRegionName] from Sales.vStoreWithAddresses WHERE AddressType='Main Office'" /s.NestingSeparator:. /t:CosmosDBBulk /t.ConnectionString:" AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:StoresSub /t.IdField:Id /t.CollectionThroughput:2500

Importare file CSV ed eseguire la conversione da CSV a JSONImport CSV files and convert CSV to JSON

L'opzione dell'utilità di importazione dell'origine file CSV consente di importare uno o più file CSV.The CSV file source importer option enables you to import one or more CSV files. Quando si aggiungono le cartelle contenenti i file CSV da importare, è possibile eseguire una ricerca ricorsiva dei file nelle sottocartelle.When adding folders that contain CSV files for import, you have the option of recursively searching for files in subfolders.

Schermata delle opzioni dell'origine CSV - Da CSV a JSON

Come per l'origine SQL, la proprietà del separatore di annidamento può essere usata per creare relazioni gerarchiche (documenti secondari) durante l'importazione.Similar to the SQL source, the nesting separator property may be used to create hierarchical relationships (sub-documents) during import. Si consideri la seguente riga di intestazione CSV e le righe di dati:Consider the following CSV header row and data rows:

Schermata dei record di esempio CSV - Da CSV a JSON

Si notino gli alias come DomainInfo.Domain_Name e RedirectInfo.Redirecting.Note the aliases such as DomainInfo.Domain_Name and RedirectInfo.Redirecting. Specificando un separatore di annidamento ".", lo strumento di importazione creerà i documenti secondari DomainInfo e RedirectInfo durante l'importazione.By specifying a nesting separator of ‘.’, the import tool will create DomainInfo and RedirectInfo subdocuments during the import. Ecco un esempio di documento risultante in Azure Cosmos DB:Here is an example of a resulting document in Azure Cosmos DB:

{ "DomainInfo": { "Domain_Name": "ACUS.GOV", "Domain_Name_Address": "http://www.ACUS.GOV" }, "Federal Agency": "Administrative Conference of the United States", "RedirectInfo": { "Redirecting": "0", "Redirect_Destination": "" }, "id": "9cc565c5-ebcd-1c03-ebd3-cc3e2ecd814d" }{ "DomainInfo": { "Domain_Name": "ACUS.GOV", "Domain_Name_Address": "http://www.ACUS.GOV" }, "Federal Agency": "Administrative Conference of the United States", "RedirectInfo": { "Redirecting": "0", "Redirect_Destination": "" }, "id": "9cc565c5-ebcd-1c03-ebd3-cc3e2ecd814d" }

Lo strumento di importazione prova a dedurre le informazioni sul tipo per i valori non racchiusi tra virgolette nei file CSV. I valori tra virgolette vengono sempre considerati come stringhe.The import tool attempts to infer type information for unquoted values in CSV files (quoted values are always treated as strings). I tipi vengono identificati nell'ordine seguente: tipo numerico, datetime, booleano.Types are identified in the following order: number, datetime, boolean.

Esistono altri due aspetti da considerare per l'importazione CSV:There are two other things to note about CSV import:

  1. Per impostazione predefinita, nei valori non racchiusi tra virgolette vengono sempre rimossi spazi e tabulazioni, mentre i valori tra virgolette vengono mantenuti così come sono.By default, unquoted values are always trimmed for tabs and spaces, while quoted values are preserved as-is. È possibile eseguire l'override di questo comportamento con la casella di controllo Taglia valori tra virgolette o con l'opzione della riga di comando /s.TrimQuoted.This behavior can be overridden with the Trim quoted values checkbox or the /s.TrimQuoted command-line option.
  2. Per impostazione predefinita, un valore Null non racchiuso tra virgolette viene considerato come valore Null.By default, an unquoted null is treated as a null value. È possibile eseguire l'override di questo comportamento (ad esempio considerando un valore Null non racchiuso tra virgolette come stringa "Null") con la casella di controllo Considera valore NULL non racchiuso tra virgolette come stringa o con l'opzione della riga di comando /s.NoUnquotedNulls.This behavior can be overridden (that is, treat an unquoted null as a “null” string) with the Treat unquoted NULL as string checkbox or the /s.NoUnquotedNulls command-line option.

Ecco un esempio di riga di comando per l'importazione CSV:Here is a command-line sample for CSV import:

dt.exe /s:CsvFile /s.Files:.\Employees.csv /t:CosmosDBBulk /t.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:Employees /t.IdField:EntityID /t.CollectionThroughput:2500

Importare da Archiviazione tabelle di AzureImport from Azure Table storage

L'opzione dell'utilità di importazione dell'origine Archiviazione tabelle di Azure consente di importare da una singola tabella di Archiviazione tabelle di Azure.The Azure Table storage source importer option allows you to import from an individual Azure Table storage table. È facoltativamente possibile filtrare le entità tabelle da importare.Optionally, you can filter the table entities to be imported.

Dati importati da Archiviazione tabelle di Azure possono essere inviati Azure Cosmos DB tabelle ed entità, per l'utilizzo con l'API di tabelle, o a raccolte documenti e, per l'utilizzo con l'API di SQL.Data imported from Azure Table Storage can be output to Azure Cosmos DB tables and entities, for use with the Table API, or to collections and documents, for use with the SQL API. Tuttavia, l'API Table è disponibile solo come destinazione nell'utilità della riga di comando, non è possibile eseguire esportazioni nell'API Table mediante l'interfaccia utente dell'Utilità di migrazione dati.However; Table API is only available as a target in the command-line utility, you cannot export to Table API by using the Data Migration tool user interface. Per altre informazioni, vedere Importare dati da usare con l'API Tabelle di Azure Cosmos DB.For more information, see Import data for use with the Azure Cosmos DB Table API.

Schermata delle opzioni dell'origine Archiviazione tabelle di Azure

Il formato della stringa di connessione di Archiviazione tabelle di Azure è:The format of the Azure Table storage connection string is:

DefaultEndpointsProtocol=<protocol>;AccountName=<Account Name>;AccountKey=<Account Key>;

Nota

Usare il comando Verify per assicurarsi che l'istanza di Archiviazione tabelle di Azure specificata nel campo della stringa di connessione sia accessibile.Use the Verify command to ensure that the Azure Table storage instance specified in the connection string field can be accessed.

Immettere il nome della tabella di Azure da cui eseguire l'importazione.Enter the name of the Azure table from to import from. Se si preferisce, si può specificare un filtro.You may optionally specify a filter.

L'opzione dell'utilità di importazione dell'origine Archiviazione tabelle di Azure presenta le seguenti opzioni aggiuntive:The Azure Table storage source importer option has the following additional options:

  1. Include Internal FieldsInclude Internal Fields
    1. All: include tutti i campi interni (PartitionKey, RowKey e Timestamp)All - Include all internal fields (PartitionKey, RowKey, and Timestamp)
    2. None: esclude tutti i campi interniNone - Exclude all internal fields
    3. RowKey: include solo il campo RowKeyRowKey - Only include the RowKey field
  2. Select ColumnsSelect Columns
    1. I filtri di Archiviazione tabelle di Azure non supportano le proiezioni.Azure Table storage filters do not support projections. Per importare solo specifiche proprietà delle entità tabelle di Azure, aggiungerle all'elenco Select Columns.If you want to only import specific Azure Table entity properties, add them to the Select Columns list. Tutte le altre proprietà delle entità vengono ignorate.All other entity properties are ignored.

Ecco un esempio di riga di comando per importare da Archiviazione tabelle di Azure:Here is a command-line sample to import from Azure Table storage:

dt.exe /s:AzureTable /s.ConnectionString:"DefaultEndpointsProtocol=https;AccountName=<Account Name>;AccountKey=<Account Key>" /s.Table:metrics /s.InternalFields:All /s.Filter:"PartitionKey eq 'Partition1' and RowKey gt '00001'" /s.Projection:ObjectCount;ObjectSize  /t:CosmosDBBulk /t.ConnectionString:" AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:metrics /t.CollectionThroughput:2500

Importa da Amazon DynamoDBImport from Amazon DynamoDB

L'opzione dell'utilità di importazione DynamoDB Amazon origine consente di importare da una singola tabella DynamoDB Amazon e filtrare le entità da importare.The Amazon DynamoDB source importer option allows you to import from an individual Amazon DynamoDB table and optionally filter the entities to be imported. Sono disponibili vari modelli in modo che l'impostazione di un'importazione è più semplice possibile.Several templates are provided so that setting up an import is as easy as possible.

Schermata delle opzioni dell'origine Amazon DynamoDB - Strumenti di migrazione del database

Schermata delle opzioni dell'origine Amazon DynamoDB - Strumenti di migrazione del database

Il formato della stringa di connessione DynamoDB di Amazon è:The format of the Amazon DynamoDB connection string is:

ServiceURL=<Service Address>;AccessKey=<Access Key>;SecretKey=<Secret Key>;

Nota

Usare il comando Verify per assicurarsi che l'istanza di MongoDB specificata nel campo della stringa di connessione sia accessibile.Use the Verify command to ensure that the Amazon DynamoDB instance specified in the connection string field can be accessed.

Ecco un esempio di riga di comando per importare da Amazon DynamoDB:Here is a command-line sample to import from Amazon DynamoDB:

dt.exe /s:DynamoDB /s.ConnectionString:ServiceURL=https://dynamodb.us-east-1.amazonaws.com;AccessKey=<accessKey>;SecretKey=<secretKey> /s.Request:"{   """TableName""": """ProductCatalog""" }" /t:DocumentDBBulk /t.ConnectionString:"AccountEndpoint=<Azure Cosmos DB Endpoint>;AccountKey=<Azure Cosmos DB Key>;Database=<Azure Cosmos DB Database>;" /t.Collection:catalogCollection /t.CollectionThroughput:2500

Importare dall'Archiviazione BLOB di AzureImport from Azure Blob storage

Il file JSON, i file di esportazione MongoDB e le opzioni dell'utilità di importazione di codice sorgente file CSV consentono di importare uno o più file dall'archiviazione Blob di Azure.The JSON file, MongoDB export file, and CSV file source importer options allow you to import one or more files from Azure Blob storage. Dopo avere specificato un URL di contenitore BLOB e una chiave dell'account, fornire un'espressione regolare per selezionare i file da importare.After specifying a Blob container URL and Account Key, provide a regular expression to select the file(s) to import.

Schermata delle opzioni dell'origine file JSON

Ecco un esempio di riga di comando per importare file JSON dall'archiviazione BLOB di Azure:Here is command-line sample to import JSON files from Azure Blob storage:

dt.exe /s:JsonFile /s.Files:"blobs://<account key>@account.blob.core.windows.net:443/importcontainer/.*" /t:CosmosDBBulk /t.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:doctest

Importare da un insieme di API di SQLImport from a SQL API collection

L'opzione dell'utilità di importazione per un'origine Azure Cosmos DB consente di importare dati da una o più raccolte di Azure Cosmos DB e, facoltativamente, filtrare i documenti usando una query.The Azure Cosmos DB source importer option allows you to import data from one or more Azure Cosmos DB collections and optionally filter documents using a query.

Screenshot delle opzioni relative all'origine per Azure Cosmos DB

Il formato della stringa di connessione di Azure Cosmos DB è il seguente:The format of the Azure Cosmos DB connection string is:

AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;

La stringa di connessione dell'account Azure Cosmos DB può essere recuperata dalla pagina Chiavi del portale di Azure, come descritto in Come gestire un account Azure Cosmos DB, ma è necessario aggiungere il nome del database alla stringa di connessione nel formato seguente:The Azure Cosmos DB account connection string can be retrieved from the Keys page of the Azure portal, as described in How to manage an Azure Cosmos DB account, however the name of the database needs to be appended to the connection string in the following format:

Database=<CosmosDB Database>;

Nota

Usare il comando Verifica per assicurarsi che l'istanza di Azure Cosmos DB specificata nel campo della stringa di connessione sia accessibile.Use the Verify command to ensure that the Azure Cosmos DB instance specified in the connection string field can be accessed.

Per eseguire l'importazione da una singola raccolta di Azure Cosmos DB, immettere il nome della raccolta da cui importare i dati.To import from a single Azure Cosmos DB collection, enter the name of the collection to import data from. Per eseguire l'importazione da più raccolte di Azure Cosmos DB, specificare un'espressione regolare corrispondente a uno o più nomi di raccolta, ad esempio, collection01 | collection02 | collection03.To import from multiple Azure Cosmos DB collections, provide a regular expression to match one or more collection names (for example, collection01 | collection02 | collection03). Se si preferisce, si può specificare o fornire un file per una query sia per filtrare che per determinare i dati da importare.You may optionally specify, or provide a file for, a query to both filter and shape the data to be imported.

Nota

Poiché il campo della raccolta accetta le espressioni regolari, se si importa da un'unica raccolta il cui nome contiene caratteri di espressioni regolari, tali caratteri dovranno essere preceduti da un carattere di escape.Since the collection field accepts regular expressions, if you are importing from a single collection whose name contains regular expression characters, then those characters must be escaped accordingly.

L'opzione dell'utilità di importazione per un'origine Azure Cosmos DB offre le opzioni avanzate seguenti.The Azure Cosmos DB source importer option has the following advanced options:

  1. Include Internal Fields (Includi campi interni): specifica se includere o meno le proprietà di sistema dei documenti di Azure Cosmos DB, ad esempio, _rid, _ts, nell'esportazione.Include Internal Fields: Specifies whether or not to include Azure Cosmos DB document system properties in the export (for example, _rid, _ts).
  2. Number of Retries on Failure (Numero di tentativi in caso di errore): specifica il numero di tentativi di connessione ad Azure Cosmos DB da effettuare in caso di errori temporanei, ad esempio un'interruzione della connettività di rete.Number of Retries on Failure: Specifies the number of times to retry the connection to Azure Cosmos DB in case of transient failures (for example, network connectivity interruption).
  3. Intervallo tentativi: specifica l'intervallo di attesa tra i tentativi di connessione ad Azure Cosmos DB in caso di errori temporanei, ad esempio un'interruzione della connettività di rete.Retry Interval: Specifies how long to wait between retrying the connection to Azure Cosmos DB in case of transient failures (for example, network connectivity interruption).
  4. Connection Mode (Modalità connessione): specifica la modalità di connessione da usare con Azure Cosmos DB.Connection Mode: Specifies the connection mode to use with Azure Cosmos DB. Le scelte disponibili sono DirectTcp, DirectHttps e Gateway.The available choices are DirectTcp, DirectHttps, and Gateway. Le modalità di connessione diretta sono più veloci, mentre la modalità gateway si integra più facilmente con il firewall perché usa solo la porta 443.The direct connection modes are faster, while the gateway mode is more firewall friendly as it only uses port 443.

Screenshot delle opzioni avanzate per origini Azure Cosmos DB

Suggerimento

Per impostazione predefinita, la modalità di connessione dello strumento di importazione è DirectTcp.The import tool defaults to connection mode DirectTcp. Se si verificano problemi con il firewall, passare alla modalità di connessione Gateway, che richiede solo la porta 443.If you experience firewall issues, switch to connection mode Gateway, as it only requires port 443.

Ecco alcuni esempi di riga di comando per l'importazione da Azure Cosmos DB:Here are some command-line samples to import from Azure Cosmos DB:

#Migrate data from one Azure Cosmos DB collection to another Azure Cosmos DB collections
dt.exe /s:CosmosDB /s.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /s.Collection:TEColl /t:CosmosDBBulk /t.ConnectionString:" AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:TESessions /t.CollectionThroughput:2500

#Migrate data from multiple Azure Cosmos DB collections to a single Azure Cosmos DB collection
dt.exe /s:CosmosDB /s.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /s.Collection:comp1|comp2|comp3|comp4 /t:CosmosDBBulk /t.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:singleCollection /t.CollectionThroughput:2500

#Export an Azure Cosmos DB collection to a JSON file
dt.exe /s:CosmosDB /s.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /s.Collection:StoresSub /t:JsonFile /t.File:StoresExport.json /t.Overwrite /t.CollectionThroughput:2500

Suggerimento

Lo strumento di importazione dati di Azure Cosmos DB supporta anche l'importazione di dati dall'emulatore di Azure Cosmos DB.The Azure Cosmos DB Data Import Tool also supports import of data from the Azure Cosmos DB Emulator. Quando si importano dati da un emulatore locale, impostare l'endpoint https://localhost:<port>.When importing data from a local emulator, set the endpoint to https://localhost:<port>.

Importa da HBaseImport from HBase

L'opzione dell'utilità di importazione HBase origine consente di importare dati da una tabella HBase e filtrare i dati.The HBase source importer option allows you to import data from an HBase table and optionally filter the data. Sono disponibili vari modelli in modo che l'impostazione di un'importazione è più semplice possibile.Several templates are provided so that setting up an import is as easy as possible.

Schermata di HBase opzioni del codice sorgente

Schermata di HBase opzioni del codice sorgente

Il formato della stringa di connessione HBase Stargate è:The format of the HBase Stargate connection string is:

ServiceURL=<server-address>;Username=<username>;Password=<password>

Nota

Utilizzare il comando verifica per garantire che l'istanza di HBase specificato nel campo della stringa di connessione sia accessibile.ssione sia accessibile.Use the Verify command to ensure that the HBase instance specified in the connection string field can be accessed.

Ecco un esempio di riga di comando per l'importazione da HBase:Here is a command-line sample to import from HBase:

dt.exe /s:HBase /s.ConnectionString:ServiceURL=<server-address>;Username=<username>;Password=<password> /s.Table:Contacts /t:CosmosDBBulk /t.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:hbaseimport

Importare l'API di SQL (importazione in blocco)Import to the SQL API (Bulk Import)

L'utilità di importazione in blocco di Azure Cosmos DB consente di eseguire l'importazione da qualsiasi opzione di origine disponibile, usando una stored procedure di Azure Cosmos DB per una maggiore efficienza.The Azure Cosmos DB Bulk importer allows you to import from any of the available source options, using an Azure Cosmos DB stored procedure for efficiency. Lo strumento supporta l'importazione in una raccolta di Azure Cosmos DB con partizione singola, nonché l'importazione partizionata con partizionamento dei dati in più raccolte di Azure Cosmos DB con partizione singola.The tool supports import to one single-partitioned Azure Cosmos DB collection, as well as sharded import whereby data is partitioned across multiple single-partitioned Azure Cosmos DB collections. Per altre informazioni sul partizionamento dei dati, vedere l'articolo relativo a partizionamento e ridimensionamento in Azure Cosmos DB.For more information about partitioning data, see Partitioning and scaling in Azure Cosmos DB. Lo strumento crea, esegue e quindi elimina la stored procedure dalla raccolta o dalle raccolte di destinazione.The tool creates, executes, and then deletes the stored procedure from the target collection(s).

Screenshot delle opzioni relative all'importazione in blocco di Azure Cosmos DB

Il formato della stringa di connessione di Azure Cosmos DB è il seguente:The format of the Azure Cosmos DB connection string is:

AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;

La stringa di connessione dell'account Azure Cosmos DB può essere recuperata dalla pagina Chiavi del portale di Azure, come descritto in Come gestire un account Azure Cosmos DB, ma è necessario aggiungere il nome del database alla stringa di connessione nel formato seguente:The Azure Cosmos DB account connection string can be retrieved from the Keys page of the Azure portal, as described in How to manage an Azure Cosmos DB account, however the name of the database needs to be appended to the connection string in the following format:

Database=<CosmosDB Database>;

Nota

Usare il comando Verifica per assicurarsi che l'istanza di Azure Cosmos DB specificata nel campo della stringa di connessione sia accessibile.Use the Verify command to ensure that the Azure Cosmos DB instance specified in the connection string field can be accessed.

Per importare in un'unica raccolta, immettere il nome della raccolta da cui importare i dati e fare clic sul pulsante Aggiungi.To import to a single collection, enter the name of the collection to import data from and click the Add button. Per importare in più raccolte, immettere il nome di ogni raccolta singolarmente o usare la sintassi seguente per specificare più raccolte: prefisso_raccolta[indice iniziale - indice finale].To import to multiple collections, either enter each collection name individually or use the following syntax to specify multiple collections: collection_prefix[start index - end index]. Quando si specificano più raccolte tramite la sintassi menzionata in precedenza, tenere presente le indicazioni seguenti:When specifying multiple collections via the aforementioned syntax, keep the following guidelines in mind:

  1. Sono supportati solo criteri di denominazione con intervalli interi.Only integer range name patterns are supported. Ad esempio, se si specifica collection[0-3], vengono create le raccolte seguenti: collection0, collection1, collection2, collection3.For example, specifying collection[0-3] creates the following collections: collection0, collection1, collection2, collection3.
  2. È possibile usare una sintassi abbreviata: collection[3] crea lo stesso set di raccolte citato nel passaggio 1.You can use an abbreviated syntax: collection[3] creates the same set of collections mentioned in step 1.
  3. È possibile specificare più di una sostituzione.More than one substitution can be provided. Ad esempio, collection[0-1] [0-9] genera 20 nomi di raccolte con zeri iniziali (collection01, ..02, ..03).For example, collection[0-1] [0-9] generates 20 collection names with leading zeros (collection01, ..02, ..03).

Dopo aver specificato il nome della raccolta, scegliere la velocità effettiva desiderata della raccolta, da 400 UR a 10.000 UR.Once the collection name(s) have been specified, choose the desired throughput of the collection(s) (400 RUs to 10,000 RUs). Per ottimizzare le prestazioni di importazione, scegliere una velocità effettiva superiore.For best import performance, choose a higher throughput. Per altre informazioni sui livelli di prestazioni, vedere l'articolo relativo ai livelli di prestazioni in Azure Cosmos DB.For more information about performance levels, see Performance levels in Azure Cosmos DB.

Nota

L'impostazione della velocità effettiva delle prestazioni si applica solo alla creazione di raccolte.The performance throughput setting only applies to collection creation. Se la raccolta specificata esiste già, la velocità effettiva non viene modificata.If the specified collection already exists, its throughput is not be modified.

Quando si importa in più raccolte, lo strumento di importazione supporta il partizionamento orizzontale basato su hash.When importing to multiple collections, the import tool supports hash-based sharding. In questo scenario è necessario specificare la proprietà di documento da usare come chiave di partizione. Se la chiave di partizione viene lasciata vuota, i documenti vengono partizionati in modo casuale tra le raccolte di destinazione.In this scenario, specify the document property you wish to use as the Partition Key (if Partition Key is left blank, documents are sharded randomly across the target collections).

Facoltativamente, è possibile specificare il campo dell'origine di importazione da usare come proprietà ID del documento di Azure Cosmos DB durante l'importazione. Se i documenti non contengono questa proprietà, lo strumento di importazione genera un GUID come valore della proprietà ID.You may optionally specify which field in the import source should be used as the Azure Cosmos DB document id property during the import (note that if documents do not contain this property, then the import tool generates a GUID as the id property value).

Durante l'importazione sono disponibili numerose opzioni avanzate.There are a number of advanced options available during import. Innanzitutto, anche se lo strumento include una stored procedure di importazione in blocco predefinita (BulkInsert.js), è possibile scegliere di specificare la propria stored procedure di importazione:First, while the tool includes a default bulk import stored procedure (BulkInsert.js), you may choose to specify your own import stored procedure:

Screenshot dell'opzione relativa alla stored procedure di inserimento in blocco per Azure Cosmos DB

Inoltre, quando si importano i tipi di data, ad esempio da SQL Server o MongoDB, è possibile scegliere tra tre opzioni di importazione:Additionally, when importing date types (for example, from SQL Server or MongoDB), you can choose between three import options:

Screenshot delle opzioni di importazione relative a data e ora per Azure Cosmos DB

  • String: persiste come valore di stringa.String: Persist as a string value
  • Epoch: persiste come valore numerico di periodo.Epoch: Persist as an Epoch number value
  • Both: persiste come valore di stringa e numerico di periodo.Both: Persist both string and Epoch number values. Questa opzione crea un documento secondario, ad esempio: "date_joined": { "Value": "2013-10-21T21:17:25.2410000Z", "Epoch": 1382390245 }This option creates a subdocument, for example: "date_joined": { "Value": "2013-10-21T21:17:25.2410000Z", "Epoch": 1382390245 }

L'utilità di importazione in blocco di Azure Cosmos DB offre le opzioni avanzate aggiuntive seguenti.The Azure Cosmos DB Bulk importer has the following additional advanced options:

  1. Batch Size: per impostazione predefinita, le dimensioni batch dello strumento sono pari a 50.Batch Size: The tool defaults to a batch size of 50. Se i documenti da importare sono di grandi dimensioni, provare a ridurre le dimensioni batch.If the documents to be imported are large, consider lowering the batch size. Se invece i documenti da importare sono di piccole dimensioni, provare ad aumentare le dimensioni batch.Conversely, if the documents to be imported are small, consider raising the batch size.
  2. Max Script Size (bytes) (Dimensioni massime script - Byte): Per impostazione predefinita lo strumento usa dimensioni massime dello script pari a 512 KB.Max Script Size (bytes): The tool defaults to a max script size of 512 KB.
  3. Disable Automatic Id Generation: se ogni documento da importare contiene un campo ID, selezionando questa opzione, le prestazioni possono migliorare.Disable Automatic Id Generation: If every document to be imported contains an id field, then selecting this option can increase performance. I documenti privi di un campo ID univoco non vengono importati.Documents missing a unique id field are not imported.
  4. Update Existing Documents: per impostazione predefinita, lo strumento non sostituisce i documenti esistenti con conflitti tra ID.Update Existing Documents: The tool defaults to not replacing existing documents with id conflicts. Questa opzione consente di sovrascrivere i documenti esistenti con ID corrispondenti.Selecting this option allows overwriting existing documents with matching ids. Questa funzionalità è utile per le migrazioni dei dati pianificate che aggiornano i documenti esistenti.This feature is useful for scheduled data migrations that update existing documents.
  5. Number of Retries on Failure (Numero di tentativi in caso di errore): specifica il numero di tentativi di connessione ad Azure Cosmos DB da effettuare in caso di errori temporanei, ad esempio un'interruzione della connettività di rete.Number of Retries on Failure: Specifies the number of times to retry the connection to Azure Cosmos DB in case of transient failures (for example, network connectivity interruption).
  6. Intervallo tentativi: specifica l'intervallo di attesa tra i tentativi di connessione ad Azure Cosmos DB in caso di errori temporanei, ad esempio un'interruzione della connettività di rete.Retry Interval: Specifies how long to wait between retrying the connection to Azure Cosmos DB in case of transient failures (for example, network connectivity interruption).
  7. Connection Mode (Modalità connessione): specifica la modalità di connessione da usare con Azure Cosmos DB.Connection Mode: Specifies the connection mode to use with Azure Cosmos DB. Le scelte disponibili sono DirectTcp, DirectHttps e Gateway.The available choices are DirectTcp, DirectHttps, and Gateway. Le modalità di connessione diretta sono più veloci, mentre la modalità gateway si integra più facilmente con il firewall perché usa solo la porta 443.The direct connection modes are faster, while the gateway mode is more firewall friendly as it only uses port 443.

Screenshot delle opzioni avanzate di importazione in blocco di Azure Cosmos DB

Suggerimento

Per impostazione predefinita, la modalità di connessione dello strumento di importazione è DirectTcp.The import tool defaults to connection mode DirectTcp. Se si verificano problemi con il firewall, passare alla modalità di connessione Gateway, che richiede solo la porta 443.If you experience firewall issues, switch to connection mode Gateway, as it only requires port 443.

Importare l'API di SQL (importazione di Record sequenziali)Import to the SQL API (Sequential Record Import)

L'utilità di importazione di record sequenziali di Azure Cosmos DB consente di importare un record alla volta da qualsiasi opzione di origine disponibile.The Azure Cosmos DB sequential record importer allows you to import from any of the available source options on a record by record basis. È possibile scegliere questa opzione se si sta importando in una raccolta esistente che ha raggiunto la quota di stored procedure.You might choose this option if you’re importing to an existing collection that has reached its quota of stored procedures. Lo strumento supporta l'importazione in un'unica raccolta di Azure Cosmos DB, sia con partizione singola che con più partizioni, nonché l'importazione partizionata con partizionamento dei dati in più raccolte di Azure Cosmos DB con partizione singola e/o con più partizioni.The tool supports import to a single (both single-partition and multi-partition) Azure Cosmos DB collection, as well as sharded import whereby data is partitioned across multiple single-partition and/or multi-partition Azure Cosmos DB collections. Per altre informazioni sul partizionamento dei dati, vedere l'articolo relativo a partizionamento e ridimensionamento in Azure Cosmos DB.For more information about partitioning data, see Partitioning and scaling in Azure Cosmos DB.

Screenshot delle opzioni di importazione di record sequenziali per Azure Cosmos DB

Il formato della stringa di connessione di Azure Cosmos DB è il seguente:The format of the Azure Cosmos DB connection string is:

AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;

La stringa di connessione dell'account Azure Cosmos DB può essere recuperata dalla pagina Chiavi del portale di Azure, come descritto in Come gestire un account Azure Cosmos DB, ma è necessario aggiungere il nome del database alla stringa di connessione nel formato seguente:The Azure Cosmos DB account connection string can be retrieved from the Keys page of the Azure portal, as described in How to manage an Azure Cosmos DB account, however the name of the database needs to be appended to the connection string in the following format:

Database=<Azure Cosmos DB Database>;

Nota

Usare il comando Verifica per assicurarsi che l'istanza di Azure Cosmos DB specificata nel campo della stringa di connessione sia accessibile.Use the Verify command to ensure that the Azure Cosmos DB instance specified in the connection string field can be accessed.

Per importare in un'unica raccolta, immettere il nome della raccolta in cui verranno importati i dati e fare clic sul pulsante Aggiungi.To import to a single collection, enter the name of the collection to which data will be imported and click the Add button. Per importare in più raccolte, immettere il nome di ogni raccolta singolarmente o usare la sintassi seguente per specificare più raccolte: prefisso_raccolta[indice iniziale - indice finale].To import to multiple collections, either enter each collection name individually or use the following syntax to specify multiple collections: collection_prefix[start index - end index]. Quando si specificano più raccolte tramite la sintassi menzionata in precedenza, tenere presente le indicazioni seguenti:When specifying multiple collections via the aforementioned syntax, keep the following guidelines in mind:

  1. Sono supportati solo criteri di denominazione con intervalli interi.Only integer range name patterns are supported. Ad esempio, se si specifica collection[0-3], vengono create le raccolte seguenti: collection0, collection1, collection2, collection3.For example, specifying collection[0-3] creates the following collections: collection0, collection1, collection2, collection3.
  2. È possibile usare una sintassi abbreviata: collection[3] crea lo stesso set di raccolte citato nel passaggio 1.You can use an abbreviated syntax: collection[3] creates the same set of collections mentioned in step 1.
  3. È possibile specificare più di una sostituzione.More than one substitution can be provided. Ad esempio, collection[0-1] [0-9] crea 20 nomi di raccolta con zeri iniziali (collection01, ..02, ..03).For example, collection[0-1] [0-9] creates 20 collection names with leading zeros (collection01, ..02, ..03).

Dopo aver specificato il nome della raccolta, scegliere la velocità effettiva desiderata della raccolta, da 400 UR a 250.000 UR.Once the collection name(s) have been specified, choose the desired throughput of the collection(s) (400 RUs to 250,000 RUs). Per ottimizzare le prestazioni di importazione, scegliere una velocità effettiva superiore.For best import performance, choose a higher throughput. Per altre informazioni sui livelli di prestazioni, vedere l'articolo relativo ai livelli di prestazioni in Azure Cosmos DB.For more information about performance levels, see Performance levels in Azure Cosmos DB. Eventuali importazioni nelle raccolte con una velocità effettiva > 10.000 UR richiedono una chiave di partizione.Any import to collections with throughput >10,000 RUs require a partition key. Se si sceglie di avere più di 250.000 UR, è necessario inviare una richiesta di nel portale per incrementare l'account.If you choose to have more than 250,000 RUs, you need to file a request in the portal to have your account increased.

Nota

L'impostazione della velocità effettiva si applica solo alla creazione di raccolte.The throughput setting only applies to collection creation. Se la raccolta specificata esiste già, la velocità effettiva non verrà modificata.If the specified collection already exists, its throughput will not be modified.

Quando si importa in più raccolte, lo strumento di importazione supporta il partizionamento orizzontale basato su hash.When importing to multiple collections, the import tool supports hash-based sharding. In questo scenario è necessario specificare la proprietà di documento da usare come chiave di partizione. Se la chiave di partizione viene lasciata vuota, i documenti vengono partizionati in modo casuale tra le raccolte di destinazione.In this scenario, specify the document property you wish to use as the Partition Key (if Partition Key is left blank, documents are sharded randomly across the target collections).

Facoltativamente, è possibile specificare il campo dell'origine di importazione da usare come proprietà ID del documento di Azure Cosmos DB durante l'importazione. Se i documenti non contengono questa proprietà, lo strumento di importazione genera un GUID come valore della proprietà ID.You may optionally specify which field in the import source should be used as the Azure Cosmos DB document id property during the import (note that if documents do not contain this property, then the import tool generates a GUID as the id property value).

Durante l'importazione sono disponibili numerose opzioni avanzate.There are a number of advanced options available during import. Quando si importano i tipi di data, ad esempio da SQL Server o MongoDB, è possibile scegliere prima di tutto tra tre opzioni di importazione:First, when importing date types (for example, from SQL Server or MongoDB), you can choose between three import options:

Screenshot delle opzioni di importazione relative a data e ora per Azure Cosmos DB

  • String: persiste come valore di stringa.String: Persist as a string value
  • Epoch: persiste come valore numerico di periodo.Epoch: Persist as an Epoch number value
  • Both: persiste come valore di stringa e numerico di periodo.Both: Persist both string and Epoch number values. Questa opzione crea un documento secondario, ad esempio: "date_joined": { "Value": "2013-10-21T21:17:25.2410000Z", "Epoch": 1382390245 }This option creates a subdocument, for example: "date_joined": { "Value": "2013-10-21T21:17:25.2410000Z", "Epoch": 1382390245 }

L'utilità di importazione di record sequenziali di Azure Cosmos DB offre le opzioni avanzate aggiuntive seguenti.The Azure Cosmos DB - Sequential record importer has the following additional advanced options:

  1. Number of Parallel Requests (Numero di richieste parallele): per impostazione predefinita, lo strumento include due richieste parallele.Number of Parallel Requests: The tool defaults to two parallel requests. Se i documenti da importare sono di piccole dimensioni, provare ad aumentare il numero di richieste parallele.If the documents to be imported are small, consider raising the number of parallel requests. Si noti che, se questo numero è troppo alto, durante l'importazione potrebbe venire applicata la limitazione delle richieste.Note that if this number is raised too much, the import may experience throttling.
  2. Disable Automatic Id Generation: se ogni documento da importare contiene un campo ID, selezionando questa opzione, le prestazioni possono migliorare.Disable Automatic Id Generation: If every document to be imported contains an id field, then selecting this option can increase performance. I documenti privi di un campo ID univoco non vengono importati.Documents missing a unique id field are not imported.
  3. Update Existing Documents: per impostazione predefinita, lo strumento non sostituisce i documenti esistenti con conflitti tra ID.Update Existing Documents: The tool defaults to not replacing existing documents with id conflicts. Questa opzione consente di sovrascrivere i documenti esistenti con ID corrispondenti.Selecting this option allows overwriting existing documents with matching ids. Questa funzionalità è utile per le migrazioni dei dati pianificate che aggiornano i documenti esistenti.This feature is useful for scheduled data migrations that update existing documents.
  4. Number of Retries on Failure (Numero di tentativi in caso di errore): specifica il numero di tentativi di connessione ad Azure Cosmos DB da effettuare in caso di errori temporanei, ad esempio un'interruzione della connettività di rete.Number of Retries on Failure: Specifies the number of times to retry the connection to Azure Cosmos DB in case of transient failures (for example, network connectivity interruption).
  5. Intervallo tentativi: specifica l'intervallo di attesa tra i tentativi di connessione ad Azure Cosmos DB in caso di errori temporanei, ad esempio un'interruzione della connettività di rete.Retry Interval: Specifies how long to wait between retrying the connection to Azure Cosmos DB in case of transient failures (for example, network connectivity interruption).
  6. Connection Mode (Modalità connessione): specifica la modalità di connessione da usare con Azure Cosmos DB.Connection Mode: Specifies the connection mode to use with Azure Cosmos DB. Le scelte disponibili sono DirectTcp, DirectHttps e Gateway.The available choices are DirectTcp, DirectHttps, and Gateway. Le modalità di connessione diretta sono più veloci, mentre la modalità gateway si integra più facilmente con il firewall perché usa solo la porta 443.The direct connection modes are faster, while the gateway mode is more firewall friendly as it only uses port 443.

Screenshot delle opzioni avanzate di importazione di record sequenziali di Azure Cosmos DB

Suggerimento

Per impostazione predefinita, la modalità di connessione dello strumento di importazione è DirectTcp.The import tool defaults to connection mode DirectTcp. Se si verificano problemi con il firewall, passare alla modalità di connessione Gateway, che richiede solo la porta 443.If you experience firewall issues, switch to connection mode Gateway, as it only requires port 443.

Specificare un criterio di indicizzazioneSpecify an indexing policy

Quando si consente lo strumento di migrazione creare raccolte di API di Azure Cosmos DB SQL durante l'importazione, è possibile specificare i criteri di indicizzazione delle raccolte.When you allow the migration tool to create Azure Cosmos DB SQL API collections during import, you can specify the indexing policy of the collections. Nella sezione delle opzioni avanzate per l'importazione in blocco e l'importazione di record sequenziali di Azure Cosmos DB, passare alla sezione relativa ai criteri di indicizzazione.In the advanced options section of the Azure Cosmos DB Bulk import and Azure Cosmos DB Sequential record options, navigate to the Indexing Policy section.

Screenshot delle opzioni avanzate relative ai criteri di indicizzazione di Azure Cosmos DB

Usando l'opzione avanzata Criteri di indicizzazione, è possibile selezionare un file di criteri di indicizzazione, immettere manualmente un criterio di indicizzazione oppure selezionarne uno da un set di modelli predefiniti facendo clic con il pulsante destro del mouse sulla casella di testo relativa al criterio di indicizzazione.Using the Indexing Policy advanced option, you can select an indexing policy file, manually enter an indexing policy, or select from a set of default templates (by right-clicking in the indexing policy textbox).

I modelli dei criteri che lo strumento fornisce sono:The policy templates the tool provides are:

  • Default.Default. Questo criterio è migliore quando si eseguono query di uguaglianza su stringhe e utilizzando ORDER BY, l'intervallo e le query di uguaglianza per i numeri.This policy is best when you’re performing equality queries against strings and using ORDER BY, range, and equality queries for numbers. Questo criterio ha un overhead di archiviazione indice inferiore rispetto a intervallo.This policy has a lower index storage overhead than Range.
  • Intervallo.Range. Questo criterio risulta ottimale quando si usano query di tipo ORDER BY, di intervallo e di uguaglianza su numeri e stringhe.This policy is best you’re using ORDER BY, range, and equality queries on both numbers and strings. Questo criterio ha un overhead di archiviazione indice superiore rispetto a predefinito o Hash.This policy has a higher index storage overhead than Default or Hash.

Screenshot delle opzioni avanzate relative ai criteri di indicizzazione di Azure Cosmos DB

Nota

Se non si specifica un criterio di indicizzazione, viene applicato il criterio predefinito.If you do not specify an indexing policy, then the default policy is applied. Per altre informazioni sui criteri di indicizzazione, vedere l'articolo relativo ai criteri di indicizzazione di Azure Cosmos DB.For more information about indexing policies, see Azure Cosmos DB indexing policies.

Esportare in file JSONExport to JSON file

L'utilità di esportazione JSON di Azure Cosmos DB consente di esportare qualsiasi opzione di origine disponibile in un file JSON contenente una matrice di documenti JSON.The Azure Cosmos DB JSON exporter allows you to export any of the available source options to a JSON file that contains an array of JSON documents. Lo strumento gestisce l'esportazione, ma è anche possibile scegliere di visualizzare il comando di migrazione risultante ed eseguire il comando manualmente.The tool handles the export for you, or you can choose to view the resulting migration command and run the command yourself. Il file JSON risultante può essere archiviato in locale o nel servizio di archiviazione Blob di Azure.The resulting JSON file may be stored locally or in Azure Blob storage.

Screenshot dell'opzione di esportazione in file JSON locale di Azure Cosmos DB

Screenshot dell'opzione di esportazione in file JSON in un archivio BLOB di Azure di Azure Cosmos DB

Se si preferisce, si può scegliere di modificare il file JSON risultante, aumentando così le dimensioni del documento risultante e rendendone il contenuto più leggibile.You may optionally choose to prettify the resulting JSON, which will increase the size of the resulting document while making the contents more human readable.

Standard JSON export
[{"id":"Sample","Title":"About Paris","Language":{"Name":"English"},"Author":{"Name":"Don","Location":{"City":"Paris","Country":"France"}},"Content":"Don's document in Azure Cosmos DB is a valid JSON document as defined by the JSON spec.","PageViews":10000,"Topics":[{"Title":"History of Paris"},{"Title":"Places to see in Paris"}]}]

Prettified JSON export
[
 {
"id": "Sample",
"Title": "About Paris",
"Language": {
  "Name": "English"
},
"Author": {
  "Name": "Don",
  "Location": {
    "City": "Paris",
    "Country": "France"
  }
},
"Content": "Don's document in Azure Cosmos DB is a valid JSON document as defined by the JSON spec.",
"PageViews": 10000,
"Topics": [
  {
    "Title": "History of Paris"
  },
  {
    "Title": "Places to see in Paris"
  }
]
}]

Configurazione avanzataAdvanced configuration

Nella schermata Configurazione avanzata specificare il percorso del file di log in cui scrivere gli errori.In the Advanced configuration screen, specify the location of the log file to which you would like any errors written. In questa pagina vengono applicate le regole seguenti:The following rules apply to this page:

  1. Se non viene fornito un nome di file, tutti gli errori vengono restituiti nella pagina dei risultati.If a file name is not provided, then all errors are returned on the Results page.
  2. Se viene fornito un nome di file senza una directory, il file viene creato (o sovrascritto) nella directory dell'ambiente corrente.If a file name is provided without a directory, then the file is created (or overwritten) in the current environment directory.
  3. Se si seleziona un file esistente, il file viene sovrascritto. Non è prevista l'opzione di accodamento.If you select an existing file, then the file is overwritten, there is no append option.

Quindi, scegliere se registrare tutti i messaggi di errore, quelli critici o nessuno.Then, choose whether to log all, critical, or no error messages. Infine, definire la frequenza con cui il messaggio di trasferimento su schermo viene aggiornato con lo stato di avanzamento.Finally, decide how frequently the on-screen transfer message is updated with its progress.

![Screenshot of Advanced configuration screen](./media/import-data/AdvancedConfiguration.png)

Confermare le impostazioni di importazione e visualizzare la riga di comandoConfirm import settings and view command line

  1. Dopo avere specificato le informazioni di origine e di destinazione e la configurazione avanzata, esaminare il riepilogo della migrazione e, facoltativamente, visualizzare/copiare il comando di migrazione risultante (copiare il comando è utile per automatizzare le operazioni di importazione):After specifying source information, target information, and advanced configuration, review the migration summary and, optionally, view/copy the resulting migration command (copying the command is useful to automate import operations):

    Schermata della pagina di riepilogo

    Schermata della pagina di riepilogo

  2. Una volta verificate le opzioni di origine e di destinazione, fare clic su Import.Once you’re satisfied with your source and target options, click Import. Il tempo trascorso, il conteggio degli elementi trasferiti e le informazioni sugli errori (se non è stato fornito un nome file nella pagina Configurazione avanzata) vengono aggiornati mentre l'importazione è in corso.The elapsed time, transferred count, and failure information (if you didn't provide a file name in the Advanced configuration) update as the import is in process. Al termine dell'importazione è possibile esportare i risultati, ad esempio per gestire gli eventuali errori di importazione.Once complete, you can export the results (for example, to deal with any import failures).

    Screenshot dell'opzione di esportazione in JSON di Azure Cosmos DB

  3. È anche possibile avviare una nuova importazione, mantenendo le impostazioni esistenti, ad esempio, le informazioni della stringa di connessione, la scelta dell'origine e della destinazione e così via, o reimpostando tutti i valori.You may also start a new import, either keeping the existing settings (for example, connection string information, source and target choice, etc.) or resetting all values.

    Screenshot dell'opzione di esportazione in JSON di Azure Cosmos DB

Passaggi successiviNext steps

In questa esercitazione sono state eseguite le attività seguenti:In this tutorial, you've done the following tasks:

  • Installazione dello strumento di migrazione datiInstalled the Data Migration tool
  • Importazione di dati da diverse origini datiImported data from different data sources
  • Esportazione da Azure Cosmos DB a JSONExported from Azure Cosmos DB to JSON

È ora possibile passare all'esercitazione successiva per ottenere informazioni su come eseguire query sui dati usando Azure Cosmos DB.You can now proceed to the next tutorial and learn how to query data using Azure Cosmos DB.