将数据迁移到 Azure Cosmos DB 表 API 帐户Migrate your data to Azure Cosmos DB Table API account

本教程说明如何导入要在 Azure Cosmos DB 表 API 中使用的数据。This tutorial provides instructions on importing data for use with the Azure Cosmos DB Table API. 如果已将数据存储在 Azure 表存储中,可以使用数据迁移工具或 AzCopy 将数据导入 Azure Cosmos DB 表 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(预览版)迁移到表 APIMigrating 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 门户中增加吞吐量的详细信息,请参阅 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 门户预先创建所有表。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 表存储数据导入到表 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) 目不支持表 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.exeRun 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. 指定应针对以下错误显示详细错误信息:None、Critical、AllSpecifies 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 表存储或表 API 预览版定义为迁移源时,请使用以下源选项。Use the following source options when defining Azure Table Storage or Table API preview as the source of the migration.

  • /s:AzureTable: 从 Azure 表存储读取数据/s:AzureTable: Reads data from Azure Table storage
  • /s.ConnectionString: 表终结点的连接字符串。/s.ConnectionString: Connection string for the table endpoint. 这可从 Azure 门户中检索This can be retrieved from the Azure portal
  • /s.LocationMode: 可选,默认值为 PrimaryOnly。/s.LocationMode: Optional, default is PrimaryOnly. 指定连接到 Azure 表存储时要使用的位置模式:PrimaryOnly、PrimaryThenSecondary、SecondaryOnly、SecondaryThenPrimarySpecifies which location mode to use when connecting to Azure Table storage: PrimaryOnly, PrimaryThenSecondary, SecondaryOnly, SecondaryThenPrimary
  • /s.Table: Azure 表的名称/s.Table: Name of the Azure Table
  • /s.InternalFields: 设置为 All 以进行表迁移,因为导入需要 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 表存储进行导入时,若要检索源连接字符串,请打开 Azure 门户并单击“存储帐户” > “帐户” > “访问密钥”,然后使用复制按钮复制连接字符串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.

HBase 源选项的屏幕截图

在从 Azure 表存储进行导入时,若要检索源连接字符串,请打开 Azure 门户并单击“存储帐户” > “帐户” > “访问密钥”,然后使用复制按钮复制连接字符串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 表存储命令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 表/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 表存储Sample command: Source is Azure Table storage

下面的命令行示例展示了如何从 Azure 表存储导入到表 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.chinacloudapi.cn /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.cosmos.azure.cn:443 /t.TableName:<Table name> /t.Overwrite

示例命令:源是 Azure Cosmos DB 表 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.cn; /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.cosmos.azure.cn:443 /t.TableName:<Table name> /t.Overwrite

使用 AzCopy 迁移数据Migrate data by using AzCopy

使用 AzCopy 命令行实用工具是将数据从 Azure 表存储迁移到 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,首先需要根据从表存储导出数据中所述导出数据,然后根据 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,而不是 core。Note that the /Dest value uses cosmosdb, not core.

示例导入命令:Example import command:

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

从表 API(预览版)迁移到表 APIMigrate 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. 因此,建议不要尝试将预览版 SDK 客户端与 GA 表 API 帐户混合使用,反之亦然。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(预览版)迁移到表 APIMigrate 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.