자습서: 데이터 마이그레이션 도구를 사용하여 Azure Cosmos DB로 데이터 마이그레이션Tutorial: Use Data migration tool to migrate your data to Azure Cosmos DB

적용 대상: SQL API

이 자습서에서는 다양한 원본에서 Azure Cosmos 컨테이너 및 테이블로 데이터를 가져올 수 있는 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 containers and tables. JSON 파일, CSV 파일, SQL, MongoDB, Azure Table Storage, Amazon DynamoDB 및 Azure Cosmos DB SQL API 컬렉션에서도 데이터를 가져올 수 있습니다.You can import from JSON files, CSV files, SQL, MongoDB, Azure Table storage, Amazon DynamoDB, and even Azure Cosmos DB SQL API collections. Azure Cosmos DB에서 사용할 수 있도록 해당 데이터를 컬렉션 및 테이블로 마이그레이션할 수도 있습니다.You migrate that data to collections and tables for use with Azure Cosmos DB. 또한 데이터 마이그레이션 도구는 단일 파티션 컬렉션에서 SQL API용 다중 파티션 컬렉션으로 마이그레이션하는 경우에도 사용할 수 있습니다.The Data Migration tool can also be used when migrating from a single partition collection to a multi-partition collection for the SQL API.

참고

Azure Cosmos DB 데이터 마이그레이션 도구는 소규모 마이그레이션을 위해 설계된 오픈 소스 도구입니다.The Azure Cosmos DB Data Migration tool is an open source tool designed for small migrations. 대규모 마이그레이션의 경우 데이터 수집 가이드를 참조하세요.For larger migrations, view our guide for ingesting data.

이 자습서에서 다루는 작업은 다음과 같습니다.This tutorial covers the following tasks:

  • 데이터 마이그레이션 도구 설치Installing the Data Migration tool
  • 다른 데이터 원본에서 데이터 가져오기Importing data from different data sources
  • Azure Cosmos DB에서 JSON으로 내보내기Exporting from Azure Cosmos DB to JSON

필수 조건Prerequisites

이 문서의 지침을 따르기 전에, 다음 단계를 수행합니다.Before following the instructions in this article, ensure that you do the following steps:

  • Microsoft .NET Framework 4.51 이상을 설치 합니다.Install Microsoft .NET Framework 4.51 or higher.

  • 처리량 증가: 데이터 마이그레이션 기간은 개별 컬렉션 또는 컬렉션 세트에 대해 설정한 처리량에 따라 다릅니다.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. 대량 데이터 마이그레이션의 경우 처리량을 늘려야 합니다.Be sure to increase the throughput for larger data migrations. 마이그레이션을 완료한 후에는 비용을 절약하기 위해 처리량을 줄이세요.After you've completed the migration, decrease the throughput to save costs. Azure Portal에서 처리량을 늘리는 방법에 대한 자세한 내용은 Azure Cosmos DB의 성능 수준가격 책정 계층을 참조하세요.For more information about increasing throughput in the Azure portal, see performance levels and pricing tiers in Azure Cosmos DB.

  • Azure Cosmos DB 리소스 만들기: 데이터 마이그레이션을 시작하기 전에 Azure Portal에서 모든 컬렉션을 미리 만듭니다.Create Azure Cosmos DB resources: Before you start the migrating data, pre-create all your collections from the Azure portal. 데이터베이스 수준 처리량이 있는 Azure Cosmos DB 계정으로 마이그레이션하는 경우에는 Azure Cosmos 컨테이너를 만들 때 파티션 키를 제공합니다.To migrate to an Azure Cosmos DB account that has database level throughput, provide a partition key when you create the Azure Cosmos containers.

중요

Azure Cosmos 계정에 연결할 때 데이터 마이그레이션 도구가 TLS(Transport Layer Security) 1.2를 사용하는지 확인하려면 .NET Framework 버전 4.7을 사용하거나 이 문서에 있는 지침을 따릅니다.To make sure that the Data migration tool uses Transport Layer Security (TLS) 1.2 when connecting to your Azure Cosmos accounts, use the .NET Framework version 4.7 or follow the instructions found in this article.

개요Overview

데이터 마이그레이션 도구는 다음을 비롯한 다양한 원본에서 Azure Cosmos DB로 데이터를 가져오는 오픈 소스 솔루션입니다.The Data Migration tool is an open-source solution that imports data to Azure Cosmos DB from a variety of sources, including:

  • JSON 파일JSON files
  • MongoDBMongoDB
  • SQL ServerSQL Server
  • CSV 파일CSV files
  • Azure Table StorageAzure Table storage
  • Amazon DynamoDBAmazon DynamoDB
  • HBaseHBase
  • Azure Cosmos 컨테이너Azure Cosmos containers

가져오기 도구는 그래픽 사용자 인터페이스(dtui.exe)를 포함하지만 명령줄(dt.exe)에서 구동할 수도 있습니다.While the import tool includes a graphical user interface (dtui.exe), it can also be driven from the command-line (dt.exe). 실제로 UI를 통해 가져오기를 설정한 후 관련 명령을 출력하는 옵션이 있습니다.In fact, there's an option to output the associated command after setting up an import through the UI. 가져오는 동안 계층 관계(하위 문서)를 만들 수 있도록 테이블 형식 원본 데이터(예: SQL Server 또는 CSV 파일)를 변환할 수 있습니다.You can transform tabular source data, such as SQL Server or CSV files, to create hierarchical relationships (subdocuments) during import. 원본 옵션, 각 원본에서 가져오는 샘플 명령, 대상 옵션 및 가져오기 결과 보기에 대해 자세히 알아보려면 계속 진행하세요.Keep reading to learn more about source options, sample commands to import from each source, target options, and viewing import results.

참고

소규모 마이그레이션에는 Azure Cosmos DB 마이그레이션 도구만 사용해야 합니다.You should only use the Azure Cosmos DB migration tool for small migrations. 대규모 마이그레이션의 경우 데이터 수집 가이드를 참조하세요.For large migrations, view our guide for ingesting data.

설치Installation

마이그레이션 도구 소스 코드는 GitHub의 이 리포지토리에서 사용할 수 있습니다.The migration tool source code is available on GitHub in this repository. 솔루션을 로컬로 다운로드하여 컴파일하거나 미리 컴파일된 이진 파일을 다운로드한 후 다음 중 하나를 실행할 수 있습니다.You can download and compile the solution locally, or download a pre-compiled binary, then run either:

  • Dtui.exe : 도구의 그래픽 인터페이스 버전Dtui.exe : Graphical interface version of the tool
  • Dt.exe : 도구의 명령줄 버전Dt.exe : Command-line version of the tool

데이터 원본 선택Select data source

이 도구를 설치하면 이제 데이터를 가져올 차례입니다.Once you've installed the tool, it's time to import your data. 어떤 종류의 데이터를 가져오시겠어요?What kind of data do you want to import?

JSON 파일 가져오기Import JSON files

JSON 파일 원본 가져오기 옵션을 사용하면 단일 문서 JSON 파일이나 각각 JSON 문서 배열을 포함하는 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. 가져올 JSON 파일을 포함하는 폴더를 추가하면, 하위 폴더에서 재귀적으로 파일을 검색하는 옵션도 있습니다.When adding folders that have JSON files to import, you have the option of recursively searching for files in subfolders.

JSON 파일 원본 옵션의 스크린샷 - 데이터베이스 마이그레이션 도구

연결 문자열은 다음 형식입니다.The connection string is in the following format:

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

  • <CosmosDB Endpoint>는 엔드포인트 URI입니다.The <CosmosDB Endpoint> is the endpoint URI. Azure Portal에서 이 값을 가져올 수 있습니다.You can get this value from the Azure portal. Azure Cosmos 계정으로 이동합니다.Navigate to your Azure Cosmos account. 개요 창을 열고 URI 값을 복사합니다.Open the Overview pane and copy the URI value.
  • <AccountKey>는 "암호" 또는 기본 키 입니다.The <AccountKey> is the "Password" or PRIMARY KEY. Azure Portal에서 이 값을 가져올 수 있습니다.You can get this value from the Azure portal. Azure Cosmos 계정으로 이동합니다.Navigate to your Azure Cosmos account. 연결 문자열 또는 창을 열고 "암호" 또는 기본 키 값을 복사합니다.Open the Connection Strings or Keys pane, and copy the "Password" or PRIMARY KEY value.
  • <CosmosDB Database>는 CosmosDB 데이터베이스 이름입니다.The <CosmosDB Database> is the CosmosDB database name.

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

참고

Verify 명령을 사용하여 연결 문자열 필드에 지정된 Cosmos DB 계정에 액세스할 수 있는지 확인합니다.Use the Verify command to ensure that the Cosmos DB account specified in the connection string field can be accessed.

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

MongoDB에서 가져오기Import from MongoDB

중요

Azure Cosmos DB의 MongoDB API로 구성된 Cosmos 계정으로 가져오는 경우 이러한 지침을 따르세요.If you're importing to a Cosmos account configured with Azure Cosmos DB's API for MongoDB, follow these instructions.

MongoDB 원본 가져오기 옵션을 사용하면 단일 MongoDB 컬렉션에서 가져오고 필요에 따라 쿼리를 사용하여 문서를 필터링하거나 프로젝션을 사용하여 문서 구조를 수정할 수 있습니다.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.

MongoDB 원본 옵션의 스크린샷

연결 문자열은 표준 MongoDB 형식입니다.The connection string is in the standard MongoDB format:

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

참고

Verify 명령을 사용하여 연결 문자열 필드에 지정된 MongoDB 인스턴스를 액세스할 수 있는지 확인합니다.Use the Verify command to ensure that the MongoDB instance specified in the connection string field can be accessed.

데이터를 가져올 컬렉션의 이름을 입력합니다.Enter the name of the collection from which data will be imported. 필요에 따라 쿼리(예: {pop: {$gt:5000}}) 및/또는 프로젝션(예: {loc:0})에 대한 파일을 제공하여 가져올 데이터를 필터링하고 형식을 지정할 수 있습니다.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.

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

MongoDB 내보내기 파일 가져오기Import MongoDB export files

중요

MongoDB에 대한 지원을 포함한 Azure Cosmos DB 계정을 가져오는 경우 다음 지침을 수행합니다.If you're importing to an Azure Cosmos DB account with support for MongoDB, follow these instructions.

MongoDB 내보내기 JSON 파일 원본 가져오기 옵션을 사용하면 mongoexport 유틸리티에서 생성된 JSON 파일을 하나 이상 가져올 수 있습니다.The MongoDB export JSON file source importer option allows you to import one or more JSON files produced from the mongoexport utility.

MongoDB 내보내기 원본 옵션의 스크린샷

가져올 MongoDB 내보내기 JSON 파일이 포함된 폴더를 추가할 때 하위 폴더의 파일을 재귀적으로 검색하는 옵션이 있습니다.When adding folders that have MongoDB export JSON files for import, you have the option of recursively searching for files in subfolders.

MongoDB 내보내기 JSON 파일에서 가져오는 명령줄 샘플은 다음과 같습니다.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

SQL Server에서 가져오기Import from SQL Server

SQL 원본 가져오기 옵션을 사용하면 개별 SQL Server 데이터베이스에서 가져오고 필요에 따라 쿼리를 사용하여 가져올 레코드를 필터링할 수 있습니다.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. 또한 중첩 구분 기호를 지정하여 문서 구조를 수정할 수 있습니다(추가 정보 제공 예정).In addition, you can modify the document structure by specifying a nesting separator (more on that in a moment).

SQL 원본 옵션의 스크린샷 - 데이터베이스 마이그레이션 도구

연결 문자열의 형식은 표준 SQL 연결 문자열 형식입니다.The format of the connection string is the standard SQL connection string format.

참고

Verify 명령을 사용하여 연결 문자열 필드에 지정된 SQL Server 인스턴스를 액세스할 수 있는지 확인합니다.Use the Verify command to ensure that the SQL Server instance specified in the connection string field can be accessed.

중첩 구분 기호 속성을 사용하여 가져오는 동안 계층 관계(하위 문서)를 만듭니다.The nesting separator property is used to create hierarchical relationships (sub-documents) during import. 다음과 같은 SQL 쿼리를 고려해 보세요.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'

다음과 같은 (부분) 결과가 반환됩니다.Which returns the following (partial) results:

SQL 쿼리 결과의 스크린샷

Address.AddressType 및 Address.Location.StateProvinceName과 같은 별칭을 확인합니다.Note the aliases such as Address.AddressType and Address.Location.StateProvinceName. 중첩 구분 기호 '.'을 지정하면 가져오기 도구가 가져오는 동안 Address 및 Address.Location 하위 문서를 만듭니다.By specifying a nesting separator of '.', the import tool creates Address and Address.Location subdocuments during the import. 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" } }

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

CSV 파일 가져오기 및 CSV를 JSON으로 변환Import CSV files and convert CSV to JSON

CSV 파일 원본 가져오기 옵션을 사용하면 하나 이상의 CSV 파일을 가져올 수 있습니다.The CSV file source importer option enables you to import one or more CSV files. 가져올 CSV 파일이 포함된 폴더를 추가하면, 하위 폴더에서 재귀적으로 파일을 검색하는 옵션도 있습니다.When adding folders that have CSV files for import, you have the option of recursively searching for files in subfolders.

CSV 원본 옵션의 스크린샷 - CSV에서 JSON으로

SQL 원본과 마찬가지로, 중첩 구분 기호 속성을 사용하여 가져오는 동안 계층 관계(하위 문서)를 만들 수 있습니다.Similar to the SQL source, the nesting separator property may be used to create hierarchical relationships (sub-documents) during import. 다음과 같은 CSV 머리글 행과 데이터 행을 고려하세요.Consider the following CSV header row and data rows:

CSV 샘플 레코드의 스크린샷 - CSV에서 JSON으로

DomainInfo.Domain_Name 및 RedirectInfo.Redirecting과 같은 별칭을 확인하세요.Note the aliases such as DomainInfo.Domain_Name and RedirectInfo.Redirecting. 중첩 구분 기호 '.'을 지정하면 가져오기 도구가 가져오는 동안 DomainInfo 및 RedirectInfo 하위 문서를 만듭니다.By specifying a nesting separator of '.', the import tool will create DomainInfo and RedirectInfo subdocuments during the import. 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" }

가져오기 도구는 CSV 파일의 따옴표가 없는 값에 대한 형식 정보를 유추하려고 합니다(따옴표로 묶인 값은 항상 문자열로 처리됨).The import tool tries to infer type information for unquoted values in CSV files (quoted values are always treated as strings). 숫자, 날짜/시간, 부울 순서로 형식이 식별됩니다.Types are identified in the following order: number, datetime, boolean.

CSV 가져오기에 대해 다른 두 가지 사항을 기억해야 합니다.There are two other things to note about CSV import:

  1. 기본적으로 따옴표가 없는 값이 항상 잘리지만, 따옴표로 묶인 값은 그대로 유지됩니다.By default, unquoted values are always trimmed for tabs and spaces, while quoted values are preserved as-is. Trim 따옴표로 묶인 값 확인란을 선택 또는 /s.TrimQuoted 명령줄 옵션으로 이 동작을 재정의할 수 있습니다.This behavior can be overridden with the Trim quoted values checkbox or the /s.TrimQuoted command-line option.
  2. 기본적으로는 따옴표가 없는 null은 null 값으로 처리됩니다.By default, an unquoted null is treated as a null value. 이 동작은 따옴표가 없는 NULL을 문자열 확인란이나 /s.NoUnquotedNulls 명령줄 옵션으로 재정의할 수 있습니다(예: 따옴표가 없는 null을 "null" 문자열로 처리).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.

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

Azure Table Storage에서 가져오기Import from Azure Table storage

Azure Table Storage 원본 가져오기 옵션을 사용하면 개별 Azure Table Storage 테이블에서 가져올 수 있습니다.The Azure Table storage source importer option allows you to import from an individual Azure Table storage table. 필요에 따라 가져올 테이블 엔터티를 필터링할 수 있습니다.Optionally, you can filter the table entities to be imported.

Azure Table Storage에서 가져온 데이터를 Table API에서 사용하기 위해 Azure Cosmos DB 테이블 및 엔터티를 출력할 수 있습니다.You may output data that was imported from Azure Table Storage to Azure Cosmos DB tables and entities for use with the Table API. 가져온 데이터를 SQL API에서 사용하기 위해 컬렉션 및 문서로 출력할 수도 있습니다.Imported data can also be output to collections and documents for use with the SQL API. 그러나 Table API는 명령줄 유틸리티의 대상으로만 사용할 수 있습니다.However, Table API is only available as a target in the command-line utility. 따라서 데이터 마이그레이션 도구 사용자 인터페이스를 사용하여 Table API로 내보낼 수 없습니다.You can't export to Table API by using the Data Migration tool user interface. 자세한 정보는 Azure Cosmos DB Table API와 함께 사용할 데이터 가져오기를 참조하세요.For more information, see Import data for use with the Azure Cosmos DB Table API.

Azure Table Storage 원본 옵션의 스크린샷

Azure Table Storage 연결 문자열의 형식은 다음과 같습니다.The format of the Azure Table storage connection string is:

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

참고

Verify 명령을 사용하여 연결 문자열 필드에 지정된 Azure Table Storage 인스턴스를 액세스할 수 있는지 확인합니다.Use the Verify command to ensure that the Azure Table storage instance specified in the connection string field can be accessed.

가져올 Azure 테이블의 이름을 입력합니다.Enter the name of the Azure table from to import from. 필요에 따라 필터를 지정할 수 있습니다.You may optionally specify a filter.

Azure Table Storage 원본 가져오기 옵션에는 다음과 같은 추가 옵션이 있습니다.The Azure Table storage source importer option has the following additional options:

  1. 내부 필드 포함Include Internal Fields
    1. 모두 - 모든 내부 필드 포함(PartitionKey, RowKey 및 Timestamp)All - Include all internal fields (PartitionKey, RowKey, and Timestamp)
    2. 없음 - 모든 내부 필드 제외None - Exclude all internal fields
    3. RowKey - RowKey 필드만 포함RowKey - Only include the RowKey field
  2. 열 선택Select Columns
    1. Azure Table Storage 필터는 프로젝션을 지원하지 않습니다.Azure Table storage filters don't support projections. 특정 Azure 테이블 엔터티 속성만 가져오려는 경우 열 선택 목록에 추가합니다.If you want to only import specific Azure Table entity properties, add them to the Select Columns list. 다른 모든 엔터티 속성은 무시됩니다.All other entity properties are ignored.

Azure Table Storage에서 가져오는 명령줄 샘플은 다음과 같습니다.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

Amazon DynamoDB에서 가져오기Import from Amazon DynamoDB

Amazon DynamoDB 원본 가져오기 옵션을 사용하면 단일 Amazon DynamoDB 테이블에서 가져올 수 있습니다.The Amazon DynamoDB source importer option allows you to import from a single Amazon DynamoDB table. 필요에 따라 가져올 엔터티를 필터링할 수 있습니다.It can optionally filter the entities to be imported. 여러 템플릿이 제공되므로 가져오기를 최대한 쉽게 설정할 수 있습니다.Several templates are provided so that setting up an import is as easy as possible.

Amazon DynamoDB 원본 옵션의 스크린샷 - 데이터베이스 마이그레이션 도구.

템플릿이 있는 Amazon DynamoDB 원본 옵션의 스크린샷 - 데이터베이스 마이그레이션 도구.

Amazon DynamoDB 연결 문자열의 형식은 다음과 같습니다.The format of the Amazon DynamoDB connection string is:

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

참고

Verify 명령을 사용하여 연결 문자열 필드에 지정된 Amazon DynamoDB 인스턴스를 액세스할 수 있는지 확인합니다.Use the Verify command to ensure that the Amazon DynamoDB instance specified in the connection string field can be accessed.

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 database>;" /t.Collection:catalogCollection /t.CollectionThroughput:2500

Azure Blob Storage에서 가져오기Import from Azure Blob storage

JSON 파일, MongoDB 내보내기 파일 및 CSV 파일 원본 가져오기 옵션을 통해 Azure Blob Storage에서 하나 이상의 파일을 가져올 수 있습니다.The JSON file, MongoDB export file, and CSV file source importer options allow you to import one or more files from Azure Blob storage. Blob 컨테이너 URL 및 계정 키를 지정한 후에 가져올 파일을 선택하는 정규식을 제공합니다.After specifying a Blob container URL and Account Key, provide a regular expression to select the file(s) to import.

Blob 파일 원본 옵션의 스크린샷

Azure Blob Storage에서 JSON 파일을 가져오려면 명령줄 예제는 다음과 같습니다.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

SQL API 컬렉션에서 가져오기Import from a SQL API collection

Azure Cosmos DB 원본 가져오기 옵션을 사용하면 필요에 따라 쿼리를 사용하여 문서를 필터링하고 하나 이상의 Azure Cosmos 컨테이너에서 데이터를 가져올 수 있습니다.The Azure Cosmos DB source importer option allows you to import data from one or more Azure Cosmos containers and optionally filter documents using a query.

Azure Cosmos DB 원본 옵션의 스크린샷

Azure Cosmos DB 연결 문자열의 형식은 다음과 같습니다.The format of the Azure Cosmos DB connection string is:

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

Azure Cosmos DB 계정을 관리하는 방법에 설명된 대로 Azure Portal의 키 페이지에서 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. 그러나 데이터베이스의 이름을 다음 형식으로 연결 문자열에 추가해야 합니다.However, the name of the database needs to be appended to the connection string in the following format:

Database=<CosmosDB Database>;

참고

Verify 명령을 사용하여 연결 문자열 필드에 지정된 Azure Cosmos DB 인스턴스를 액세스할 수 있는지 확인합니다.Use the Verify command to ensure that the Azure Cosmos DB instance specified in the connection string field can be accessed.

단일 Azure Cosmos 컨테이너에서 가져오려면 데이터를 가져올 컬렉션의 이름을 입력합니다.To import from a single Azure Cosmos container, enter the name of the collection to import data from. 둘 이상의 Azure Cosmos 컨테이너에서 가져오려면 하나 이상의 컬렉션 이름과 일치하는 정규식을 제공합니다(예: collection01 | collection02 | collection03).To import from more than one Azure Cosmos container, provide a regular expression to match one or more collection names (for example, collection01 | collection02 | collection03). 필요에 따라 쿼리를 지정하거나 쿼리에 대한 파일을 제공하여 가져올 데이터를 필터링하고 형식을 지정할 수 있습니다.You may optionally specify, or provide a file for, a query to both filter and shape the data that you're importing.

참고

컬렉션 필드 이름이 정규식 문자를 포함하므로 이름에 정규식 문자를 포함한 단일 컬렉션에서 가져오는 경우 해당 문자는 이스케이프되어야 합니다.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.

Azure Cosmos DB 원본 가져오기 옵션에는 다음과 같은 고급 옵션이 있습니다.The Azure Cosmos DB source importer option has the following advanced options:

  1. 내부 필드 포함: 내보내기에 Azure Cosmos DB 문서 시스템 속성(예: _rid, _ts)을 포함할지 여부를 지정합니다.Include Internal Fields: Specifies whether or not to include Azure Cosmos DB document system properties in the export (for example, _rid, _ts).
  2. 실패 시 재시도 횟수: 일시적 오류(예: 네트워크 연결 중단)의 경우 Azure Cosmos DB에 대한 연결을 재시도할 횟수를 지정합니다.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. 재시도 간격: 일시적 오류(예: 네트워크 연결 중단)의 경우 Azure Cosmos DB에 대한 연결을 재시도하는 간격을 지정합니다.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. 연결 모드: Azure Cosmos DB에 사용할 연결 모드를 지정합니다.Connection Mode: Specifies the connection mode to use with Azure Cosmos DB. 사용 가능한 선택 사항은 DirectTcp, DirectHttps 및 게이트웨이입니다.The available choices are DirectTcp, DirectHttps, and Gateway. 직접 연결 모드는 더 빠르고, 게이트웨이 모드는 포트 443만 사용하므로 더 방화벽 친화적입니다.The direct connection modes are faster, while the gateway mode is more firewall friendly as it only uses port 443.

Azure Cosmos DB 원본 고급 옵션의 스크린샷

가져오기 도구는 기본적으로 DirectTcp 연결 모드로 설정되어 있습니다.The import tool defaults to connection mode DirectTcp. 방화벽 문제가 발생하는 경우 포트 443만 요구하는 게이트웨이 연결 모드로 전환합니다.If you experience firewall issues, switch to connection mode Gateway, as it only requires port 443.

Azure Cosmos DB에서 가져오는 몇 가지 명령줄 샘플은 다음과 같습니다.Here are some command-line samples to import from Azure Cosmos DB:

#Migrate data from one Azure Cosmos container to another Azure Cosmos containers
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 container to a single Azure Cosmos container
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 container 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

또한 Azure Cosmos DB 데이터 가져오기 도구는 Azure Cosmos DB 에뮬레이터에서 데이터를 가져오도록 지원합니다.The Azure Cosmos DB Data Import Tool also supports import of data from the Azure Cosmos DB Emulator. 로컬 에뮬레이터에서 데이터를 가져올 때 엔드포인트를 https://localhost:<port>로 설정합니다.When importing data from a local emulator, set the endpoint to https://localhost:<port>.

HBase에서 가져오기Import from HBase

HBase 원본 가져오기 옵션을 사용하면 HBase 테이블에서 데이터를 가져오고 필요에 따라 데이터를 필터링할 수 있습니다.The HBase source importer option allows you to import data from an HBase table and optionally filter the data. 여러 템플릿이 제공되므로 가져오기를 최대한 쉽게 설정할 수 있습니다.Several templates are provided so that setting up an import is as easy as possible.

HBase 원본 옵션의 스크린샷.

필터 컨텍스트 메뉴가 확장된 HBase 원본 옵션의 스크린샷.

HBase Stargate 연결 문자열의 형식은 다음과 같습니다.The format of the HBase Stargate connection string is:

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

참고

Verify 명령을 사용하여 연결 문자열 필드에 지정된 HBase 인스턴스를 액세스할 수 있는지 확인합니다.Use the Verify command to ensure that the HBase instance specified in the connection string field can be accessed.

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

SQL API로 가져오기(대량 가져오기)Import to the SQL API (Bulk Import)

Azure Cosmos DB 대량 가져오기를 사용하면 효율성을 위해 Azure Cosmos DB 저장 프로시저를 통해 사용 가능한 모든 원본 옵션에서 가져올 수 있습니다.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. 도구는 하나의 단일 분할 Azure Cosmos 컨테이너로의 가져오기를 지원합니다.The tool supports import to one single-partitioned Azure Cosmos container. 또한 둘 이상의 단일 분할 Azure Cosmos 컨테이너 간에 데이터를 분할하는 분할된 가져오기를 지원합니다.It also supports sharded import whereby data is partitioned across more than one single-partitioned Azure Cosmos container. 데이터를 분할하는 방법에 대한 자세한 내용은 Azure Cosmos DB에서 분할 및 크기 조정을 참조하세요.For more information about partitioning data, see Partitioning and scaling in Azure Cosmos DB. 이 도구는 대상 컬렉션에서 저장 프로시저를 만들고 실행한 다음 삭제합니다.The tool creates, executes, and then deletes the stored procedure from the target collection(s).

Azure Cosmos DB 대량 옵션의 스크린샷

Azure Cosmos DB 연결 문자열의 형식은 다음과 같습니다.The format of the Azure Cosmos DB connection string is:

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

Azure Cosmos DB 계정을 관리하는 방법에 설명된 대로 Azure Cosmos DB 계정 연결 문자열은 Azure Portal의 키 페이지에서 검색할 수 있지만 데이터베이스의 이름은 다음 형식으로 연결 문자열에 추가되어야 합니다.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>;

참고

Verify 명령을 사용하여 연결 문자열 필드에 지정된 Azure Cosmos DB 인스턴스를 액세스할 수 있는지 확인합니다.Use the Verify command to ensure that the Azure Cosmos DB instance specified in the connection string field can be accessed.

단일 컬렉션으로 가져오려면, 데이터를 가져올 컬렉션의 이름을 입력하고 추가 단추를 클릭합니다.To import to a single collection, enter the name of the collection to import data from and click the Add button. 둘 이상의 컬렉션을 가져오려면 개별적으로 각 컬렉션 이름을 입력하거나 둘 이상의 컬렉션을 지정하려면 다음 구문을 사용합니다. collection_prefix [start index - end index].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]. 앞서 언급한 구문을 사용하여 둘 이상의 컬렉션을 지정할 때 다음 지침에 유의해야 합니다.When specifying more than one collection using the aforementioned syntax, keep the following guidelines in mind:

  1. 정수 범위 이름 패턴만 지원됩니다.Only integer range name patterns are supported. 예를 들어, 컬렉션 [0-3]을 지정하면 collection0, collection1, collection2, collection3 컬렉션을 생성합니다.For example, specifying collection[0-3] creates the following collections: collection0, collection1, collection2, collection3.
  2. 축약된 구문을 사용할 수 있습니다. [3] 컬렉션은 1단계에서 설명한 동일한 집합을 생성합니다.You can use an abbreviated syntax: collection[3] creates the same set of collections mentioned in step 1.
  3. 둘 이상의 대체를 제공할 수 있습니다.More than one substitution can be provided. 예를 들어, 컬렉션 [0-1] [0-9]는 0이 이름 앞에 오는 20개의 컬렉션을 생성합니다(collection01, ..02, ..03).For example, collection[0-1] [0-9] generates 20 collection names with leading zeros (collection01, ..02, ..03).

컬렉션 이름이 지정되면 원하는 컬렉션 처리량을 선택합니다(400RU~10,000RU).Once the collection name(s) have been specified, choose the desired throughput of the collection(s) (400 RUs to 10,000 RUs). 가져오기 성능을 최적화하려면 더 높은 처리량을 선택합니다.For best import performance, choose a higher throughput. 성능 수준에 대한 자세한 내용은 Azure Cosmos DB의 성능 수준을 참조하세요.For more information about performance levels, see Performance levels in Azure Cosmos DB.

참고

성능 처리량 설정은 컬렉션 생성에만 적용됩니다.The performance throughput setting only applies to collection creation. 지정된 컬렉션이 이미 있는 경우 해당 처리량은 수정되지 않습니다.If the specified collection already exists, its throughput won't be modified.

둘 이상의 컬렉션을 가져올 때 가져오기 도구는 해시 기반 분할을 지원합니다.When you import to more than one collection, the import tool supports hash-based sharding. 이 시나리오에서는 파티션 키로 사용하려는 문서 속성을 지정합니다.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.)

필요에 따라 가져오는 동안 Azure Cosmos DB 문서 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. 문서에 이 속성에 없는 경우 가져오기 도구가 ID 속성 값으로 GUID를 생성합니다.If documents don't have this property, then the import tool generates a GUID as the ID property value.

가져오는 동안 사용할 수 있는 다양한 고급 옵션이 있습니다.There are a number of advanced options available during import. 먼저, 도구에 기본 대량 가져오기 저장 프로시저(BulkInsert.js)가 포함되어 있지만 사용자 고유의 가져오기 저장 프로시저를 지정할 수 있습니다.First, while the tool includes a default bulk import stored procedure (BulkInsert.js), you may choose to specify your own import stored procedure:

Azure Cosmos DB 대량 삽입 저장 프로시저 옵션의 스크린샷

또한 SQL Server 또는 MongoDB 등에서 날짜 형식을 가져오는 경우 다음 3개의 가져오기 옵션 중에서 선택할 수 있습니다.Additionally, when importing date types (for example, from SQL Server or MongoDB), you can choose between three import options:

Azure Cosmos DB 날짜/시간 가져오기 옵션의 스크린샷

  • 문자열: 문자열 값으로 유지String: Persist as a string value
  • Epoch: Epoch 숫자 값으로 유지Epoch: Persist as an Epoch number value
  • 둘 다: 문자열 및 Epoch 숫자 값으로 유지.Both: Persist both string and Epoch number values. 이 옵션은 하위 문서를 만듭니다. 예: "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 }

Azure Cosmos DB 대량 가져오기에는 다음과 같은 추가 고급 옵션이 있습니다.The Azure Cosmos DB Bulk importer has the following additional advanced options:

  1. Batch 크기: 기본적으로 도구의 배치 크기는 50으로 설정되어 있습니다.Batch Size: The tool defaults to a batch size of 50. 가져올 문서가 크면 배치 크기를 줄이는 것이 좋습니다.If the documents to be imported are large, consider lowering the batch size. 반대로, 가져올 문서가 작으면 배치 크기를 늘리는 것이 좋습니다.Conversely, if the documents to be imported are small, consider raising the batch size.
  2. 최대 스크립트 크기(바이트): 기본적으로 도구의 최대 스크립트 크기는 512KB입니다.Max Script Size (bytes): The tool defaults to a max script size of 512 KB.
  3. 자동 Id 생성 사용 안 함: 가져올 모든 문서에 ID 필드가 포함되어 있는 경우 이 옵션을 선택하면 성능을 향상시킬 수 있습니다.Disable Automatic Id Generation: If every document to be imported has an ID field, then selecting this option can increase performance. 고유 ID 필드가 누락된 문서는 가져오지 않습니다.Documents missing a unique ID field aren't imported.
  4. 기존 문서 업데이트 이 도구는 기본적으로 기존 문서를 충돌하는 ID로 대체하지 않습니다.Update Existing Documents: The tool defaults to not replacing existing documents with ID conflicts. 이 옵션을 선택하면 기존 문서를 일치하는 ID로 덮어쓸 수 있습니다.Selecting this option allows overwriting existing documents with matching IDs. 이 기능은 기존 문서를 업데이트하는 예약된 데이터 마이그레이션에 유용합니다.This feature is useful for scheduled data migrations that update existing documents.
  5. 실패 시 재시도 횟수: 일시적 오류(예: 네트워크 연결 중단)의 경우 Azure Cosmos DB에 대한 연결을 다시 시도하는 빈도를 지정합니다.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. 재시도 간격: 일시적 오류(예: 네트워크 연결 중단)의 경우 Azure Cosmos DB에 대한 연결을 재시도하는 간격을 지정합니다.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. 연결 모드: Azure Cosmos DB에 사용할 연결 모드를 지정합니다.Connection Mode: Specifies the connection mode to use with Azure Cosmos DB. 사용 가능한 선택 사항은 DirectTcp, DirectHttps 및 게이트웨이입니다.The available choices are DirectTcp, DirectHttps, and Gateway. 직접 연결 모드는 더 빠르고, 게이트웨이 모드는 포트 443만 사용하므로 더 방화벽 친화적입니다.The direct connection modes are faster, while the gateway mode is more firewall friendly as it only uses port 443.

Azure Cosmos DB 대량 가져오기 고급 옵션의 스크린샷

가져오기 도구는 기본적으로 DirectTcp 연결 모드로 설정되어 있습니다.The import tool defaults to connection mode DirectTcp. 방화벽 문제가 발생하는 경우 포트 443만 요구하는 게이트웨이 연결 모드로 전환합니다.If you experience firewall issues, switch to connection mode Gateway, as it only requires port 443.

SQL API로 가져오기(순차 레코드 가져오기)Import to the SQL API (Sequential Record Import)

Azure Cosmos DB 순차 레코드 가져오기를 사용하면 레코드 단위로 사용 가능한 모든 원본 옵션에서 가져올 수 있습니다.The Azure Cosmos DB sequential record importer allows you to import from an available source option on a record-by-record basis. 저장 프로시저의 할당량에 도달한 기존 컬렉션으로 가져오는 경우 이 옵션을 선택할 수 있습니다.You might choose this option if you’re importing to an existing collection that has reached its quota of stored procedures. 도구는 단일(단일 파티션 및 다중 파티션 모두) Azure Cosmos 컨테이너로의 가져오기를 지원합니다.The tool supports import to a single (both single-partition and multi-partition) Azure Cosmos container. 또한 둘 이상의 단일 파티션 또는 다중 파티션 Azure Cosmos 컨테이너 간에 데이터를 분할하는 분할된 가져오기를 지원합니다.It also supports sharded import whereby data is partitioned across more than one single-partition or multi-partition Azure Cosmos container. 데이터를 분할하는 방법에 대한 자세한 내용은 Azure Cosmos DB에서 분할 및 크기 조정을 참조하세요.For more information about partitioning data, see Partitioning and scaling in Azure Cosmos DB.

Azure Cosmos DB 순차 레코드 가져오기 옵션의 스크린샷

Azure Cosmos DB 연결 문자열의 형식은 다음과 같습니다.The format of the Azure Cosmos DB connection string is:

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

Azure Cosmos DB 계정을 관리하는 방법에 설명된 대로 Azure Portal의 키 페이지에서 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. 그러나 데이터베이스의 이름을 다음 형식으로 연결 문자열에 추가해야 합니다.However, the name of the database needs to be appended to the connection string in the following format:

Database=<Azure Cosmos database>;

참고

Verify 명령을 사용하여 연결 문자열 필드에 지정된 Azure Cosmos DB 인스턴스를 액세스할 수 있는지 확인합니다.Use the Verify command to ensure that the Azure Cosmos DB instance specified in the connection string field can be accessed.

단일 컬렉션으로 가져오려면, 데이터를 가져올 컬렉션의 이름을 입력하고 추가 단추를 클릭합니다.To import to a single collection, enter the name of the collection to import data into, and then click the Add button. 둘 이상의 컬렉션을 가져오려면 각 컬렉션 이름을 따로 입력합니다.To import to more than one collection, enter each collection name individually. 둘 이상의 컬렉션을 지정하려면 다음 구문을 사용할 수도 있습니다. collection_prefix [start index - end index].You may also use the following syntax to specify more than one collection: collection_prefix [start index - end index]. 앞서 언급한 구문을 사용하여 둘 이상의 컬렉션을 지정할 때 다음 지침에 유의해야 합니다.When specifying more than one collection via the aforementioned syntax, keep the following guidelines in mind:

  1. 정수 범위 이름 패턴만 지원됩니다.Only integer range name patterns are supported. 예를 들어, 컬렉션 [0-3]을 지정하면 collection0, collection1, collection2, collection3 컬렉션을 생성합니다.For example, specifying collection[0-3] creates the following collections: collection0, collection1, collection2, collection3.
  2. 축약된 구문을 사용할 수 있습니다. [3] 컬렉션은 1단계에서 설명한 동일한 집합을 생성합니다.You can use an abbreviated syntax: collection[3] creates the same set of collections mentioned in step 1.
  3. 둘 이상의 대체를 제공할 수 있습니다.More than one substitution can be provided. 예를 들어, 컬렉션 [0-1] [0-9]는 0이 이름 앞에 오는 20개의 컬렉션을 생성합니다(collection01, ..02, ..03).For example, collection[0-1] [0-9] creates 20 collection names with leading zeros (collection01, ..02, ..03).

컬렉션 이름이 지정되면 원하는 컬렉션 처리량을 선택합니다(400RU~250,000RU).Once the collection name(s) have been specified, choose the desired throughput of the collection(s) (400 RUs to 250,000 RUs). 가져오기 성능을 최적화하려면 더 높은 처리량을 선택합니다.For best import performance, choose a higher throughput. 성능 수준에 대한 자세한 내용은 Azure Cosmos DB의 성능 수준을 참조하세요.For more information about performance levels, see Performance levels in Azure Cosmos DB. 처리량 >10,000RU로 컬렉션에 가져오기는 파티션 키가 필요합니다.Any import to collections with throughput >10,000 RUs require a partition key. 250,000RU 이상을 보유하도록 선택한 경우에는 계정을 늘리도록 포털에 요청을 접수해야 합니다.If you choose to have more than 250,000 RUs, you need to file a request in the portal to have your account increased.

참고

처리량 설정은 컬렉션 또는 데이터베이스 생성에만 적용됩니다.The throughput setting only applies to collection or database creation. 지정된 컬렉션이 이미 있는 경우 해당 처리량은 수정되지 않습니다.If the specified collection already exists, its throughput won't be modified.

둘 이상의 컬렉션을 가져올 때 가져오기 도구는 해시 기반 분할을 지원합니다.When importing to more than one collection, the import tool supports hash-based sharding. 이 시나리오에서는 파티션 키로 사용하려는 문서 속성을 지정합니다.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.)

필요에 따라 가져오는 동안 Azure Cosmos DB 문서 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. (문서에 이 속성에 없는 경우 가져오기 도구가 ID 속성 값으로 GUID를 생성합니다.)(If documents don't have this property, then the import tool generates a GUID as the ID property value.)

가져오는 동안 사용할 수 있는 다양한 고급 옵션이 있습니다.There are a number of advanced options available during import. 먼저, SQL Server 또는 MongoDB 등에서 날짜 형식을 가져오는 경우 다음 3개의 가져오기 옵션 중에서 선택할 수 있습니다.First, when importing date types (for example, from SQL Server or MongoDB), you can choose between three import options:

Azure Cosmos DB 날짜/시간 가져오기 옵션의 스크린샷

  • 문자열: 문자열 값으로 유지String: Persist as a string value
  • Epoch: Epoch 숫자 값으로 유지Epoch: Persist as an Epoch number value
  • 둘 다: 문자열 및 Epoch 숫자 값으로 유지.Both: Persist both string and Epoch number values. 이 옵션은 하위 문서를 만듭니다. 예: "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 }

Azure Cosmos DB - 순차 레코드 가져오기에는 다음과 같은 추가 고급 옵션이 있습니다.The Azure Cosmos DB - Sequential record importer has the following additional advanced options:

  1. 병렬 요청 수: 기본적으로 도구의 병렬 요청 수는 2개로 설정됩니다.Number of Parallel Requests: The tool defaults to two parallel requests. 가져올 문서가 작으면 병렬 요청 수를 늘리는 것이 좋습니다.If the documents to be imported are small, consider raising the number of parallel requests. 이 개수를 너무 많이 늘리면 가져오기 시 속도 제한이 발생할 수 있습니다.If this number is raised too much, the import may experience rate limiting.
  2. 자동 Id 생성 사용 안 함: 가져올 모든 문서에 ID 필드가 포함되어 있는 경우 이 옵션을 선택하면 성능을 향상시킬 수 있습니다.Disable Automatic Id Generation: If every document to be imported has an ID field, then selecting this option can increase performance. 고유 ID 필드가 누락된 문서는 가져오지 않습니다.Documents missing a unique ID field aren't imported.
  3. 기존 문서 업데이트 이 도구는 기본적으로 기존 문서를 충돌하는 ID로 대체하지 않습니다.Update Existing Documents: The tool defaults to not replacing existing documents with ID conflicts. 이 옵션을 선택하면 기존 문서를 일치하는 ID로 덮어쓸 수 있습니다.Selecting this option allows overwriting existing documents with matching IDs. 이 기능은 기존 문서를 업데이트하는 예약된 데이터 마이그레이션에 유용합니다.This feature is useful for scheduled data migrations that update existing documents.
  4. 실패 시 재시도 횟수: 일시적 오류(예: 네트워크 연결 중단)의 경우 Azure Cosmos DB에 대한 연결을 다시 시도하는 빈도를 지정합니다.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. 재시도 간격: 일시적 오류(예: 네트워크 연결 중단)의 경우 Azure Cosmos DB에 대한 연결을 다시 시도하는 간격을 지정합니다.Retry Interval: Specifies how long to wait between retrying the connection to Azure Cosmos DB during transient failures (for example, network connectivity interruption).
  6. 연결 모드: Azure Cosmos DB에 사용할 연결 모드를 지정합니다.Connection Mode: Specifies the connection mode to use with Azure Cosmos DB. 사용 가능한 선택 사항은 DirectTcp, DirectHttps 및 게이트웨이입니다.The available choices are DirectTcp, DirectHttps, and Gateway. 직접 연결 모드는 더 빠르고, 게이트웨이 모드는 포트 443만 사용하므로 더 방화벽 친화적입니다.The direct connection modes are faster, while the gateway mode is more firewall friendly as it only uses port 443.

Azure Cosmos DB 순차 레코드 가져오기 고급 옵션의 스크린샷

가져오기 도구는 기본적으로 DirectTcp 연결 모드로 설정되어 있습니다.The import tool defaults to connection mode DirectTcp. 방화벽 문제가 발생하는 경우 포트 443만 요구하는 게이트웨이 연결 모드로 전환합니다.If you experience firewall issues, switch to connection mode Gateway, as it only requires port 443.

인덱싱 정책 지정Specify an indexing policy

가져오는 동안 마이그레이션 도구가 Azure Cosmos DB SQL API 컬렉션을 만들 수 있도록 하는 경우 컬렉션의 인덱싱 정책을 지정할 수 있습니다.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. Azure Cosmos DB 대량 가져오기의 고급 옵션 섹션 및 Azure Cosmos DB 순차 레코드 옵션에서 인덱싱 정책 섹션으로 이동합니다.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.

Azure Cosmos DB 인덱싱 정책 고급 옵션의 스크린샷.

인덱싱 정책 고급 옵션을 사용하여 인덱싱 정책 파일을 선택하고 인덱싱 정책을 수동으로 입력하거나 인덱싱 정책 텍스트 상자를 마우스 오른쪽 단추로 클릭하여 일련의 기본 템플릿 중에 선택할 수 있습니다.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).

도구가 제공하는 정책 템플릿은 다음과 같습니다.The policy templates the tool provides are:

  • 기본값Default. 이 정책은 문자열에 대해 같음 쿼리를 수행할 때 가장 적합합니다.This policy is best when you perform equality queries against strings. 숫자에 대해 ORDER BY, 범위 및 같음 쿼리를 사용할 때도 적용됩니다.It also works if you use ORDER BY, range, and equality queries for numbers. 이 정책에는 범위보다 더 낮은 인덱스 스토리지 오버헤드가 있습니다.This policy has a lower index storage overhead than Range.
  • 범위입니다.Range. 이 정책은 숫자와 문자열 모두에 ORDER BY, 범위 및 같음 쿼리를 사용할 때 가장 좋습니다.This policy is best when you use ORDER BY, range, and equality queries on both numbers and strings. 이 정책에는 기본값 또는 해시보다 더 높은 인덱스 스토리지 오버헤드가 있습니다.This policy has a higher index storage overhead than Default or Hash.

대상 정보를 지정하는 Azure Cosmos DB 인덱싱 정책 고급 옵션의 스크린샷.

참고

인덱싱 정책을 지정하지 않으면 기본 정책이 적용됩니다.If you don't specify an indexing policy, then the default policy is applied. 인덱싱 정책에 대한 자세한 내용은 Azure Cosmos DB 인덱싱 정책을 참조하세요.For more information about indexing policies, see Azure Cosmos DB indexing policies.

JSON 파일로 내보내기Export to JSON file

Azure Cosmos DB JSON 내보내기를 사용하면 사용 가능한 모든 원본 옵션을 JSON 문서 배열이 포함된 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. 이 도구는 자동으로 내보내기를 처리합니다.The tool handles the export for you. 또는 사용자가 결과 마이그레이션 명령을 보고 직접 명령을 실행할 수 있습니다.Alternatively, you can choose to view the resulting migration command and run the command yourself. 결과 JSON 파일은 로컬로 또는 Azure Blob Storage에 저장될 수도 있습니다.The resulting JSON file may be stored locally or in Azure Blob storage.

Azure Cosmos DB JSON 로컬 파일 내보내기 옵션의 스크린샷

Azure Cosmos DB JSON Azure Blob 스토리지 내보내기 옵션의 스크린샷

필요에 따라 결과 JSON을 꾸밀 수 있습니다.You may optionally choose to prettify the resulting JSON. 이 경우 콘텐츠의 가독성은 향상되지만 결과 문서의 크기가 증가합니다.This action will increase the size of the resulting document while making the contents more human readable.

  • 표준 JSON 내보내기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"}]}]
    
  • 꾸민 JSON 내보내기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"
        }
      ]
      }]
    

다음은 JSON 파일을 Azure Blob Storage로 내보내는 명령줄 샘플입니다.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

고급 구성Advanced configuration

고급 구성 화면에서 원하는 모든 오류가 기록된 로그 파일의 위치를 지정합니다.In the Advanced configuration screen, specify the location of the log file to which you would like any errors written. 이 페이지에는 다음 규칙이 적용됩니다.The following rules apply to this page:

  1. 파일 이름을 제공하지 않으면, 모든 오류는 결과 페이지에 반환됩니다.If a file name isn't provided, then all errors are returned on the Results page.

  2. 파일 이름에서 디렉터리가 없는 경우 파일은 현재 환경 디렉터리에 만들어지거나 덮어씁니다.If a file name is provided without a directory, then the file is created (or overwritten) in the current environment directory.

  3. 기존 파일을 선택하는 경우 파일을 덮어쓰며 추가 옵션은 없습니다.If you select an existing file, then the file is overwritten, there's no append option.

  4. 그런 다음 모든 메시지를 기록할지, 중요한 메시지를 기록할지 또는 오류 없음 메시지를 기록할지 선택합니다.Then, choose whether to log all, critical, or no error messages. 마지막으로, 화면 전송 메시지를 해당 진행률과 함께 업데이트할 빈도를 결정합니다.Finally, decide how frequently the on-screen transfer message is updated with its progress.

    고급 구성 화면의 스크린샷

가져오기 설정 확인 및 명령줄 보기Confirm import settings and view command line

  1. 원본 정보, 대상 정보 및 고급 구성을 지정한 후, 마이그레이션 요약을 검토하고, 결과 마이그레이션 명령을 확인/복사합니다.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. (명령 복사는 가져오기 작업을 자동화하는 데 유용합니다.)(Copying the command is useful to automate import operations.)

    요약 화면의 스크린샷.

    명령줄 미리 보기가 있는 요약 화면의 스크린샷.

  2. 원본 및 대상 옵션이 적절하면 가져오기 를 클릭합니다.Once you’re satisfied with your source and target options, click Import. 고급 구성에서 파일 이름을 지정하지 않은 경우 가져오기가 처리되는 동안 경과된 시간, 전송 횟수 및 실패 정보가 업데이트됩니다.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. 완료되면 결과를 내보낼 수 있습니다(예: 가져오기 오류를 처리하기 위해).Once complete, you can export the results (for example, to deal with any import failures).

    Azure Cosmos DB JSON 내보내기 옵션의 스크린샷.

  3. 모든 값을 다시 설정하거나 기존 설정을 유지하여 새 가져오기를 시작할 수도 있습니다.You may also start a new import by either resetting all values or keeping the existing settings. (예를 들어, 연결 문자열 정보, 원본 및 대상 선택 등을 유지하도록 선택할 수 있습니다.)(For example, you may choose to keep connection string information, source and target choice, and more.)

    새 가져오기 확인 대화 상자가 있는 Azure Cosmos DB JSON 내보내기 옵션의 스크린샷.

다음 단계Next steps

이 자습서에서는 다음 작업을 수행했습니다.In this tutorial, you've done the following tasks:

  • 데이터 마이그레이션 도구 설치Installed the Data Migration tool
  • 여러 데이터 원본에서 데이터 가져오기Imported data from different data sources
  • Azure Cosmos DB에서 JSON으로 내보내기Exported from Azure Cosmos DB to JSON

이제 다음 자습서로 진행하여 Azure Cosmos DB를 사용하여 데이터를 쿼리하는 방법을 알아볼 수 있습니다.You can now proceed to the next tutorial and learn how to query data using Azure Cosmos DB.