Uso de Azure Table Storage y Table API de Azure Cosmos DB con RubyHow to use Azure Table Storage and the Azure Cosmos DB Table API with Ruby

Sugerencia

El contenido de este artículo se aplica a Azure Table Storage y a Table API de Azure Cosmos DB.The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. La instancia de Table API de Azure Cosmos DB es una oferta premium que ofrece tablas con rendimiento optimizado, distribución global e índices secundarios automáticos.The Azure Cosmos DB Table API is a premium offering for table storage that offers throughput-optimized tables, global distribution, and automatic secondary indexes.

Información generalOverview

En esta guía se explica cómo realizar tareas comunes mediante Azure Table service y Table API de Azure Cosmos DB.This guide shows you how to perform common scenarios using Azure Table service and the Azure Cosmos DB Table API. Los ejemplos están escritos en Ruby y usan la biblioteca de cliente de Azure Storage Table para Ruby.The samples are written in Ruby and use the Azure Storage Table Client Library for Ruby. Entre los escenarios descritos se incluyen la creación y eliminación de una tabla y la inserción y consulta de entidades en una tabla.The scenarios covered include creating and deleting a table, and inserting and querying entities in a table.

Creación de una cuenta de servicio de AzureCreate an Azure service account

Puede trabajar con tablas mediante Azure Table Storage o Azure Cosmos DB.You can work with tables using Azure Table storage or Azure Cosmos DB. Para más información acerca de las diferencias entre los servicios, consulte Ofertas de Table.To learn more about the differences between the services, see Table offerings. Debe crear una cuenta para el servicio que se va a utilizar.You'll need to create an account for the service you're going to use.

Creación de una cuenta de Azure StorageCreate an Azure storage account

La manera más sencilla de crear una cuenta de almacenamiento de Azure es mediante Azure Portal.The easiest way to create an Azure storage account is by using the Azure portal. Para obtener más información, consulte Crear una cuenta de almacenamiento.To learn more, see Create a storage account.

También se puede crear una cuenta de Azure Storage mediante Azure PowerShell o la CLI de Azure.You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

Si no desea crear una cuenta de almacenamiento en este momento, también puede utilizar el emulador de Almacenamiento de Azure para ejecutar y probar el código en un entorno local.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. Para más información, consulte Uso del emulador de Azure Storage para desarrollo y pruebas.For more information, see Use the Azure storage emulator for development and testing.

Creación de una cuenta de Azure Cosmos DBCreate an Azure Cosmos DB account

Para obtener instrucciones sobre cómo crear una cuenta de Table API de Azure Cosmos DB, consulte Creación de una cuenta de base de datos.For instructions on creating an Azure Cosmos DB Table API account, see Create a database account.

Incorporación de acceso a Storage o Azure Cosmos DBAdd access to Storage or Azure Cosmos DB

Para usar Azure Storage o Azure Cosmos DB, debe descargar y usar el paquete de Azure para Ruby que incluye un conjunto de bibliotecas útiles que se comunican con los servicios REST de Table.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.

Uso de RubyGems para obtener el paqueteUse RubyGems to obtain the package

  1. Use una interfaz de línea de comandos como PowerShell (Windows), Terminal (Mac) o Bash (Unix).Use a command-line interface such as PowerShell (Windows), Terminal (Mac), or Bash (Unix).
  2. Escriba gem install azure-storage-table en la ventana de comandos para instalar la gema y las dependencias.Type gem install azure-storage-table in the command window to install the gem and dependencies.

Importación del paqueteImport the package

Con el editor de texto que prefiera, agregue lo siguiente al principio del archivo de Ruby en el que pretenda utilizar el almacenamiento: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"

Incorporación de una conexión de Azure StorageAdd an Azure Storage connection

El módulo de Azure Storage lee las variables de entorno AZURE_STORAGE_ACCOUNT y AZURE_STORAGE_ACCESS_KEY para la información necesaria para conectarse a su cuenta de 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. Si no se establecen estas variables de entorno, debe especificar la información de la cuenta antes de usar Azure::Storage::Table::TableService con el código siguiente: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>"

Para obtener estos valores desde una cuenta de almacenamiento de Azure Resource Manager o clásica en el Portal de Azure:To obtain these values from a classic or Resource Manager storage account in the Azure portal:

  1. Inicie sesión en Azure Portal.Log in to the Azure portal.
  2. Vaya a la cuenta de almacenamiento que desea usar.Navigate to the Storage account you want to use.
  3. En la hoja Configuración que se encuentra a la derecha, haga clic en Claves de acceso.In the Settings blade on the right, click Access Keys.
  4. En la hoja Claves de acceso que aparece, verá la clave de acceso 1 y 2.In the Access keys blade that appears, you'll see the access key 1 and access key 2. Puede usar cualquiera de estas.You can use either of these.
  5. Haga clic en el icono de copia para copiar la clave en el Portapapeles.Click the copy icon to copy the key to the clipboard.

Adición de una conexión de Azure Cosmos DBAdd an Azure Cosmos DB connection

Para conectarse a Azure Cosmos DB, copie la cadena de conexión principal de Azure Portal y cree un objeto Client con la cadena de conexión que ha copiado.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. Puede pasar el objeto Client cuando crea un objeto 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)

Creación de una tablaCreate a table

El objeto Azure::Storage::Table::TableService permite trabajar con tablas y entidades.The Azure::Storage::Table::TableService object lets you work with tables and entities. Para crear una tabla, use el método create_table() .To create a table, use the create_table() method. En el siguiente ejemplo se crea una tabla o se imprime el error, si hay alguno.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

Adición de una entidad a una tablaAdd an entity to a table

Para agregar una entidad, primero cree un objeto hash que defina las propiedades de la entidad.To add an entity, first create a hash object that defines your entity properties. Tenga en cuenta que para cada entidad debe especificar valores en PartitionKey y RowKey.Note that for every entity you must specify a PartitionKey and RowKey. Estos son los identificadores exclusivos de sus entidades y son valores que se pueden consultar más rápidamente que las demás propiedades.These are the unique identifiers of your entities, and are values that can be queried much faster than your other properties. Azure Storage usa PartitionKey para distribuir automáticamente las entidades de la tabla entre varios nodos de almacenamiento.Azure Storage uses PartitionKey to automatically distribute the table's entities over many storage nodes. Las entidades con la misma PartitionKey se almacenan en el mismo nodo.Entities with the same PartitionKey are stored on the same node. La RowKey es el identificador exclusivo de la entidad de la partición a la que pertenece.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)

Actualización de una entidadUpdate an entity

Hay varios métodos para actualizar una entidad existente:There are multiple methods available to update an existing entity:

  • update_entity(): actualiza una entidad existente al reemplazarla.update_entity(): Update an existing entity by replacing it.
  • merge_entity(): actualiza una entidad que ya existe combinando los valores de las nuevas propiedades con la entidad existente.merge_entity(): Updates an existing entity by merging new property values into the existing entity.
  • insert_or_merge_entity(): actualiza una entidad existente al reemplazarla.insert_or_merge_entity(): Updates an existing entity by replacing it. Si no hay entidades, se insertará una nueva.If no entity exists, a new one will be inserted:
  • insert_or_replace_entity(): actualiza una entidad que ya existe combinando los valores de las nuevas propiedades con la entidad existente.insert_or_replace_entity(): Updates an existing entity by merging new property values into the existing entity. Si no hay entidades, se insertará una nueva.If no entity exists, a new one will be inserted.

En el ejemplo siguiente se demuestra cómo actualizar una entidad usando 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() y merge_entity() , si la entidad que va a actualizar no existe, la operación de actualización generará un error.With update_entity() and merge_entity(), if the entity that you are updating doesn't exist then the update operation will fail. Por lo tanto, si desea almacenar una entidad independientemente de la que ya existe, debe usar 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().

Trabajo con grupos de entidadesWork with groups of entities

A veces resulta útil enviar varias operaciones juntas en un lote a fin de garantizar el procesamiento atómico por parte del servidor.Sometimes it makes sense to submit multiple operations together in a batch to ensure atomic processing by the server. Para ello, primero debe crear un objeto Batch y, a continuación, usar el método execute_batch() en TableService.To accomplish that, you first create a Batch object and then use the execute_batch() method on TableService. El siguiente ejemplo muestra el envío de dos entidades con RowKey 2 y 3 en un lote.The following example demonstrates submitting two entities with RowKey 2 and 3 in a batch. Tenga en cuenta que solo funciona para entidades con el mismo valor de 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)

Consulta de una entidadQuery for an entity

Para consultar una entidad de una tabla, use el método get_entity() , pasando el nombre de la tabla, PartitionKey y 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")

Consulta de un conjunto de entidadesQuery a set of entities

Para realizar una consulta de un conjunto de entidades de una tabla, cree un objeto hash de consulta y use el método query_entities() .To query a set of entities in a table, create a query hash object and use the query_entities() method. El siguiente ejemplo muestra la obtención de todas las entidades con el mismo valor de 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

Si el resultado establecido es demasiado largo para que lo devuelva una única consulta, se devuelve un token de continuación que puede usar para recuperar las páginas siguientes.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.

Consulta de un subconjunto de propiedades de las entidadesQuery a subset of entity properties

Una consulta de tabla puede recuperar solo algunas propiedades de una entidad.A query to a table can retrieve just a few properties from an entity. Esta técnica, denominada "proyección", reduce el ancho de banda y puede mejorar el rendimiento de las consultas, en especial en el caso de entidades de gran tamaño.This technique, called "projection," reduces bandwidth and can improve query performance, especially for large entities. Utilice la cláusula select y pase los nombres de las propiedades que quiera que lleguen al cliente.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)

Eliminación de una entidadDelete an entity

Para eliminar una entidad, use el método delete_entity() .To delete an entity, use the delete_entity() method. Pase el nombre de la tabla que contiene la entidad, la PartitionKey y la RowKey de la entidad.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")

Eliminar una tablaDelete a table

Para eliminar una tabla, use el método delete_table() y pase el nombre de la tabla que desea eliminar.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")

Pasos siguientesNext steps