Usare l'utilità di migrazione dati per la migrazione dei dati in Azure Cosmos DBUse Data migration tool to migrate your data to Azure Cosmos DB

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 file JSON, file CSV, SQL, MongoDB, archiviazione tabelle di Azure, Amazon DynamoDB e anche da raccolte di API SQL per 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. È possibile eseguire la migrazione di tali dati in raccolte e tabelle da usare con Azure Cosmos DB.You migrate that data to collections and tables for use with Azure Cosmos DB. L'utilità di migrazione dati può essere usata anche per la migrazione da una raccolta con singola partizione a una raccolta con più partizioni per l'API 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?

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, assicurarsi di eseguire i passaggi seguenti:Before following the instructions in this article, ensure that you do the following steps:

  • Installare Microsoft .NET Framework 4.51 o versione successiva.Install Microsoft .NET Framework 4.51 or higher.

  • Aumentare la velocità effettiva: la durata della migrazione dei dati dipende dalla velocità effettiva configurata per una singola raccolta o un set di raccolte.Increase throughput: The duration of your data migration depends on the amount of throughput you set up for an individual collection or a set of collections. Assicurarsi di aumentare la velocità effettiva per le migrazioni dei dati di dimensioni più grandi.Be sure to increase the throughput for larger data migrations. Dopo avere completato la migrazione, diminuire la velocità effettiva per ridurre i costi.After you've completed the migration, decrease the throughput to save costs. Per altre informazioni sull'aumento della velocità effettiva nel portale di Azure, vedere livelli di prestazioni e piani tariffari in Azure Cosmos DB.For more information about increasing throughput in the Azure portal, see performance levels and pricing tiers in Azure Cosmos DB.

  • Creare risorse di Azure Cosmos DB: prima di iniziare la migrazione dei dati, creare tutte le raccolte dal portale di Azure.Create Azure Cosmos DB resources: Before you start the migrating data, pre-create all your collections from the Azure portal. Per eseguire la migrazione a un account Azure Cosmos DB con velocità effettiva a livello di database, fornire una chiave di partizione quando si creano le raccolte di Azure Cosmos DB.To migrate to an Azure Cosmos DB account that has database level throughput, provide a partition key when you create the Azure Cosmos DB collections.

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, un'opzione specifica consente di inviare il comando associato dopo aver configurato un'operazione di importazione nell'interfaccia utente.In fact, there's an option to output the associated command after setting up an import through the UI. È possibile trasformare i dati di origine tabulari (ad esempio, file CSV o SQL Server) in modo da creare relazioni gerarchiche (documenti secondari) durante l'importazione.You can transform tabular source data, such as SQL Server or CSV files, to create hierarchical relationships (subdocuments) during import. Continuare a leggere per scoprire di più sulle opzioni di origine, sui comandi 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 commands to import from each source, target options, and viewing import results.

InstallazioneInstallation

Il codice sorgente dell'utilità di migrazione è disponibile in GitHub in questo repository.The migration tool source code is available on GitHub in this repository. È possibile scaricare e compilare la soluzione in locale o scaricare un binario precompilato, quindi eseguire uno degli eseguibili seguenti:You can download and compile the solution locally, or download a pre-compiled binary, 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 have 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 have 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

La stringa di connessione è nel formato seguente:The connection string is in the following format:

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

  • <CosmosDB Endpoint> è l'URI dell'endpoint.The <CosmosDB Endpoint> is the endpoint URI. È possibile ottenere questo valore dal portale di Azure.You can get this value from the Azure portal. Accedere all'account Azure Cosmos.Navigate to your Azure Cosmos account. Aprire il riquadro Overview e copiare il valore URI.Open the Overview pane and copy the URI value.
  • <AccountKey> è "Password" oppure CHIAVE PRIMARIA.The <AccountKey> is the "Password" or PRIMARY KEY. È possibile ottenere questo valore dal portale di Azure.You can get this value from the Azure portal. Accedere all'account Azure Cosmos.Navigate to your Azure Cosmos account. Aprire il riquadro Stringhe di connessione oppure Chiavi, quindi copiare la "Password" o il valore CHIAVE PRIMARIA.Open the Connection Strings or Keys pane, and copy the "Password" or PRIMARY KEY value.
  • <CosmosDB Database> è il nome del database CosmosDB.The <CosmosDB Database> is the CosmosDB database name.

Esempio: AccountEndpoint=https://myCosmosDBName.documents.azure.com:443/;AccountKey=wJmFRYna6ttQ79ATmrTMKql8vPri84QBiHTt6oinFkZRvoe7Vv81x9sn6zlVlBY10bEPMgGM982wfYXpWXWB9w==;Database=myDatabaseNameExample: AccountEndpoint=https://myCosmosDBName.documents.azure.com:443/;AccountKey=wJmFRYna6ttQ79ATmrTMKql8vPri84QBiHTt6oinFkZRvoe7Vv81x9sn6zlVlBY10bEPMgGM982wfYXpWXWB9w==;Database=myDatabaseName

Nota

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

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:DocumentDBBulk /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:DocumentDBBulk /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:DocumentDBBulk /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:DocumentDBBulk /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:DocumentDBBulk /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 Cosmos configurato con l'API di Azure Cosmos DB per MongoDB, seguire queste istruzioni.If you're importing to a Cosmos account configured with Azure Cosmos DB's API for MongoDB, follow these instructions.

Con l'opzione dell'utilità di importazione dell'origine MongoDB è possibile importare da una singola raccolta MongoDB, di filtrare facoltativamente i documenti usando una query e di modificare la struttura di documenti usando una proiezione.With the MongoDB source importer option, you can import from a single MongoDB collection, optionally filter documents using a query, and 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 come {pop: {$gt:5000}} o una proiezione come {loc:0} sia per filtrare che per determinare i dati da importare.You may optionally specify or provide a file for a query, such as {pop: {$gt:5000}}, or a projection, such as {loc:0}, to both filter and shape the data that you're importing.

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:DocumentDBBulk /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:DocumentDBBulk /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're 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 have 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:DocumentDBBulk /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'

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:DocumentDBBulk /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:DocumentDBBulk /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 have 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": "https://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": "https://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 tries 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:DocumentDBBulk /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.

È possibile restituire come output i dati che sono stati importati da Archiviazione tabelle di Azure nelle tabelle e nelle entità di Azure Cosmos DB per l'uso con l'API Tabella.You may output data that was imported from Azure Table Storage to Azure Cosmos DB tables and entities for use with the Table API. I dati importati possono anche essere restituiti in raccolte e documenti per l'uso con l'API SQL.Imported data can also be output to collections and documents for use with the SQL API. Tuttavia, l'API Tabella è disponibile solo come destinazione nell'utilità della riga di comando.However, Table API is only available as a target in the command-line utility. Non è possibile esportare nell'API Tabella usando l'interfaccia utente dell'utilità di migrazione dati.You can't 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 don't 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:DocumentDBBulk /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 dell'origine Amazon DynamoDB consente di importare da una singola tabella Amazon DynamoDB.The Amazon DynamoDB source importer option allows you to import from a single Amazon DynamoDB table. È facoltativamente possibile filtrare le entità da importare.It can 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:DocumentDBBulk /t.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:doctest

Importare da una raccolta di API 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>;

È possibile recuperare la stringa di connessione dell'account Azure Cosmos DB dalla pagina Chiavi del portale di Azure, come descritto in Come gestire un account Azure Cosmos DB.You can retrieve the Azure Cosmos DB account connection string from the Keys page of the Azure portal, as described in How to manage an Azure Cosmos DB account. Tuttavia, il nome del database deve essere aggiunto alla stringa di connessione nel formato seguente: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 more than one Azure Cosmos DB collection, 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 that you're importing.

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're importing from a single collection whose name has 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. Retry Interval (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:DocumentDB /s.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /s.Collection:TEColl /t:DocumentDBBulk /t.ConnectionString:" AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:TESessions /t.CollectionThroughput:2500

#Migrate data from more than one Azure Cosmos DB collection to a single Azure Cosmos DB collection
dt.exe /s:DocumentDB /s.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /s.Collection:comp1|comp2|comp3|comp4 /t:DocumentDBBulk /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:DocumentDB /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:DocumentDBBulk /t.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB Database>;" /t.Collection:hbaseimport

Importare nell'API 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.The tool supports import to one single-partitioned Azure Cosmos DB collection. Supporta inoltre l'importazione partizionata con partizionamento dei dati in più raccolte di Azure Cosmos DB con partizione singola.It also supports sharded import whereby data is partitioned across more than one single-partitioned Azure Cosmos DB collection. 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 more than one collection, either enter each collection name individually or use the following syntax to specify more than one collection: collection_prefix[start index - end index]. Quando si specificano più raccolte tramite la sintassi menzionata in precedenza, tenere presente le indicazioni seguenti:When specifying more than one collection using 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 won't be modified.

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

È possibile specificare facoltativamente quale campo dell'origine di importazione deve essere usato come proprietà ID del documento di Azure Cosmos DB durante l'importazione.You may optionally specify which field in the import source should be used as the Azure Cosmos DB document ID property during the import. Se i documenti non hanno questa proprietà, lo strumento di importazione genera un GUID come valore della proprietà ID.If documents don't have 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 (Dimensioni batch): 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 (Disabilita generazione ID automatica): 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 has 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 aren't imported.
  4. Update Existing Documents (Aggiorna documenti esistenti): 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 how often to retry the connection to Azure Cosmos DB during transient failures (for example, network connectivity interruption).
  6. Retry Interval (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 nell'API 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 un'opzione di origine disponibile.The Azure Cosmos DB sequential record importer allows you to import from an available source option 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.The tool supports import to a single (both single-partition and multi-partition) Azure Cosmos DB collection. Supporta inoltre l'importazione partizionata con partizionamento dei dati in più raccolte di Azure Cosmos DB con partizione singola o con più partizioni.It also supports sharded import whereby data is partitioned across more than one single-partition or multi-partition Azure Cosmos DB collection. 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>;

È possibile recuperare la stringa di connessione dell'account Azure Cosmos DB dalla pagina Chiavi del portale di Azure, come descritto in Come gestire un account Azure Cosmos DB.You can retrieve the connection string for the Azure Cosmos DB account from the Keys page of the Azure portal, as described in How to manage an Azure Cosmos DB account. Tuttavia, il nome del database deve essere aggiunto alla stringa di connessione nel formato seguente: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 importare i dati e quindi fare clic sul pulsante Aggiungi.To import to a single collection, enter the name of the collection to import data into, and then click the Add button. Per importare in più raccolte, immettere il nome di ogni raccolta singolarmente.To import to more than one collection, enter each collection name individually. È anche possibile usare la sintassi seguente per specificare più raccolte: prefisso_raccolta[indice iniziale - indice finale].You may also use the following syntax to specify more than one collection: collection_prefix[start index - end index]. Quando si specificano più raccolte tramite la sintassi menzionata in precedenza, tenere presente le indicazioni seguenti:When specifying more than one collection 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 o del database.The throughput setting only applies to collection or database creation. Se la raccolta specificata esiste già, la velocità effettiva non viene modificata.If the specified collection already exists, its throughput won't be modified.

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

È possibile specificare facoltativamente quale campo dell'origine di importazione deve essere usato come proprietà ID del documento di Azure Cosmos DB durante l'importazione.You may optionally specify which field in the import source should be used as the Azure Cosmos DB document ID property during the import. Se i documenti non hanno questa proprietà, lo strumento di importazione genera un GUID come valore della proprietà ID.(If documents don't have 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. Se questo numero è troppo elevato, durante l'importazione potrebbe venire applicata la limitazione della velocità.If this number is raised too much, the import may experience rate limiting.
  2. Disable Automatic Id Generation (Disabilita generazione ID automatica): 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 has 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 aren't imported.
  3. Update Existing Documents (Aggiorna documenti esistenti): 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 how often to retry the connection to Azure Cosmos DB during transient failures (for example, network connectivity interruption).
  5. Retry Interval (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 during 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 all'utilità di migrazione di creare raccolte di API SQL di Azure Cosmos DB 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 risulta ottimale quando si eseguono query di uguaglianza su stringhe.This policy is best when you perform equality queries against strings. È utile anche se si usano query di tipo ORDER BY, di intervallo e di uguaglianza per i numeri.It also works if you use 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 when you use 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 don't 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 has an array of JSON documents. Lo strumento gestisce l'esportazione.The tool handles the export for you. In alternativa, è possibile scegliere di visualizzare il comando di migrazione risultante ed eseguire il comando manualmente.Alternatively, 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

È possibile scegliere facoltativamente di modificare il file JSON risultante.You may optionally choose to prettify the resulting JSON. Questa azione fa aumentare le dimensioni del documento risultante rendendone il contenuto più leggibile.This action will increase the size of the resulting document while making the contents more human readable.

  • Esportazione JSON standardStandard 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"}]}]
    
  • Esportazione JSON modificataPrettified 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"
        }
      ]
      }]
    

Ecco un esempio di riga di comando per esportare il file JSON nell'archiviazione BLOB di Azure:Here is a command-line sample to export the JSON file to Azure Blob storage:

dt.exe /ErrorDetails:All /s:DocumentDB /s.ConnectionString:"AccountEndpoint=<CosmosDB Endpoint>;AccountKey=<CosmosDB Key>;Database=<CosmosDB database_name>" /s.Collection:<CosmosDB collection_name>
/t:JsonFile /t.File:"blobs://<Storage account key>@<Storage account name>.blob.core.windows.net:443/<Container_name>/<Blob_name>"
/t.Overwrite

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 isn't 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's no append option.

  4. 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 della schermata di configurazione avanzata

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, se si vuole, visualizzare o copiare il comando di migrazione risultante.After you specify the source information, target information, and advanced configuration, review the migration summary and view or copy the resulting migration command if you want. Copiare il comando è utile per automatizzare le operazioni di importazione.(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 reimpostando tutti i valori o mantenendo le impostazioni esistenti.You may also start a new import by either resetting all values or keeping the existing settings. Ad esempio, si potrebbe scegliere di mantenere le informazioni della stringa di connessione, la scelta dell'origine e della destinazione e altro ancora.(For example, you may choose to keep connection string information, source and target choice, and more.)

    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.