Jak používat službu Azure Table Storage a rozhraní Table API služby Azure Cosmos DB pomocí RubyHow to use Azure Table Storage and the Azure Cosmos DB Table API with Ruby

PLATÍ pro: rozhraní API pro tabulky

Tip

Obsah v tomto článku se vztahuje na službu Azure Table Storage a rozhraní Azure Cosmos DB Table API.The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. Rozhraní Azure Cosmos DB Table API je nabídka služby Table Storage úrovně Premium, která nabízí tabulky optimalizované pro zvýšení propustnosti, globální distribuci a automatické sekundární indexy.The Azure Cosmos DB Table API is a premium offering for table storage that offers throughput-optimized tables, global distribution, and automatic secondary indexes.

V tomto článku se dozvíte, jak vytvářet tabulky, ukládat data a provádět operace CRUD s daty.This article shows you how to create tables, store your data, and perform CRUD operations on the data. Vyberte buď Azure Table service, nebo rozhraní API pro tabulky Azure Cosmos DB.Choose either the Azure Table service or the Azure Cosmos DB Table API. Ukázky popsané v tomto článku jsou napsané v Ruby a používají knihovnu klienta Azure Storage Table pro Ruby.The samples described in this article are written in Ruby and uses the Azure Storage Table Client Library for Ruby. Zahrnuté scénáře zahrnují vytvoření tabulky, odstranění tabulky, vložení entit a dotazování entit z tabulky.The scenarios covered include create a table, delete a table, insert entities, and query entities from the table.

Vytvoření účtu služby AzureCreate an Azure service account

S tabulkami můžete pracovat pomocí služby Azure Table Storage nebo Azure Cosmos DB.You can work with tables using the Azure Table storage or the Azure Cosmos DB. Další informace o rozdílech mezi nabídkami tabulek v těchto dvou službách najdete v článku věnovaném nabídkám pro tabulky .To learn more about the differences between table offerings in these two services, see the Table offerings article. U služby, kterou budete používat, si budete muset vytvořit účet.You'll need to create an account for the service you're going to use. V následujících částech se dozvíte, jak vytvořit službu Azure Table Storage a účet Azure Cosmos DB, ale stačí použít jednu z nich.The following sections show how to create both Azure Table storage and the Azure Cosmos DB account, however you can just use one of them.

Vytvoření účtu služby Azure StorageCreate an Azure storage account

Nejjednodušší způsob, jak vytvořit účet úložiště Azure, je použít Azure Portal.The easiest way to create an Azure storage account is by using the Azure portal. Další informace najdete v tématu Vytvoření účtu úložiště.To learn more, see Create a storage account.

Účet úložiště Azure můžete vytvořit také pomocí Azure PowerShellu nebo Azure CLI.You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

Pokud nechcete v tomto okamžiku vytvořit účet úložiště, můžete také použít emulátor Azure Storage ke spuštění a otestování kódu v místním prostředí.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. Další informace najdete v tématu použití emulátoru Azure Storage pro vývoj a testování.For more information, see Use the Azure Storage Emulator for development and testing.

Vytvoření účtu služby Azure Cosmos DBCreate an Azure Cosmos DB account

Pokyny k vytvoření účtu Azure Cosmos DB rozhraní API pro tabulky najdete v tématu vytvoření databázového účtu.For instructions on creating an Azure Cosmos DB Table API account, see Create a database account.

Přidání přístupu do služby Azure Storage nebo Azure Cosmos DBAdd access to Azure storage or Azure Cosmos DB

Pokud chcete používat službu Azure Storage nebo Azure Cosmos DB, musíte stáhnout a použít balíček Azure pro Ruby, který obsahuje sadu knihoven usnadňujících práci a komunikujících se službami REST služby Table Storage.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.

Získání balíčku pomocí RubyGemsUse RubyGems to obtain the package

  1. Použijte rozhraní příkazového řádku, jako je PowerShell (Windows), Terminál (Mac) nebo Bash (Unix).Use a command-line interface such as PowerShell (Windows), Terminal (Mac), or Bash (Unix).
  2. Zadáním příkazu gem install azure-storage-table do příkazového okna nainstalujte gem a závislosti.Type gem install azure-storage-table in the command window to install the gem and dependencies.

Import balíčkuImport the package

Pomocí oblíbeného textového editoru přidejte následující řádek na začátek souboru Ruby, ve kterém chcete službu Storage používat: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"

Přidat připojovací řetězecAdd your connection string

Můžete se buď připojit k účtu služby Azure Storage nebo účtu Azure Cosmos DB rozhraní API pro tabulky.You can either connect to the Azure storage account or the Azure Cosmos DB Table API account. Získejte připojovací řetězec na základě typu účtu, který používáte.Get the connection string based on the type of account you are using.

Přidání připojení ke službě Azure StorageAdd an Azure Storage connection

Modul Azure Storage načte informace potřebné pro připojení k účtu služby Azure Storage z proměnných prostředí AZURE_STORAGE_ACCOUNT a AZURE_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. Pokud tyto proměnné prostředí nejsou nastavené, je potřeba zadat informace o účtu ještě před použitím objektu Azure::Storage::Table::TableService pomocí následujícího kódu: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>"

Získání těchto hodnot z klasického účtu úložiště nebo účtu úložiště Resource Manageru na webu Azure Portal:To obtain these values from a classic or Resource Manager storage account in the Azure portal:

  1. Přihlaste se k Azure Portal.Log in to the Azure portal.
  2. Přejděte do účtu služby Storage, který chcete použít.Navigate to the Storage account you want to use.
  3. V okně Nastavení na pravé straně klikněte na Přístupové klíče .In the Settings blade on the right, click Access Keys .
  4. V okně Přístupové klíče, které se zobrazí, uvidíte přístupový klíč 1 a přístupový klíč 2.In the Access keys blade that appears, you'll see the access key 1 and access key 2. Můžete použít libovolný z nich.You can use either of these.
  5. Kliknutím na ikonu kopírování zkopírujte klíč do schránky.Click the copy icon to copy the key to the clipboard.

Přidání připojení ke službě Azure Cosmos DBAdd an Azure Cosmos DB connection

Pokud se chcete připojit ke službě Azure Cosmos DB, zkopírujte z webu Azure Portal primární připojovací řetězec a s jeho použitím vytvořte objekt 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. Objekt Client můžete předat při vytváření objektu TableService :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)

Vytvoření tabulkyCreate a table

Objekt Azure::Storage::Table::TableService umožňuje pracovat s tabulkami a entitami.The Azure::Storage::Table::TableService object lets you work with tables and entities. Pokud chcete vytvořit tabulku, použijte metodu create_table() .To create a table, use the create_table() method. Následující příklad vytvoří tabulku nebo vypíše chybu, pokud tabulka již existuje.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

Přidání entity do tabulkyAdd an entity to a table

Pokud chcete přidat entitu, nejprve vytvořte objekt hash definující vlastnosti entity.To add an entity, first create a hash object that defines your entity properties. Nezapomeňte, že pro každou entitu musíte zadat PartitionKey a RowKey .Note that for every entity you must specify a PartitionKey and RowKey . Jedná se o jedinečné identifikátory entit a jsou to hodnoty, které je možné dotazovat mnohem rychleji než ostatní vlastnosti.These are the unique identifiers of your entities, and are values that can be queried much faster than your other properties. Azure Storage používá PartitionKey k automatické distribuci entit tabulky do mnoha uzlů úložiště.Azure Storage uses PartitionKey to automatically distribute the table's entities over many storage nodes. Entity se stejnou hodnotou PartitionKey se ukládají na stejném uzlu.Entities with the same PartitionKey are stored on the same node. RowKey je jedinečné ID entity v rámci oddílu, do kterého patří.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)

Aktualizace entityUpdate an entity

Existující entitu můžete aktualizovat několika metodami:There are multiple methods available to update an existing entity:

  • update_entity(): Aktualizuje existující entitu tím, že ji nahradí.update_entity(): Update an existing entity by replacing it.
  • merge_entity(): Aktualizuje existující entitu tím, že s ní sloučí nové hodnoty vlastností.merge_entity(): Updates an existing entity by merging new property values into the existing entity.
  • insert_or_merge_entity(): Aktualizuje existující entitu tím, že ji nahradí.insert_or_merge_entity(): Updates an existing entity by replacing it. Pokud žádná entita neexistuje, vloží se nová entita:If no entity exists, a new one will be inserted:
  • insert_or_replace_entity(): Aktualizuje existující entitu tím, že s ní sloučí nové hodnoty vlastností.insert_or_replace_entity(): Updates an existing entity by merging new property values into the existing entity. Pokud žádná entita neexistuje, vloží se nová entita.If no entity exists, a new one will be inserted.

Následující příklad ukazuje aktualizaci entity pomocí metody 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)

V případě metod update_entity() a merge_entity() platí, že pokud aktualizovaná entita neexistuje, operace aktualizace selže.With update_entity() and merge_entity() , if the entity that you are updating doesn't exist then the update operation will fail. Proto pokud chcete entitu uložit bez ohledu na to, jestli již existuje, měli byste místo toho použít metodu insert_or_replace_entity() nebo 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() .

Práce se skupinami entitWork with groups of entities

Někdy má smysl odeslat více operací společně v dávce, aby se zajistilo jejich atomické zpracování serverem.Sometimes it makes sense to submit multiple operations together in a batch to ensure atomic processing by the server. Uděláte to tak, že nejprve vytvoříte objekt Batch a pak použijete metodu execute_batch() pro objekt TableService .To accomplish that, you first create a Batch object and then use the execute_batch() method on TableService . Následující příklad ukazuje odeslání dvou entit s RowKey 2 a 3 v dávce.The following example demonstrates submitting two entities with RowKey 2 and 3 in a batch. Poznámka: Tento přístup funguje pouze pro entity se stejnou hodnotou 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)

Dotaz na entituQuery for an entity

Pokud chcete zadat dotaz na entitu v tabulce, použijte metodu get_entity() a předejte do ní název tabulky, PartitionKey a 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")

Dotaz na sadu entitQuery a set of entities

Pokud chcete zadat dotaz na sadu entit v tabulce, vytvořte objekt hash dotazu a použijte metodu query_entities() .To query a set of entities in a table, create a query hash object and use the query_entities() method. Následující příklad ukazuje získání všech entit se stejnou hodnotou 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)

Poznámka

Pokud je sada výsledků dotazu příliš velká na to, aby ji vrátil jeden dotaz, vrátí se token pro pokračování, pomocí kterého můžete načíst další stránky.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.

Dotaz na podmnožinu vlastností entityQuery a subset of entity properties

Dotaz na tabulku dokáže z entity načíst pouze několik vlastností.A query to a table can retrieve just a few properties from an entity. Tato technika, označovaná jako projekce, snižuje šířku pásma a může zlepšit výkon dotazů, zejména u velkých entit.This technique, called "projection," reduces bandwidth and can improve query performance, especially for large entities. Použijte klauzuli select a předejte názvy vlastností, které chcete přenést do klienta.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)

Odstranění entityDelete an entity

Pokud chcete odstranit entitu, použijte metodu delete_entity() .To delete an entity, use the delete_entity() method. Předejte do ní název tabulky, která entitu obsahuje, a PartitionKey a RowKey entity.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")

Odstranění tabulkyDelete a table

Pokud chcete odstranit tabulku, použijte metodu delete_table() a předejte do ní název tabulky, kterou chcete odstranit.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")

Další krokyNext steps