Jak korzystać z usługi Azure Table Storage i interfejsu Table API usługi Azure Cosmos DB przy użyciu języka RubyHow to use Azure Table Storage and the Azure Cosmos DB Table API with Ruby

Porada

Zawartość tego artykułu dotyczy magazynu tabel Azure i interfejsu API tabeli w usłudze Azure Cosmos DB.The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. Interfejs API tabeli w usłudze Azure Cosmos DB jest ofertą Premium służącą do przechowywania tabel, która zapewnia tabele zoptymalizowane pod kątem przepływności, ich globalną dystrybucję i automatyczne indeksy pomocnicze.The Azure Cosmos DB Table API is a premium offering for table storage that offers throughput-optimized tables, global distribution, and automatic secondary indexes.

OmówienieOverview

W tym przewodniku przedstawiono sposób wykonywania typowych scenariuszy przy użyciu usługi Azure Table Storage oraz interfejsu Table API usługi Azure Cosmos DB.This guide shows you how to perform common scenarios using Azure Table service and the Azure Cosmos DB Table API. Przykłady są napisane w języku Ruby i korzystają z biblioteki klienta usługi Azure Table Storage dla języka Ruby.The samples are written in Ruby and use the Azure Storage Table Client Library for Ruby. Przedstawione scenariusze obejmują tworzenie i usuwanie tabel oraz wstawianie jednostek w tabeli i wykonywanie względem nich zapytań.The scenarios covered include creating and deleting a table, and inserting and querying entities in a table.

Tworzenie konta usługi AzureCreate an Azure service account

Do pracy z tabelami można używać usługi Azure Table Storage lub Azure Cosmos DB.You can work with tables using Azure Table storage or Azure Cosmos DB. Aby dowiedzieć się więcej o różnicach między usługami, zobacz Oferty tabel .To learn more about the differences between the services, see Table offerings. Aby móc korzystać z wybranej usługi, musisz w niej utworzyć konto.You'll need to create an account for the service you're going to use.

Tworzenie konta usługi Azure StorageCreate an Azure storage account

Najprostszym sposobem utworzenia konta magazynu platformy Azure jest użycie witryny Azure portal.The easiest way to create an Azure storage account is by using the Azure portal. Więcej informacji można znaleźć w temacie Tworzenie konta magazynu.To learn more, see Create a storage account.

Możesz utworzyć konto usługi Azure Storage przy użyciu programu Azure PowerShell lub interfejsu wiersza polecenia platformy Azure.You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

Jeśli nie chcesz teraz tworzyć konta magazynu, możesz także użyć emulatora usługi Azure Storage do uruchomienia i testowania kodu w środowisku lokalnym.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. Aby uzyskać więcej informacji, zobacz Używanie emulatora magazynu platformy Azure do tworzenia i testowania.For more information, see Use the Azure storage emulator for development and testing.

Tworzenie konta usługi Azure Cosmos DBCreate an Azure Cosmos DB account

Aby uzyskać instrukcje dotyczące tworzenia konta interfejsu API tabeli usługi Azure Cosmos DB, zobacz Tworzenie konta bazy danych.For instructions on creating an Azure Cosmos DB Table API account, see Create a database account.

Dodawanie dostępu do usługi Storage lub Azure Cosmos DBAdd access to Storage or Azure Cosmos DB

Aby użyć usługi Azure Storage lub Azure Cosmos DB, należy pobrać pakiet platformy Azure dla języka Ruby, który zawiera zestaw wygodnych bibliotek służących do komunikacji z usługami 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.

Używanie narzędzia RubyGems do pobierania pakietuUse RubyGems to obtain the package

  1. Użyj interfejsu wiersza polecenia, takiego jak PowerShell (system Windows), Terminal (system Mac) lub Bash (system Unix).Use a command-line interface such as PowerShell (Windows), Terminal (Mac), or Bash (Unix).
  2. Wpisz polecenie gem install azure-storage-table w oknie polecenia, aby zainstalować rozwiązanie gem i zależności.Type gem install azure-storage-table in the command window to install the gem and dependencies.

Importowanie pakietuImport the package

Użyj swojego ulubionego edytora tekstu, aby dodać następujący element na początku pliku w języku Ruby, w którym planujesz użyć usługi Storage: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"

Dodawanie połączenia z usługą Azure StorageAdd an Azure Storage connection

Moduł usługi Azure Storage odczytuje zmienne środowiskowe AZURE_STORAGE_ACCOUNT i AZURE_STORAGE_ACCESS_KEY, aby uzyskać informacje wymagane do nawiązania połączenia z kontem usługi Azure Storage.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. Jeśli te zmienne środowiskowe nie są ustawione, należy za pomocą następującego kodu określić informacje o koncie przed użyciem obiektu 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>"

Aby uzyskać te wartości z klasycznego konta magazynu lub konta magazynu menedżera zasobów w witrynie Azure Portal:To obtain these values from a classic or Resource Manager storage account in the Azure portal:

  1. Zaloguj się do witryny Azure Portal.Log in to the Azure portal.
  2. Przejdź do konta magazynu, którego chcesz użyć.Navigate to the Storage account you want to use.
  3. W bloku Ustawienia po prawej stronie kliknij pozycję Klucze dostępu.In the Settings blade on the right, click Access Keys.
  4. W wyświetlonym bloku Klucze dostępu widoczny będzie klucz dostępu 1 i klucz dostępu 2.In the Access keys blade that appears, you'll see the access key 1 and access key 2. Możesz użyć jednego z nich.You can use either of these.
  5. Kliknij ikonę kopiowania, aby skopiować klucz do schowka.Click the copy icon to copy the key to the clipboard.

Dodawanie połączenia z usługą Azure Cosmos DBAdd an Azure Cosmos DB connection

Aby nawiązać połączenie z usługą Azure Cosmos DB, skopiuj podstawowe parametry połączenia z witryny Azure Portal, a następnie utwórz obiekt Client za ich pomocą.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. Możesz przekazać obiekt Client podczas tworzenia obiektu 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)

Tworzenie tabeliCreate a table

Obiekt Azure::Storage::Table::TableService umożliwia pracę z tabelami i jednostkami.The Azure::Storage::Table::TableService object lets you work with tables and entities. Aby utworzyć tabelę, użyj metody create_table().To create a table, use the create_table() method. W poniższym przykładzie zostanie utworzona tabela lub wyświetlony błąd, jeśli taki wystąpi.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

Dodawanie jednostki do tabeliAdd an entity to a table

Aby dodać jednostkę, najpierw utwórz obiekt skrótu, który definiuje właściwości jednostki.To add an entity, first create a hash object that defines your entity properties. Należy pamiętać, że dla każdej jednostki konieczne jest ustawienie właściwości PartitionKey i RowKey.Note that for every entity you must specify a PartitionKey and RowKey. Są to unikatowe identyfikatory jednostek, będące wartościami, względem których można tworzyć zapytania znaczenie szybciej niż względem innych właściwości.These are the unique identifiers of your entities, and are values that can be queried much faster than your other properties. Usługa Azure Storage używa właściwości PartitionKey do automatycznego dystrybuowania jednostek tabeli w wielu węzłach magazynu.Azure Storage uses PartitionKey to automatically distribute the table's entities over many storage nodes. Obiekty z tą samą wartością właściwości PartitionKey są przechowywane w tym samym węźle.Entities with the same PartitionKey are stored on the same node. Właściwość RowKey to unikatowy identyfikator jednostki w ramach partycji, do której należy.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)

Aktualizowanie jednostkiUpdate an entity

Istnieje kilka metod aktualizowania istniejącej jednostki:There are multiple methods available to update an existing entity:

  • update_entity(): aktualizuje istniejącą jednostkę przez zastąpienie jej.update_entity(): Update an existing entity by replacing it.
  • merge_entity(): aktualizuje istniejącą jednostkę przez scalenie nowych wartości właściwości z istniejącą jednostką.merge_entity(): Updates an existing entity by merging new property values into the existing entity.
  • insert_or_merge_entity(): aktualizuje istniejącą jednostkę przez zastąpienie jej.insert_or_merge_entity(): Updates an existing entity by replacing it. Jeśli żadna jednostka nie istnieje, zostanie wstawiona nowa jednostka:If no entity exists, a new one will be inserted:
  • insert_or_replace_entity(): aktualizuje istniejącą jednostkę przez scalenie nowych wartości właściwości z istniejącą jednostką.insert_or_replace_entity(): Updates an existing entity by merging new property values into the existing entity. Jeśli żadna jednostka nie istnieje, zostanie wstawiona nowa jednostka.If no entity exists, a new one will be inserted.

W poniższym przykładzie przedstawiono aktualizowanie jednostki przy użyciu 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)

Jeśli podczas używania metod update_entity() i merge_entity() aktualizowana jednostka nie istnieje, operacja aktualizacji zakończy się niepowodzeniem.With update_entity() and merge_entity(), if the entity that you are updating doesn't exist then the update operation will fail. W związku z tym jeśli chcesz przechowywać jednostki niezależnie od tego, czy już istnieją, należy zamiast tego użyć metody insert_or_replace_entity() lub 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().

Praca z grupami jednostekWork with groups of entities

Czasami warto przesłać jednocześnie wiele operacji w partii, aby zapewnić niepodzielne przetwarzanie przez serwer.Sometimes it makes sense to submit multiple operations together in a batch to ensure atomic processing by the server. Aby to osiągnąć, należy najpierw utworzyć obiekt Batch, a następnie użyć metody execute_batch() względem obiektu TableService.To accomplish that, you first create a Batch object and then use the execute_batch() method on TableService. W poniższym przykładzie przedstawiono przesyłanie dwóch jednostek w partii z właściwością RowKey o wartościach 2 i 3.The following example demonstrates submitting two entities with RowKey 2 and 3 in a batch. Należy zauważyć, że działa to tylko dla jednostek o tej samej wartości właściwości 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)

Wykonywanie zapytania względem jednostkiQuery for an entity

Aby wykonać zapytanie względem jednostki w tabeli, użyj metody get_entity(), przekazując nazwę tabeli oraz właściwości PartitionKey i 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")

Wykonywanie zapytania względem zestawu jednostekQuery a set of entities

Aby wykonać zapytanie względem zestawu jednostek, utwórz obiekt skrótu zapytania, a następnie użyj metody query_entities().To query a set of entities in a table, create a query hash object and use the query_entities() method. W poniższym przykładzie przedstawiono pobieranie wszystkich jednostek o takiej samej wartości właściwości 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)

Uwaga

Jeśli zestaw wyników jest zbyt duży do zwrócenia w ramach pojedynczego zapytania, zwracany jest token kontynuacji, którego można użyć do pobrania kolejnych stron.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.

Tworzenie zapytania do podzbioru właściwości jednostkiQuery a subset of entity properties

Za pomocą zapytania wykonywanego względem tabeli można pobrać tylko kilka właściwości z jednostki.A query to a table can retrieve just a few properties from an entity. Ta technika, zwana „projekcją”, zmniejsza przepustowość i może poprawić wydajność zapytań, zwłaszcza w przypadku dużych jednostek.This technique, called "projection," reduces bandwidth and can improve query performance, especially for large entities. Użyj klauzuli SELECT i wprowadź nazwy właściwości, które chcesz przekazać 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)

Usuwanie jednostkiDelete an entity

Aby usunąć jednostkę, użyj metody delete_entity().To delete an entity, use the delete_entity() method. Przekaż nazwę tabeli zawierającą jednostkę oraz właściwości PartitionKey i RowKey jednostki.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")

Usuwanie tabeliDelete a table

Aby usunąć tabelę, użyj metody delete_table() i przekaż nazwę tabeli, którą chcesz usunąć.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")

Następne krokiNext steps