Ruby から Azure Table Storage と Azure Cosmos DB Table API を使用する方法How to use Azure Table Storage and the Azure Cosmos DB Table API with Ruby

ヒント

この記事の内容の適用対象は、Azure Table Storage および Azure Cosmos DB Table API です。The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. Azure Cosmos DB Table API は、スループット最適化テーブル、グローバル配布、自動セカンダリ インデックスを提供する Table Storage 用の Premium オファーです。The Azure Cosmos DB Table API is a premium offering for table storage that offers throughput-optimized tables, global distribution, and automatic secondary indexes.

概要Overview

このガイドでは、Azure Table service と Azure Cosmos DB Table API を使用する一般的なシナリオの実行方法を説明します。This guide shows you how to perform common scenarios using Azure Table service and the Azure Cosmos DB Table API. サンプルは Ruby で記述され、Azure Storage Table Client Library for Ruby を使用しています。The samples are written in Ruby and use the Azure Storage Table Client Library for Ruby. 紹介するシナリオには、テーブルの作成と削除の他に、テーブルへのエンティティの挿入とクエリの実行が含まれています。The scenarios covered include creating and deleting a table, and inserting and querying entities in a table.

Azure サービス アカウントを作成するCreate an Azure service account

Azure Table ストレージまたは Azure Cosmos DB を使用してテーブルを操作できます。You can work with tables using Azure Table storage or Azure Cosmos DB. サービスによる違いの詳細については、「Table のサービス」を参照してください。You can learn more about the differences between the services by reading Table offerings. 使用するサービスのアカウントを作成する必要があります。You'll need to create an account for the service you're going to use.

Azure のストレージ アカウントの作成Create an Azure storage account

最初の Azure ストレージ アカウントを作成する最も簡単な方法は、Azure Portal を利用することです。The easiest way to create your first Azure storage account is by using the Azure portal. 詳細については、「 ストレージ アカウントの作成」を参照してください。To learn more, see Create a storage account.

Azure PowerShell または Azure CLI を使って、Azure Storage アカウントを作成することもできます。You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

現時点でストレージ アカウントを作成しない場合は、Azure ストレージ エミュレーターを使用して、ローカル環境でコードの実行とテストを行うこともできます。If you prefer not to create a storage account at this time, you can also use the Azure storage emulator to run and test your code in a local environment. 詳細については、「 開発とテストのための Azure のストレージ エミュレーター使用」を参照してください。For more information, see Use the Azure Storage Emulator for Development and Testing.

Azure Cosmos DB アカウントを作成するCreate an Azure Cosmos DB account

Azure Cosmos DB Table API アカウントの作成手順については、Table API アカウントの作成に関するセクションを参照してください。For instructions on creating an Azure Cosmos DB Table API account, see Create a Table API account.

Storage または Azure Cosmos DB へのアクセスを追加するAdd access to Storage or Azure Cosmos DB

Azure Storage または Azure Cosmos DB を使用するには、Ruby Azure パッケージをダウンロードして使用する必要があります。このパッケージには、Table REST サービスと通信するための便利なライブラリのセットが含まれています。To use Azure Storage or Azure Cosmos DB, you must download and use the Ruby Azure package that includes a set of convenience libraries that communicate with the Table REST services.

RubyGems を使用してパッケージを取得するUse RubyGems to obtain the package

  1. PowerShell (Windows)、ターミナル (Mac)、Bash (Unix) などのコマンド ライン インターフェイスを使用します。Use a command-line interface such as PowerShell (Windows), Terminal (Mac), or Bash (Unix).
  2. コマンド ウィンドウに「gem install azure-storage-table」と入力して、gem と依存関係をインストールします。Type gem install azure-storage-table in the command window to install the gem and dependencies.

パッケージをインポートするImport the package

任意のテキスト エディターを使用して、Storage を使用する Ruby ファイルの先頭に次のコードを追加します。Use your favorite text editor, add the following to the top of the Ruby file where you intend to use Storage:

require "azure/storage/table"

Azure Storage 接続を追加するAdd an Azure Storage connection

Azure Storage モジュールは、Azure Storage アカウントに接続するために必要な情報として、環境変数 AZURE_STORAGE_ACCOUNTAZURE_STORAGE_ACCESS_KEY を読み取ります。The Azure Storage module reads the environment variables AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_ACCESS_KEY for information required to connect to your Azure Storage account. これらの環境変数が設定されていない場合は、Azure::Storage::Table::TableService を使用する前に、次のコードを使用してアカウント情報を指定する必要があります。If these environment variables are not set, you must specify the account information before using Azure::Storage::Table::TableService with the following code:

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

Azure ポータルでクラシックまたは Resource Manager ストレージ アカウントからこれらの値を取得するには:To obtain these values from a classic or Resource Manager storage account in the Azure portal:

  1. Azure Portal にログインします。Log in to the Azure portal.
  2. 使用するストレージ アカウントを表示します。Navigate to the Storage account you want to use.
  3. 右側の [設定] ブレードで、 [アクセス キー] をクリックします。In the Settings blade on the right, click Access Keys.
  4. 表示される [アクセス キー] ブレードに、アクセス キー 1 とアクセス キー 2 が表示されます。In the Access keys blade that appears, you'll see the access key 1 and access key 2. このいずれかを使用できます。You can use either of these.
  5. コピー アイコンをクリックしてキーをクリップボードにコピーします。Click the copy icon to copy the key to the clipboard.

Azure Cosmos DB の接続を追加するAdd an Azure Cosmos DB connection

Azure Cosmos DB に接続するには、Azure Portal からプライマリ接続文字列をコピーし、コピーした接続文字列を使って Client オブジェクトを作成します。To connect to Azure Cosmos DB, copy your primary connection string from the Azure portal, and create a Client object using your copied connection string. TableService オブジェクトの作成時に Client オブジェクトを渡すことができます。You can pass the Client object when you create a TableService object:

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)

テーブルを作成するCreate a table

Azure::Storage::Table::TableService オブジェクトを使用して、テーブルとエンティティを操作できます。The Azure::Storage::Table::TableService object lets you work with tables and entities. テーブルを作成するには、create_table() メソッドを使用します。To create a table, use the create_table() method. 次の例では、テーブルを作成し、既に存在している場合はエラーを出力します。The following example creates a table or prints the error if there is any.

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

エンティティをテーブルに追加するAdd an entity to a table

エンティティを追加するには、エンティティのプロパティを定義するハッシュ オブジェクトを最初に作成します。To add an entity, first create a hash object that defines your entity properties. すべてのエンティティについて、PartitionKeyRowKey を指定する必要があることに注意してください。Note that for every entity you must specify a PartitionKey and RowKey. これらはエンティティの一意の識別子であり、他のエンティティのプロパティよりはるかに高速に照会できる値です。These are the unique identifiers of your entities, and are values that can be queried much faster than your other properties. Azure Storage では、テーブルのエンティティを多数のストレージ ノードに自動的に配布するために PartitionKey を使用します。Azure Storage uses PartitionKey to automatically distribute the table's entities over many storage nodes. PartitionKey が同じエンティティは同じノードに格納されます。Entities with the same PartitionKey are stored on the same node. RowKey は、エンティティが属するパーティション内のエンティティの一意の ID です。The RowKey is the unique ID of the entity within the partition it belongs to.

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

エンティティを更新するUpdate an entity

既存のエンティティを更新するには、複数のメソッドがあります。There are multiple methods available to update an existing entity:

  • update_entity(): 既存のエンティティを置換することで更新します。update_entity(): Update an existing entity by replacing it.
  • merge_entity(): 新しいプロパティ値を既存のエンティティにマージすることで既存のエンティティを更新します。merge_entity(): Updates an existing entity by merging new property values into the existing entity.
  • insert_or_merge_entity(): 既存のエンティティを置換することで更新します。insert_or_merge_entity(): Updates an existing entity by replacing it. エンティティが存在しない場合は、新しいエンティティが挿入されます。If no entity exists, a new one will be inserted:
  • insert_or_replace_entity(): 新しいプロパティ値を既存のエンティティにマージすることで既存のエンティティを更新します。insert_or_replace_entity(): Updates an existing entity by merging new property values into the existing entity. エンティティが存在しない場合は、新しいエンティティが挿入されます。If no entity exists, a new one will be inserted.

次の例は、update_entity() を使用してエンティティを更新する方法を示しています。The following example demonstrates updating an entity using 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() では、更新されるエンティティが存在しない場合、更新操作は失敗します。With update_entity() and merge_entity(), if the entity that you are updating doesn't exist then the update operation will fail. したがって、既に存在しているかどうかに関係なくエンティティを格納するには、insert_or_replace_entity() または insert_or_merge_entity() を使用する必要があります。Therefore, if you want to store an entity regardless of whether it already exists, you should instead use insert_or_replace_entity() or insert_or_merge_entity().

エンティティのグループを操作するWork with groups of entities

状況によって、複数の操作をバッチとして送信し、サーバーによるアトミック処理を行うことが合理的である場合があります。Sometimes it makes sense to submit multiple operations together in a batch to ensure atomic processing by the server. このためには、まず Batch オブジェクトを作成し、次に TableServiceexecute_batch() メソッドを使用します。To accomplish that, you first create a Batch object and then use the execute_batch() method on TableService. 次の例では、RowKey が 2 および 3 である 2 つのエンティティをバッチで送信する方法を示します。The following example demonstrates submitting two entities with RowKey 2 and 3 in a batch. これは、同じ PartitionKey を持つエンティティでのみ機能することに注意してください。Notice that it only works for entities with the same 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)

エンティティを照会するQuery for an entity

テーブル内のエンティティを照会するには、get_entity() メソッドを使用して、テーブル名、PartitionKey、および RowKey を渡します。To query an entity in a table, use the get_entity() method, by passing the table name, PartitionKey and RowKey.

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

エンティティのセットを照会するQuery a set of entities

テーブル内のエンティティのセットを照会するには、クエリ ハッシュ オブジェクトを作成し、query_entities() メソッドを使用します。To query a set of entities in a table, create a query hash object and use the query_entities() method. 次の例では、同じ PartitionKeyを持つエンティティをすべて取得します。The following example demonstrates getting all the entities with the same PartitionKey:

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

注意

結果セットが大きすぎて単一のクエリで返すことができない場合は、継続トークンが返されます。この継続トークンを使用して、後続のページを取得できます。If the result set is too large for a single query to return, a continuation token is returned that you can use to retrieve subsequent pages.

エンティティ プロパティのサブセットを照会するQuery a subset of entity properties

テーブルに対するクエリでは、ごくわずかのプロパティだけをエンティティから取得できます。A query to a table can retrieve just a few properties from an entity. プロジェクションと呼ばれるこの方法では、帯域幅の使用が削減され、クエリのパフォーマンスが向上します。特に、大量のエンティティがある場合に役立ちます。This technique, called "projection," reduces bandwidth and can improve query performance, especially for large entities. select 句を使用して、クライアントに渡すプロパティの名前を指定します。Use the select clause and pass the names of the properties you would like to bring over to the client.

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

エンティティを削除するDelete an entity

エンティティを削除するには、delete_entity() メソッドを使用します。To delete an entity, use the delete_entity() method. 目的のエンティティを含んでいるテーブルの名前、PartitionKey、および エンティティの RowKey を渡します。Pass in the name of the table that contains the entity, the PartitionKey, and the RowKey of the entity.

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

テーブルを削除するDelete a table

テーブルを削除するには、delete_table() を使用して、削除するテーブルの名前を渡します。To delete a table, use the delete_table() method and pass in the name of the table you want to delete.

azure_table_service.delete_table("testtable")

次の手順Next steps