如何通过 Ruby 使用 Azure 表存储或 Azure Cosmos DB for Table

项目
04/08/2023

适用对象：表

提示

本文中的内容适用于 Azure 表存储和 Azure Cosmos DB for Table。 API for Table 是表存储的高级服务，可提供吞吐量优化表、全局分发和自动辅助索引。

本文介绍如何创建表、存储数据以及对数据执行 CRUD 操作。选择 Azure 表服务或 Azure Cosmos DB for Table。本文中所述的示例是采用 Ruby 编写的，并使用了用于 Ruby 的 Azure 存储表客户端库。涉及的场景包括创建表、删除表、插入实体以及查询表中的实体。

创建 Azure 服务帐户

可以通过 Azure 表存储或 Azure Cosmos DB 使用表。若要详细了解这两个服务中的表产品/服务之间的差异，请参阅 API for Table 概述。需要为所要使用的服务创建一个帐户。以下部分说明了如何创建 Azure 表存储和 Azure Cosmos DB 帐户，但你只需使用其中一个。

创建 Azure 存储帐户

创建 Azure 存储帐户的最简单方法是使用 Azure 门户。若要了解更多信息，请参阅创建存储帐户。

也可以使用 Azure PowerShell 或 Azure CLI 创建 Azure 存储帐户。

如果暂时不想创建存储帐户，也可以使用 Azure 存储模拟器在本地环境中运行和测试代码。有关详细信息，请参阅使用 Azure 存储模拟器进行开发和测试。

创建 Azure Cosmos DB 帐户

有关创建 Azure Cosmos DB for Table 帐户的说明，请参阅创建数据库帐户。

添加对 Azure 存储或 Azure Cosmos DB 的访问权限

要使用 Azure 存储或 Azure Cosmos DB，必须下载和使用 Ruby azure 包，其中包括一组便于与表 REST 服务进行通信的库。

使用 RubyGems 获取该程序包

使用命令行接口，例如 PowerShell (Windows)、Terminal (Mac) 或 Bash (Unix)。
在命令窗口中键入“gem install azure-storage-blob”以安装 gem 和依赖项。

导入包

使用常用的文本编辑器将以下内容添加到要在其中使用存储的 Ruby 文件的顶部：

require "azure/storage/table"

添加连接字符串

可以连接到 Azure 存储帐户，也可以连接到 Azure Cosmos DB for Table 帐户。根据所使用的帐户类型获取连接字符串。

添加 Azure 存储连接

Azure 存储模块读取环境变量 AZURE_STORAGE_ACCOUNT 和 AZURE_STORAGE_ACCESS_KEY 以获取连接到 Azure 存储器帐户所需的信息。如果未设置这些环境变量，则在使用 Azure::Storage::Table::TableService 之前必须通过以下代码指定帐户信息：

Azure.config.storage_account_name = "<your Azure Storage account>"
Azure.config.storage_access_key = "<your Azure Storage access key>"

从 Azure 门户中的经典或 Resource Manager 存储帐户中获取这些值：

登录到 Azure 门户。
导航到要使用的存储帐户。
在右侧的“设置”边栏选项卡中，单击“访问密钥”。
在出现的“访问密钥”边栏选项卡中，将看到访问密钥 1 和访问密钥 2。可以使用其中任意一个。
单击复制图标以将键复制到剪贴板。

添加 Azure Cosmos DB 连接

要连接到 Azure Cosmos DB，请从 Azure 门户中复制主连接字符串，并使用复制的连接字符串创建 Client 对象：创建 TableService 对象时，可以传递 Client 对象：

common_client = Azure::Storage::Common::Client.create(storage_account_name:'myaccount', storage_access_key:'mykey', storage_table_host:'mycosmosdb_endpoint')
table_client = Azure::Storage::Table::TableService.new(client: common_client)

创建表

使用 Azure::Storage::Table::TableService 对象可以对表和实体进行操作。要创建表，请使用 create_table() 方法。以下示例将创建表或输出存在的错误。

azure_table_service = Azure::Storage::Table::TableService.new
begin
    azure_table_service.create_table("testtable")
rescue
    puts $!
end

将实体添加到表

要添加实体，应首先创建一个定义了实体属性的哈希对象。请注意，必须为每个实体指定 PartitionKey 和 RowKey。这些值是实体的唯一标识符，并且查询它们比查询其他属性快很多。 Azure 存储使用 PartitionKey 将表的实体自动分发到多个存储节点。具有相同 PartitionKey 的实体存储在同一个节点上。 RowKey 是实体在其所属分区内的唯一 ID。

entity = { "content" => "test entity",
    :PartitionKey => "test-partition-key", :RowKey => "1" }
azure_table_service.insert_entity("testtable", entity)

更新实体

可使用多种方法来更新现有实体：

update_entity()： 通过替换现有实体来更新现有实体。
merge_entity()： 通过将新属性值合并到现有实体来更新现有实体。
insert_or_merge_entity()： 通过替换现有实体来更新现有实体。如果不存在实体，将插入一个新实体。
insert_or_replace_entity()： 通过将新属性值合并到现有实体来更新现有实体。如果不存在实体，将插入一个新实体。

以下示例演示使用 update_entity() 更新实体：

entity = { "content" => "test entity with updated content",
    :PartitionKey => "test-partition-key", :RowKey => "1" }
azure_table_service.update_entity("testtable", entity)

对于 update_entity() 和 merge_entity()，如果要更新的实体不存在，更新操作会失败。因此，如果想要存储某个实体而不考虑它是否已存在，则应改用 insert_or_replace_entity() 或 insert_or_merge_entity() 。

使用实体组

有时，有必要批量同时提交多项操作以确保通过服务器进行原子处理。要完成此操作，首先要创建一个批处理对象，然后对 TableService 使用 execute_batch() 方法。下面的示例演示在一个批次中提交 RowKey 为 2 和 3 的两个实体。请注意，这仅适用于具有相同 PartitionKey 的实体。

azure_table_service = Azure::TableService.new
batch = Azure::Storage::Table::Batch.new("testtable",
    "test-partition-key") do
    insert "2", { "content" => "new content 2" }
    insert "3", { "content" => "new content 3" }
end
results = azure_table_service.execute_batch(batch)

查询实体

要在表中查询实体，请通过传递表名称、PartitionKey 和 RowKey 来使用 get_entity() 方法。

result = azure_table_service.get_entity("testtable", "test-partition-key",
    "1")

查询实体集

要查询表中的实体集，请创建一个查询哈希对象并使用 query_entities() 方法。以下示例演示如何获取具有相同 PartitionKey 的所有实体：

query = { :filter => "PartitionKey eq 'test-partition-key'" }
result, token = azure_table_service.query_entities("testtable", query)

注意

如果结果集太大，一个查询无法全部返回，则返回一个继续标记，可以使用该标记检索后续页面。

查询一部分实体属性

对表的查询可以只检索实体中的少数几个属性。此方法称为“投影”，可减少带宽并提高查询性能，尤其适用于大型实体。请使用 select 子句并传递希望显示给客户端的属性的名称。

query = { :filter => "PartitionKey eq 'test-partition-key'",
    :select => ["content"] }
result, token = azure_table_service.query_entities("testtable", query)

删除实体

要删除实体，请使用 delete_entity() 方法。传入包含该实体的表的名称、实体的 PartitionKey 和 RowKey。

azure_table_service.delete_entity("testtable", "test-partition-key", "1")

删除表

要删除表，请使用 delete_table() 方法并传入要删除的表的名称。

azure_table_service.delete_table("testtable")

后续步骤

Azure 存储资源管理器是 Microsoft 免费提供的独立应用，适用于在 Windows、macOS 和 Linux 上以可视方式处理 Azure 存储数据。
Ruby 开发人员中心
适用于 Ruby 的 Azure 存储表客户端库

通过