Come usare l'archiviazione tabelle di Azure o l'API Tabelle di Azure Cosmos DB con RubyHow to use Azure Table Storage and the Azure Cosmos DB Table API with Ruby

Suggerimento

Il contenuto di questo articolo è applicabile al servizio di archiviazione tabelle di Azure e all'API Tabelle di Azure Cosmos DB.The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. L'API Tabelle di Azure Cosmos DB è un'offerta Premium per il servizio di archiviazione tabelle, che include tabelle con ottimizzazione per la velocità effettiva, distribuzione globale e indici secondari automatici.The Azure Cosmos DB Table API is a premium offering for table storage that offers throughput-optimized tables, global distribution, and automatic secondary indexes.

PanoramicaOverview

Questo documento illustra come eseguire scenari comuni usando il servizio archiviazione tabelle di Azure e l'API Tabelle di Azure Cosmos DB.This guide shows you how to perform common scenarios using Azure Table service and the Azure Cosmos DB Table API. Gli esempi sono scritti in Ruby e usano la libreria client delle tabelle di Archiviazione di Azure per Ruby.The samples are written in Ruby and use the Azure Storage Table Client Library for Ruby. Gli scenari presentati includono creazione ed eliminazione di una tabella, inserimento di entità ed esecuzione di query sulle entità in una tabella.The scenarios covered include creating and deleting a table, and inserting and querying entities in a table.

Creare un account del servizio di AzureCreate an Azure service account

È possibile usare tabelle con l'archiviazione tabelle di Azure o con Azure Cosmos DB.You can work with tables using Azure Table storage or Azure Cosmos DB. Per altre informazioni sulle differenze tra i servizi, vedere Offerte per tabelle.You can learn more about the differences between the services by reading Table offerings. Sarà necessario creare un account per il servizio che si intende usare.You'll need to create an account for the service you're going to use.

Creare un account di archiviazione di AzureCreate an Azure storage account

Il modo più semplice per creare il primo account di archiviazione di Azure consiste nell'usare il portale di Azure.The easiest way to create your first Azure storage account is by using the Azure portal. Per altre informazioni, vedere Creare un account di archiviazione.To learn more, see Create a storage account.

È possibile anche creare un account di archiviazione di Azure usando Azure PowerShell o l'interfaccia della riga di comando di Azure.You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

Se si preferisce non creare un account di archiviazione in questa fase, è anche possibile usare l'emulatore di archiviazione di Azure per eseguire e testare il codice in un ambiente locale.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. Per altre informazioni, vedere Usare l'emulatore di archiviazione di Azure per sviluppo e test.For more information, see Use the Azure Storage Emulator for Development and Testing.

Creare un account Azure Cosmos DBCreate an Azure Cosmos DB account

Per istruzioni per la creazione di un account per l'API di tabella di Azure Cosmos DB, vedere Creare un account per un'API di tabella.For instructions on creating an Azure Cosmos DB Table API account, see Create a Table API account.

Aggiungere l'accesso ad Archiviazione o ad Azure Cosmos DBAdd access to Storage or Azure Cosmos DB

Per usare Archiviazione di Azure o Azure Cosmos DB, è necessario scaricare e usare il pacchetto di Azure per Ruby, che comprende un set di pratiche librerie che comunicano con i servizi REST per le tabelle.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.

Utilizzare RubyGems per ottenere il pacchettoUse RubyGems to obtain the package

  1. Usare un'interfaccia della riga di comando, ad esempio PowerShell (Windows), Terminal (Mac) o Bash (Unix).Use a command-line interface such as PowerShell (Windows), Terminal (Mac), or Bash (Unix).
  2. Digitare gem install azure-storage-table nella finestra di comando per installare la gemma e le dipendenze.Type gem install azure-storage-table in the command window to install the gem and dependencies.

Importare il pacchettoImport the package

Usando l'editor di testo preferito aggiungere quanto segue alla parte superiore del file Ruby dove si intende usare l'archiviazione: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"

Aggiungere una connessione ad Archiviazione di AzureAdd an Azure Storage connection

I modulo di Archiviazione di Azure legge le variabili di ambiente AZURE_STORAGE_ACCOUNT e AZURE_STORAGE_ACCESS_KEY per ottenere le informazioni necessarie per la connessione all'account di archiviazione di Azure.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. Se queste variabili di ambiente non sono impostate, è necessario specificare le informazioni relative all'account prima di usare Azure::Storage::Table::TableService con il codice seguente: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>"

Per ottenere questi valori da un account di archiviazione classico o di Resource Manager nel portale di Azure:To obtain these values from a classic or Resource Manager storage account in the Azure portal:

  1. Accedere al Portale di Azure.Log in to the Azure portal.
  2. Passare all'account di archiviazione che si vuole usare.Navigate to the Storage account you want to use.
  3. Nel pannello Impostazioni a destra fare clic su Chiavi di accesso.In the Settings blade on the right, click Access Keys.
  4. Nel pannello Chiavi di accesso visualizzato notare la chiave di accesso 1 e la chiave di accesso 2.In the Access keys blade that appears, you'll see the access key 1 and access key 2. È possibile usare una di queste indifferentemente.You can use either of these.
  5. Fare clic sull'icona Copia per copiare la chiave negli Appunti.Click the copy icon to copy the key to the clipboard.

Aggiungere una connessione ad Azure Cosmos DBAdd an Azure Cosmos DB connection

Per connettersi ad Azure Cosmos DB, copiare la stringa di connessione primaria dal portale di Azure e creare un oggetto Client usando la stringa di connessione copiata.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. È possibile passare l'oggetto Client quando si crea un oggetto 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)

Creare una tabellaCreate a table

L'oggetto Azure::Storage::Table::TableService consente di usare tabelle ed entità.The Azure::Storage::Table::TableService object lets you work with tables and entities. Per creare una tabella, usare il metodo create_table().To create a table, use the create_table() method. Nell'esempio seguente viene creata una tabella o stampato l'eventuale errore.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

Aggiungere un'entità a una tabellaAdd an entity to a table

Per aggiungere un'entità, creare innanzitutto un oggetto hash che definisca le proprietà dell'entità.To add an entity, first create a hash object that defines your entity properties. Si noti che per ogni entità è necessario specificare un oggetto PartitionKey e un oggetto RowKey.Note that for every entity you must specify a PartitionKey and RowKey. Si tratta di identificatori univoci dell'entità e sono valori che possono essere interrogati molto più velocemente di altre proprietà.These are the unique identifiers of your entities, and are values that can be queried much faster than your other properties. Archiviazione Azure utilizza PartitionKey per distribuire automaticamente le entità della tabella su molti nodi di archiviazione.Azure Storage uses PartitionKey to automatically distribute the table's entities over many storage nodes. Le entità con lo stesso oggetto PartitionKey vengono archiviate nello stesso nodo.Entities with the same PartitionKey are stored on the same node. RowKey è l'ID univoco dell'entità all'interno della partizione cui appartiene.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)

Aggiornare un'entitàUpdate an entity

Esistono vari metodi per aggiornare un'entità esistente:There are multiple methods available to update an existing entity:

  • update_entity(): aggiorna un'entità esistente sostituendola.update_entity(): Update an existing entity by replacing it.
  • merge_entity(): aggiorna un'entità esistente unendovi nuovi valori delle proprietà.merge_entity(): Updates an existing entity by merging new property values into the existing entity.
  • insert_or_merge_entity(): aggiorna un'entità esistente sostituendola.insert_or_merge_entity(): Updates an existing entity by replacing it. Se non esiste alcuna entità, ne verrà inserita una nuova:If no entity exists, a new one will be inserted:
  • insert_or_replace_entity(): aggiorna un'entità esistente unendovi nuovi valori delle proprietà.insert_or_replace_entity(): Updates an existing entity by merging new property values into the existing entity. Se non esiste alcuna entità, ne verrà inserita una nuova.If no entity exists, a new one will be inserted.

L'esempio seguente illustra l'aggiornamento di un'entità mediante 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)

Con update_entity() e merge_entity(), se l'entità che si sta aggiornando non esiste, l'operazione di aggiornamento ha esito negativo.With update_entity() and merge_entity(), if the entity that you are updating doesn't exist then the update operation will fail. Se pertanto si vuole archiviare un'entità indipendentemente dal fatto che esista o meno, è necessario usare insert_or_replace_entity() o 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().

Usare i gruppi di entitàWork with groups of entities

È talvolta consigliabile inviare più operazioni in un batch per garantire l'elaborazione atomica da parte del server.Sometimes it makes sense to submit multiple operations together in a batch to ensure atomic processing by the server. A tale scopo, è necessario prima creare un oggetto Batch e quindi usare il metodo execute_batch() su TableService.To accomplish that, you first create a Batch object and then use the execute_batch() method on TableService. Nell'esempio seguente viene dimostrato l'invio di due entità con RowKey 2 e 3 in un batch:The following example demonstrates submitting two entities with RowKey 2 and 3 in a batch. Si noti che funziona solo per le entità con lo stesso oggetto 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)

Eseguire una query su un'entitàQuery for an entity

Per eseguire una query su un'entità in una tabella, usare il metodo get_entity() passando il nome della tabella e i parametri PartitionKey e 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")

Eseguire query su un set di entitàQuery a set of entities

Per eseguire query su un set di entità in una tabella, creare un oggetto hash di query e usare il metodo query_entities().To query a set of entities in a table, create a query hash object and use the query_entities() method. Nell'esempio seguente viene dimostrato l'invio di tutte le entità con lo stesso oggetto 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)

Nota

Se il set di risultati è troppo grande per essere restituito da un'unica query, viene restituito un token di continuazione per recuperare le pagine successive.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.

Eseguire query su un subset di proprietà di entitàQuery a subset of entity properties

Mediante una query su una tabella è possibile recuperare solo alcune proprietà da un'entità.A query to a table can retrieve just a few properties from an entity. Questa tecnica, denominata proiezione, consente di ridurre la larghezza di banda e di migliorare le prestazioni della query, soprattutto per le entità di grandi dimensioni.This technique, called "projection," reduces bandwidth and can improve query performance, especially for large entities. Utilizzare la clausola select e passare i nomi delle proprietà da inoltrare al client.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)

Eliminare un'entitàDelete an entity

Per eliminare un'entità, usare il metodo delete_entity().To delete an entity, use the delete_entity() method. Passare il nome della tabella che contiene l'entità e i parametri PartitionKey e RowKey dell'entità.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")

Eliminare una tabellaDelete a table

Per eliminare una tabella, usare il metodo delete_table() e passare il nome della tabella che si vuole eliminare.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")

Passaggi successiviNext steps