Azure Cosmos DB Table API 계정으로 데이터 마이그레이션Migrate your data to Azure Cosmos DB Table API account

적용 대상: Table API

이 자습서에서는 Azure Cosmos DB 테이블 API로 사용할 데이터 가져오기에 대한 지침을 제공합니다.This tutorial provides instructions on importing data for use with the Azure Cosmos DB Table API. Azure Table Storage에 저장된 데이터가 있는 경우 데이터 마이그레이션 도구 또는 AzCopy를 사용하여 데이터를 Azure Cosmos DB Table API로 가져올 수 있습니다.If you have data stored in Azure Table storage, you can use either the Data Migration Tool or AzCopy to import your data to Azure Cosmos DB Table API. 데이터가 Azure Cosmos DB 테이블 API(미리 보기) 계정에 저장된 경우 데이터 마이그레이션 도구를 사용하여 데이터를 마이그레이션해야 합니다.If you have data stored in an Azure Cosmos DB Table API (preview) account, you must use the Data Migration tool to migrate your data.

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

  • 데이터 마이그레이션 도구를 사용하여 데이터 가져오기Importing data with the Data Migration tool
  • AzCopy를 사용하여 데이터 가져오기Importing data with AzCopy
  • 테이블 API(미리 보기)에서 테이블 API로 마이그레이션Migrating from Table API (preview) to Table API

필수 구성 요소Prerequisites

  • 처리량 증가: 데이터 마이그레이션 기간은 개별 컨테이너 또는 컨테이너 세트에 대해 설정한 처리량에 따라 달라집니다.Increase throughput: The duration of your data migration depends on the amount of throughput you set up for an individual container or a set of containers. 대량 데이터 마이그레이션의 경우 처리량을 늘려야 합니다.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 tables from the Azure portal. 데이터베이스 수준 처리량이 있는 Azure Cosmos DB 계정으로 마이그레이션하는 경우에는 Azure Cosmos DB 테이블을 만들 때 파티션 키를 제공해야 합니다.If you are migrating to an Azure Cosmos DB account that has database level throughput, make sure to provide a partition key when creating the Azure Cosmos DB tables.

데이터 마이그레이션 도구Data Migration tool

명령줄 Azure Cosmos DB 데이터 마이그레이션 도구(dt.exe)를 사용하여 기존의 Azure Table Storage 데이터를 테이블 API GA 계정으로 가져오거나 테이블 API(미리 보기) 계정에서 테이블 API GA 계정으로 데이터를 마이그레이션할 수 있습니다.The command-line Azure Cosmos DB Data Migration tool (dt.exe) can be used to import your existing Azure Table storage data to a Table API GA account, or migrate data from a Table API (preview) account into a Table API GA account. 다른 원본은 현재 지원되지 않습니다.Other sources are not currently supported. UI 기반 데이터 마이그레이션 도구(dtui.exe)는 현재 Table API 계정에 대해 지원되지 않습니다.The UI based Data Migration tool (dtui.exe) is not currently supported for Table API accounts.

테이블 데이터 마이그레이션을 수행하려면 다음 작업을 완료하세요.To perform a migration of table data, complete the following tasks:

  1. 마이그레이션 도구를 GitHub에서 다운로드합니다.Download the migration tool from GitHub.

  2. 시나리오에 맞는 명령줄 인수를 사용하여 dt.exe를 실행합니다.Run dt.exe using the command-line arguments for your scenario. dt.exe에서 사용하는 형식은 다음과 같습니다.dt.exe takes a command in the following format:

     dt.exe [/<option>:<value>] /s:<source-name> [/s.<source-option>:<value>] /t:<target-name> [/t.<target-option>:<value>] 
    

이 명령에 지원되는 옵션은 다음과 같습니다.The supported options for this command are:

  • /ErrorLog: (선택 사항)/ErrorLog: Optional. 데이터 전송 실패를 리디렉션하는 CSV 파일 이름Name of the CSV file to redirect data transfer failures
  • /OverwriteErrorLog: (선택 사항)/OverwriteErrorLog: Optional. 오류 로그 파일 덮어쓰기Overwrite error log file
  • /ProgressUpdateInterval: 선택 사항입니다. 기본값은 00:00:01입니다./ProgressUpdateInterval: Optional, default is 00:00:01. 화면 데이터 전송 진행률을 새로 고치는 시간 간격Time interval to refresh on-screen data transfer progress
  • /ErrorDetails: 선택 사항입니다. 기본값은 None입니다./ErrorDetails: Optional, default is None. 다음 오류에 대한 자세한 오류 정보를 표시하도록 지정합니다. 없음, 중요, 모두Specifies that detailed error information should be displayed for the following errors: None, Critical, All
  • /EnableCosmosTableLog: (선택 사항)/EnableCosmosTableLog: Optional. 로그를 cosmos 테이블 계정으로 보냅니다.Direct the log to a cosmos table account. 설정하는 경우 /CosmosTableLogConnectionString도 제공되지 않는 한 이 기본값은 대상 계정 연결 문자열입니다.If set, this defaults to destination account connection string unless /CosmosTableLogConnectionString is also provided. 이는 DT의 여러 인스턴스가 동시에 실행되는 경우에 유용합니다.This is useful if multiple instances of DT are being run simultaneously.
  • /CosmosTableLogConnectionString: (선택 사항)/CosmosTableLogConnectionString: Optional. 로그를 원격 cosmos 테이블 계정으로 보내기 위한 ConnectionString입니다.ConnectionString to direct the log to a remote cosmos table account.

명령줄 원본 설정Command-line source settings

Azure Table Storage 또는 테이블 API 미리 보기를 마이그레이션 원본으로 정의할 때는 다음 원본 옵션을 사용하세요.Use the following source options when defining Azure Table Storage or Table API preview as the source of the migration.

  • /s:AzureTable: Azure Table 스토리지에서 데이터 읽기/s:AzureTable: Reads data from Azure Table storage
  • /s.ConnectionString: 테이블 엔드포인트의 연결 문자열입니다./s.ConnectionString: Connection string for the table endpoint. 이는 Azure Portal에서 검색할 수 있습니다.This can be retrieved from the Azure portal
  • /s.LocationMode: 선택 사항입니다. 기본값은 PrimaryOnly입니다./s.LocationMode: Optional, default is PrimaryOnly. Azure Table 스토리지에 연결할 때 사용할 위치 모드를 지정합니다. PrimaryOnly, PrimaryThenSecondary, SecondaryOnly, SecondaryThenPrimarySpecifies which location mode to use when connecting to Azure Table storage: PrimaryOnly, PrimaryThenSecondary, SecondaryOnly, SecondaryThenPrimary
  • /s.Table: Azure Table의 이름/s.Table: Name of the Azure Table
  • /s.InternalFields: RowKey 및 PartitionKey가 가져오기에 필요하므로 테이블 마이그레이션의 경우 모두로 설정합니다./s.InternalFields: Set to All for table migration as RowKey and PartitionKey are required for import.
  • /s.Filter: (선택 사항)/s.Filter: Optional. 적용할 필터 문자열Filter string to apply
  • /s.Projection: (선택 사항)/s.Projection: Optional. 선택할 열 목록List of columns to select

Azure Table Storage에서 가져올 때 원본 연결 문자열을 검색하려면 Azure Portal을 열고 스토리지 계정 > 계정 > 액세스 키 를 클릭한 후 복사 단추를 사용하여 연결 문자열 을 복사합니다.To retrieve the source connection string when importing from Azure Table storage, open the Azure portal and click Storage accounts > Account > Access keys , and then use the copy button to copy the Connection string.

스토리지 계정 > 계정 > 액세스 키 옵션을 보여주고 복사 단추를 강조 표시하는 스크린샷.

Azure Cosmos DB 테이블 API(미리 보기) 계정에서 가져올 때 원본 연결 문자열을 검색하려면 Azure Portal을 열고 Azure Cosmos DB > 계정 > 연결 문자열 을 클릭하고 복사 단추를 사용하여 연결 문자열 을 복사합니다.To retrieve the source connection string when importing from an Azure Cosmos DB Table API (preview) account, open the Azure portal, click Azure Cosmos DB > Account > Connection String and use the copy button to copy the Connection String.

HBase 원본 옵션의 스크린샷

Azure Table Storage 명령 예제Sample Azure Table Storage command

Azure Cosmos DB 테이블 API(미리 보기) 명령 예제Sample Azure Cosmos DB Table API (preview) command

명령줄 대상 설정Command-line target settings

Azure Cosmos DB 테이블 API를 마이그레이션 대상으로 정의할 때는 다음 대상 옵션을 사용하세요.Use the following target options when defining Azure Cosmos DB Table API as the target of the migration.

  • /t:TableAPIBulk: 일괄 처리로 데이터를 Azure CosmosDB Table에 업로드/t:TableAPIBulk: Uploads data into Azure CosmosDB Table in batches
  • /t.ConnectionString: 테이블 엔드포인트의 연결 문자열/t.ConnectionString: Connection string for the table endpoint
  • /t.TableName: 쓸 테이블의 열 이름 지정/t.TableName: Specifies the name of the table to write to
  • /t.Overwrite: 선택 사항입니다. 기본값은 false입니다./t.Overwrite: Optional, default is false. 기존 값을 덮어쓸지 여부를 지정Specifies if existing values should be overwritten
  • /t.MaxInputBufferSize: 선택 사항입니다. 기본값은 1GB입니다./t.MaxInputBufferSize: Optional, default is 1GB. 싱크로 데이터를 플러시하기 전에 버퍼에 입력할 바이트의 대략적인 추정치Approximate estimate of input bytes to buffer before flushing data to sink
  • /t.Throughput: 선택 사항입니다. 지정되지 않은 경우 서비스 기본값입니다./t.Throughput: Optional, service defaults if not specified. 테이블에 구성할 처리량 지정Specifies throughput to configure for table
  • /t.MaxBatchSize: 선택 사항입니다. 기본값은 2MB입니다./t.MaxBatchSize: Optional, default is 2MB. 일괄 처리 크기(바이트) 지정Specify the batch size in bytes

명령 샘플: 원본이 Azure Table 스토리지인 경우Sample command: Source is Azure Table storage

Azure Table Storage에서 테이블 API로 가져오는 방법을 보여주는 명령줄 예제는 다음과 같습니다.Here is a command-line sample showing how to import from Azure Table storage to Table API:

dt /s:AzureTable /s.ConnectionString:DefaultEndpointsProtocol=https;AccountName=<Azure Table storage account name>;AccountKey=<Account Key>;EndpointSuffix=core.windows.net /s.Table:<Table name> /t:TableAPIBulk /t.ConnectionString:DefaultEndpointsProtocol=https;AccountName=<Azure Cosmos DB account name>;AccountKey=<Azure Cosmos DB account key>;TableEndpoint=https://<Account name>.table.cosmosdb.azure.com:443 /t.TableName:<Table name> /t.Overwrite

명령 샘플: 원본이 Azure Cosmos DB Table API(미리 보기)인 경우Sample command: Source is Azure Cosmos DB Table API (preview)

테이블 API 미리 보기에서 테이블 API GA로 가져오는 명령줄 예제는 다음과 같습니다.Here is a command-line sample to import from Table API preview to Table API GA:

dt /s:AzureTable /s.ConnectionString:DefaultEndpointsProtocol=https;AccountName=<Table API preview account name>;AccountKey=<Table API preview account key>;TableEndpoint=https://<Account Name>.documents.azure.com; /s.Table:<Table name> /t:TableAPIBulk /t.ConnectionString:DefaultEndpointsProtocol=https;AccountName=<Azure Cosmos DB account name>;AccountKey=<Azure Cosmos DB account key>;TableEndpoint=https://<Account name>.table.cosmosdb.azure.com:443 /t.TableName:<Table name> /t.Overwrite

AzCopy를 사용하여 데이터 마이그레이션Migrate data by using AzCopy

AzCopy 명령줄 유틸리티를 사용하는 것은 Azure Table Storage에서 Azure Cosmos DB 테이블 API로 데이터를 마이그레이션하는 다른 옵션입니다.Using the AzCopy command-line utility is the other option for migrating data from Azure Table storage to the Azure Cosmos DB Table API. AzCopy를 사용하려면 먼저 Table Storage에서 데이터 내보내기에 설명된 대로 데이터를 내보낸 다음 Azure Cosmos DB 테이블 API에 설명된 대로 Azure Cosmos DB로 데이터를 가져옵니다.To use AzCopy, you first export your data as described in Export data from Table storage, then import the data to Azure Cosmos DB as described in Azure Cosmos DB Table API.

Azure Cosmos DB에서 가져오기를 수행할 때는 다음 예제를 참조하세요.When performing the import into Azure Cosmos DB, refer to the following sample. /Dest 값이 코어가 아닌 cosmosdb를 사용한다는 점을 참고하세요.Note that the /Dest value uses cosmosdb, not core.

가져오기 명령 예제:Example import command:

AzCopy /Source:C:\myfolder\ /Dest:https://myaccount.table.cosmosdb.windows.net/mytable1/ /DestKey:key /Manifest:"myaccount_mytable_20140103T112020.manifest" /EntityOperation:InsertOrReplace

테이블 API(미리 보기)에서 테이블 API로 마이그레이션Migrate from Table API (preview) to Table API

경고

일반 공급 테이블의 이점을 즉시 누리려면 이 섹션에 지정된 기존의 미리 보기를 마이그레이션하세요. 그렇지 않을 경우 앞으로 몇 주 동안 기존 미리 보기 고객을 위한 자동 마이그레이션이 수행됩니다. 하지만 자동으로 마이그레이션된 미리 보고 테이블은 새로 생성된 테이블과 달리 특정한 제한 사항이 있다는 사실을 참고하세요.If you want to immediately enjoy the benefits of the generally available tables then please migrate your existing preview tables as specified in this section, otherwise we will be performing auto-migrations for existing preview customers in the coming weeks, note however that auto-migrated preview tables will have certain restrictions to them that newly created tables will not.

테이블 API는 현재 일반 공급(GA)됩니다.The Table API is now generally available (GA). 클라우드에서 실행되는 코드와 클라이언트에서 실행되는 코드에서 미리 보기 버전과 GA 버전의 테이블에는 차이점이 있습니다.There are differences between the preview and GA versions of tables both in the code that runs in the cloud as well as in code that runs at the client. 따라서 GA 테이블 API 계정과 미리 보기 SDK 클라이언트를 혼합하거나 그 반대로 결합하려는 시도는 하지 않는 것이 좋습니다.Therefore it is not advised to try to mix a preview SDK client with a GA Table API account, and vice versa. 기존의 테이블을 프로덕션 환경에서 계속 사용하고자 하는 테이블 API 미리 보기 고객은 미리 보기에서 GA 환경으로 마이그레이션하거나 자동 마이그레이션을 기다려야 합니다.Table API preview customers who want to continue to use their existing tables but in a production environment need to migrate from the preview to the GA environment, or wait for auto-migration. 자동 마이그레이션을 기다리는 경우 마이그레이션된 테이블에 대한 제한 사항 알림이 수신될 것입니다.If you wait for auto-migration, you will be notified of the restrictions on the migrated tables. 마이그레이션 후에는 제한 사항 없이 기존 게정으로 새 테이블을 만들 수 있습니다(마이그레이션된 테이블에만 제한 사항이 있음).After migration, you will be able to create new tables on your existing account without restrictions (only migrated tables will have restrictions).

테이블 API(미리 보기)에서 일반 공급 테이블 API로 마이그레이션하려면:To migrate from Table API (preview) to the generally available Table API:

  1. 데이터베이스 계정 만들기에 설명된 대로새 Azure Cosmos DB 계정을 만들고 API 유형을 Azure 테이블로 설정합니다.Create a new Azure Cosmos DB account and set its API type to Azure Table as described in Create a database account.

  2. 테이블 API SDK의 GA 릴리스를 사용하도록 클라이언트를 변경합니다.Change clients to use a GA release of the Table API SDKs.

  3. 데이터 마이그레이션 도구를 사용하여 미리 보기 테이블의 클라이언트 데이터를 GA 테이블로 마이그레이션합니다.Migrate the client data from preview tables to GA tables by using the Data Migration tool. 이러한 용도로 데이터 마이그레이션 도구를 사용하는 방법에 대한 지침은 데이터 마이그레이션 도구에 설명되어 있습니다.Instructions on using the data migration tool for this purpose are described in Data Migration tool.

다음 단계Next steps

이 자습서에서는 다음 방법에 대해 알아보았습니다.In this tutorial you learned how to:

  • 데이터 마이그레이션 도구를 사용하여 데이터 가져오기Import data with the Data Migration tool
  • AzCopy를 사용하여 데이터 가져오기Import data with AzCopy
  • 테이블 API(미리 보기)에서 테이블 API로 마이그레이션Migrate from Table API (preview) to Table API

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