Como usar o Armazenamento de Tabelas do Azure e o Azure Cosmos DB for Table com Ruby

  • Artigo

APLICA-SE A: Tabela

Aviso

Este projeto está no estágio de suporte da comunidade do ciclo de vida dele. Eventualmente, todas as bibliotecas de cliente associadas serão desativadas permanentemente. Para obter mais informações sobre a desativação e as alternativas ao uso desse projeto, consulte Aviso de desativação : bibliotecas de clientes PHP do Armazenamento do Azure.

Dica

O conteúdo deste artigo se aplica ao Armazenamento de Tabelas do Azure e ao Azure Cosmos DB for Table. A API para Tabela é uma oferta premium para armazenamento de tabelas que oferece tabelas com otimização de taxa de transferência, distribuição global e índices secundários automáticos.

Este artigo mostra como criar tabelas, armazenar dados e realizar operações CRUD nos dados. Escolha o serviço de Tabela do Azure ou o Azure Cosmos DB for Table. Os exemplos descritos neste artigo são escritos em Ruby e usam a Biblioteca de clientes da Tabela do Armazenamento do Microsoft Azure para Ruby. Os cenários abordados incluem criar uma tabela, excluir uma tabela, inserir entidades e consultar entidades da tabela.

Criar conta de serviço do Azure

Você pode trabalhar com tabelas usando o Armazenamento de Tabelas do Azure ou o Azure Cosmos DB. Para saber mais sobre as diferenças entre as ofertas de tabela desses dois serviços, confira a Visão geral da API para tabela. Você precisa criar uma conta para o serviço que você vai usar. As seções a seguir mostram como criar as contas do Armazenamento de Tabelas do Azure e do Azure Cosmos DB, no entanto, você pode usar apenas um deles.

Armazenamento de Tabelas do Azure

A maneira mais fácil de criar uma conta de armazenamento do Azure é usando o portal do Azure. Para saber mais, consulte Criar uma conta de armazenamento.

Você também pode criar uma conta de armazenamento do Azure usando o Azure PowerShell ou a CLI do Azure.

Se você preferir não criar uma conta de armazenamento no momento, também poderá usar o Emulador de Armazenamento do Azure para executar e testar o seu código em um ambiente local. Para saber mais, confira Usar o Emulador de Armazenamento do Azure para desenvolvimento e teste.

Azure Cosmos DB for Table

Para obter instruções sobre como criar uma conta do Azure Cosmos DB for Table, veja Criar uma conta de banco de dados.

Adicionar acesso ao Armazenamento do Azure ou ao Azure Cosmos DB

Para usar o Armazenamento do Azure ou o Azure Cosmos DB, baixe e use o pacote ruby do Azure. Esse pacote inclui um conjunto de bibliotecas de conveniência que se comunicam com os serviços REST de Tabela.

Usar RubyGems para obter o pacote

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

Importar o pacote

Use seu editor de texto favorito e adicione o seguinte na parte superior do arquivo do Ruby no qual você pretende usar o Armazenamento:

require "azure/storage/table"

Adicionar sua cadeia de conexão

Você pode se conectar à conta de armazenamento do Azure ou à conta do Azure Cosmos DB for Table. Obtenha o cadeia de conexão com base no tipo de conta que você está usando.

Adicionar uma conexão do Armazenamento do Azure

O módulo do Armazenamento do Microsoft Azure lê as variáveis de ambiente AZURE_STORAGE_ACCOUNT e AZURE_STORAGE_ACCESS_KEY para obter as informações necessárias para se conectar à sua conta do Armazenamento do Azure. Se essas variáveis de ambiente não estiverem definidas, você deverá especificar as informações da conta antes de usar 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 esses valores de uma conta de armazenamento clássico ou do Resource Manager no Portal do Azure:

  1. Entre no portal do Azure.
  2. Navegue até a conta de armazenamento que você deseja usar.
  3. Na página Configurações, selecione Chaves de Acesso.
  4. Na página Chaves de acesso, observe a chave de acesso 1 e a chave de acesso 2. Você pode usar qualquer uma dessas chaves.
  5. Selecione o ícone para copiar a chave para a área de transferência.

Adicionar uma conexão do Azure Cosmos DB

Para se conectar ao Azure Cosmos DB, copie a cadeia de conexão principal do Portal do Azure e crie um objeto Client usando a cadeia de conexão copiada. Você pode passar o objeto Client quando 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 trabalhar com tabelas e entidades. Para criar uma tabela, use o método create_table() . O exemplo a seguir cria uma tabela ou imprime o erro se houver 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 hash que defina as propriedades da entidade. Para cada entidade, você deve especificar um PartitionKey e RowKey. Essas entidades são os identificadores exclusivos de suas entidades e são valores que podem ser consultados mais rapidamente do que suas outras propriedades. O Armazenamento do Azure usa PartitionKey para distribuir automaticamente as entidades da tabela entre vários nós de armazenamento. As entidades com o mesmo PartitionKey são armazenadas no mesmo nó. O RowKey é o ID exclusivo da entidade na partição à qual pertence.

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

Atualizar uma entidade

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

Descrição
update_entity() Atualiza uma entidade existente substituindo-a.
merge_entity() Atualiza uma entidade existente mesclando novos valores de propriedade com a entidade existente.
insert_or_merge_entity() Atualiza uma entidade existente substituindo-a. Se nenhuma entidade existir, uma nova será inserida.
insert_or_replace_entity() Atualiza uma entidade existente mesclando novos valores de propriedade com a entidade existente. Se nenhuma entidade existir, uma nova será inserida.

O exemplo a seguir demonstra a atualização de uma entidade usando 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 você está atualizando não existir, a operação de atualização falhará. Portanto, se desejar armazenar uma entidade independentemente de sua existência, você deverá usar insert_or_replace_entity() ou insert_or_merge_entity() .

Trabalhar com grupos de entidades

Às vezes, convém enviar várias operações juntas em um lote para garantir o processamento atômico pelo servidor. Para fazer isso, você cria primeiro um objeto Batch e depois usa o método execute_batch() em TableService. O seguinte exemplo demonstra o envio de duas entidades com RowKey 2 e 3 em um lote. Observe que isso funciona apenas em 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 em uma tabela, use o método get_entity() , transmitindo 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 em uma tabela, crie um objeto de hash de consulta e use o método query_entities() . O exemplo a seguir demonstra como obter todas as entidades com o mesmo PartitionKey:

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

Observação

Se o conjunto de resultados for muito grande para ser retornado por uma única consulta, um token de continuação será retornado para que você possa usar para recuperar páginas subsequentes.

consultar um subconjunto de propriedades da entidade

Uma consulta a uma tabela pode recuperar apenas algumas propriedades de uma entidade. Essa técnica de "projeção" reduz a largura de banda e pode melhorar o desempenho da consulta, especialmente para entidades grandes. Use a cláusula select e transmita os nomes das propriedades que você gostaria de trazer para o cliente.

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

Excluir uma entidade

Para excluir uma entidade, use o método delete_entity() . Transmita 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")

Excluir uma tabela

Para excluir uma tabela, use o método delete_table() e passe o nome da tabela que você quer excluir.

azure_table_service.delete_table("testtable")

Conteúdo relacionado