Como utilizar o Armazenamento de Tabelas do Azure e o Azure Cosmos DB para Tabela com Ruby

APLICA-SE A: Tabela

Este artigo mostra-lhe como criar tabelas, armazenar os seus dados e realizar operações CRUD nos dados. Selecione o serviço Tabela do Azure ou o Azure Cosmos DB para Tabela. Os exemplos descritos neste artigo são escritos no Ruby e utilizam a Biblioteca de Cliente da Tabela de Armazenamento do Azure para Ruby. Os cenários abrangidos incluem criar uma tabela, eliminar uma tabela, inserir entidades e consultar entidades da tabela.

Criar uma conta de serviço do Azure

Pode trabalhar com tabelas com o armazenamento de Tabelas do Azure ou o Azure Cosmos DB. Para saber mais sobre as diferenças entre as ofertas de tabela nestes dois serviços, veja a Descrição geral da API para Tabela. Tem de criar uma conta para o serviço que vai utilizar. As secções seguintes mostram como criar o armazenamento de Tabelas do Azure e a conta do Azure Cosmos DB. No entanto, pode utilizar apenas uma delas.

Table Storage do Azure

A forma mais fácil de criar uma conta de armazenamento do Azure é através da portal do Azure. Para saber mais, veja Criar uma conta de armazenamento.

Também pode criar uma conta de armazenamento do Azure com o Azure PowerShell ou a CLI do Azure.

Se preferir não criar uma conta de armazenamento neste momento, também pode utilizar o Emulador de Armazenamento do Azure para executar e testar o código num ambiente local. Para obter mais informações, veja Utilizar o Emulador de Armazenamento do Azure para desenvolvimento e teste.

Azure Cosmos DB para Tabela

Para obter instruções sobre como criar uma conta do Azure Cosmos DB para Tabela, veja Criar uma conta de base de dados.

Adicionar acesso ao armazenamento do Azure ou ao Azure Cosmos DB

Para utilizar o Armazenamento do Azure ou o Azure Cosmos DB, transfira e utilize o pacote do Ruby Azure. Este pacote inclui um conjunto de bibliotecas de conveniência que comunicam com os serviços REST da Tabela.

Utilizar RubyGems para obter o pacote

1. Utilize uma interface de linha de comandos, como PowerShell (Windows), Terminal (Mac), ou Bash (Unix).
2. Escreva gem install azure-storage-table na janela de comandos, para instalar o gem e as dependências.

Importar o pacote

Utilize o seu editor de texto favorito e adicione o seguinte à parte superior do ficheiro Ruby em que pretende utilizar o Armazenamento:

require "azure/storage/table"

Adicionar o seu cadeia de ligação

Pode ligar-se à conta de armazenamento do Azure ou à conta do Azure Cosmos DB for Table. Obtenha o cadeia de ligação com base no tipo de conta que está a utilizar.

Adicionar uma ligação ao Armazenamento do Azure

O módulo de Armazenamento do Azure lê as variáveis de ambiente AZURE_STORAGE_ACCOUNT e AZURE_STORAGE_ACCESS_KEY para obter as informações necessárias para ligar à sua conta de Armazenamento do Azure. Se estas variáveis de ambiente não estiverem definidas, tem de especificar as informações da conta antes de utilizar o Azure::Storage::Table::TableService com o seguinte código:

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

Para obter estes valores a partir de uma conta de armazenamento do Resource Manager ou clássica no portal do Azure:

1. Inicie sessão no portal do Azure.
2. Navegue para a Conta de armazenamento que pretende utilizar.
3. Na página Definições, selecione Chaves de Acesso.
4. Na página Chaves de acesso, observe a chave de acesso 1 e a chave de acesso 2. Pode utilizar qualquer uma destas chaves.
5. Selecione o ícone copiar para copiar a chave para a área de transferência.

Adicionar uma ligação do Azure Cosmos DB

Para ligar ao Azure Cosmos DB, copie a cadeia de ligação principal do portal do Azure e crie um objeto Cliente através da cadeia de ligação copiada. Pode passar o objeto Cliente ao criar um objeto TableService:

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)

Criar uma tabela

O objeto Azure::Storage::Table::TableService permite-lhe trabalhar com tabelas e entidades. Para criar uma tabela, utilize o método create_table(). O exemplo seguinte cria uma tabela ou imprime o erro se existir alguma.

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

Adicionar uma entidade a uma tabela

Para adicionar uma entidade, primeiro crie um objeto de hash que define as propriedades da sua entidade. Para cada entidade, tem de especificar partitionKey e RowKey. Estas entidades são os identificadores exclusivos das suas entidades e são valores que podem ser consultados mais rapidamente do que as outras propriedades. O Armazenamento do Azure utiliza a PartitionKey para distribuir automaticamente as entidades da tabela através de vários nós de armazenamento. As entidades com a mesma PartitionKey são armazenadas no mesmo nó. O RowKey é o ID exclusivo da entidade na partição a que pertence.

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

Atualizar uma entidade

Existem vários métodos disponíveis para atualizar uma entidade existente:

O exemplo seguinte demonstra como atualizar uma entidade com update_entity():

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

Com update_entity() e merge_entity(), se a entidade que está a atualizar não existir, a operação de atualização falhará. Por conseguinte, se pretender armazenar uma entidade, independentemente de já existir, deve, em vez disso, utilizar insert_or_replace_entity() ou insert_or_merge_entity().

Trabalhar com grupos de entidades

Por vezes, é útil submeter várias operações em conjunto num batch para garantir um processamento atómico pelo servidor. Para tal, crie primeiro um objeto de Batch e, em seguida, utilize o método execute_batch() no TableService. O exemplo seguinte demonstra como submeter duas entidades com RowKey 2 e 3 num batch. Tenha em atenção que funciona apenas para entidades com o mesmo 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)

Consultar uma entidade

Para consultar uma entidade numa tabela, utilize o método get_entity(), ao passar o nome da tabela, PartitionKey e RowKey.

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

Consultar um conjunto de entidades

Para consultar um conjunto de entidades numa tabela, crie um objeto de hash de consulta e utilize o método query_entities(). O exemplo seguinte demonstra como obter todas as entidades com a mesma PartitionKey:

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

Consultar um subconjunto de propriedades de entidade

Uma consulta a uma tabela pode obter apenas algumas propriedades de uma entidade. Esta técnica de "projeção" reduz a largura de banda e pode melhorar o desempenho das consultas, especialmente para grandes entidades. Utilize a cláusula selecionada e passe os nomes das propriedades que pretende levar ao cliente.

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

Eliminar uma entidade

Para eliminar uma entidade, utilize o método delete_entity(). Passe o nome da tabela que contém a entidade, a PartitionKey e a RowKey da entidade.

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

Eliminar uma tabela

Para eliminar uma tabela, utilize o método delete_table() e passe o nome da tabela que pretende eliminar.

azure_table_service.delete_table("testtable")

Conteúdo relacionado

• O Explorador de Armazenamento do Microsoft Azure é uma aplicação autónoma e gratuita da Microsoft, que lhe permite trabalhar visualmente com dados do Armazenamento do Azure no Windows, macOS e Linux.
• Centro de Programadores do Ruby
• Biblioteca de Cliente das Tabelas de Armazenamento do Microsoft Azure para Ruby