Biblioteca de clientes das Tabelas do Azure para Java – versão 12.3.16

  • Artigo

As Tabelas do Azure são um serviço que armazena dados NoSQL estruturados na nuvem, fornecendo um repositório de chaves/atributos com um design sem esquema. As Tabelas do Azure oferecem aos desenvolvedores flexibilidade e escalabilidade com todas as melhores partes da nuvem do Azure.

Código-fonte | Pacote (Maven) | Documentação | de referência da APIDocumentação do produto | Amostras

Introdução

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

e inclua a dependência direta na seção dependências sem a marca de versão, conforme mostrado abaixo.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-data-tables</artifactId>
    </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-data-tables</artifactId>
  <version>12.3.16</version>
</dependency>

Pré-requisitos

Criar uma conta de armazenamento

Para criar uma Conta de Armazenamento, você pode usar o Portal do Azure ou a CLI do Azure.

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

A URL da conta de armazenamento, posteriormente identificada como <your-table-account-url>, seria formatada da seguinte maneira http(s)://<storage-account-name>.table.core.windows.net.

Criar uma conta da API de Tabela do Cosmos DB

Para criar uma conta da API de Tabela do Cosmos DB, você pode usar o Portal do Azure ou a CLI do Azure.

az cosmosdb create \
    --resource-group <resource-group-name> \
    --name <cosmosdb-account-name> \
    --capabilities EnableTable

A URL da conta da API de Tabela, posteriormente identificada como <your-table-account-url>, seria formatada da seguinte maneira http(s)://<cosmosdb-account-name>.table.cosmosdb.azure.com.

Autenticar o cliente

Cada solicitação feita ao serviço Tabelas deve ser autorizada usando uma cadeia de conexão, credencial de chave nomeada, Assinatura de Acesso Compartilhado ou credenciais de token. Os exemplos abaixo demonstram o uso desses métodos.

Observação: somente os pontos de extremidade da API de Armazenamento do Azure atualmente dão suporte à autorização do AAD por meio de credenciais de token.

Cadeia de conexão

Um cadeia de conexão inclui as informações de autenticação necessárias para que seu aplicativo acesse dados em uma tabela do Azure em runtime usando a autorização de Chave Compartilhada. Consulte Autenticar com uma cadeia de conexão para obter um exemplo de como usar um cadeia de conexão com um TableServiceClient.

Você pode obter sua cadeia de conexão no Portal do Azure (clique em Chaves de acesso em Configurações na folha Conta de Armazenamento do Portal ou Cadeia de Conexão em Configurações na folha da conta do Portal Cosmos DB) ou usando a CLI do Azure:

# Storage account
az storage account show-connection-string \
    --resource-group <resource-group-name> \
    --name <storage-account-name>

# Cosmos DB Table API account
az cosmosdb list-connection-strings \
    --resource-group <resource-group-name> \
    --name <cosmosdb-account-name>

Credencial de chave compartilhada

A autorização com chave compartilhada usa as chaves de acesso de sua conta e outros parâmetros para produzir uma cadeia de caracteres de assinatura criptografada que é passada na solicitação no cabeçalho de autorização. Consulte Autenticar com uma credencial de Chave Compartilhada para obter um exemplo de como usar a autorização de chave nomeada com um TableServiceClient.

Para usar a autorização de Chave Nomeada, você precisará do nome da conta e da URL, bem como de uma chave de acesso da conta. Você pode obter sua chave de acesso primária no Portal do Azure (clique em Chaves de acesso em Configurações na folha Conta de Armazenamento do Portal ou Cadeia de Conexão em Configurações na folha da conta do Portal Cosmos DB) ou usando a CLI do Azure:

# Storage account
az storage account keys list \
    --resource-group <resource-group-name> \
    --account-name <storage-account-name>

# Cosmos DB Table API account
az cosmosdb list-keys \
    --resource-group <resource-group-name> \
    --name <cosmosdb-account-name>

SAS (Assinatura de Acesso Compartilhado)

Uma Assinatura de Acesso Compartilhado permite que os administradores delegam acesso granular a uma tabela do Azure sem compartilhar a chave de acesso diretamente. Você pode controlar quais recursos o cliente pode acessar, quais permissões ele tem nesses recursos e por quanto tempo a SAS é válida, entre outros parâmetros. Ele depende das chaves de acesso da conta e de outros parâmetros para produzir uma cadeia de caracteres de assinatura criptografada que é passada na solicitação na cadeia de caracteres de consulta. Consulte Autenticar com uma SAS (Assinatura de Acesso Compartilhado) para obter um exemplo de como usar assinaturas de acesso compartilhado com um TableServiceClient.

Para usar a autorização de token SAS, você precisará do nome da conta e da URL, bem como da SAS. Você pode obter sua SAS no Portal do Azure (clique em Assinatura de acesso compartilhado em Configurações na folha Conta de Armazenamento do Portal) ou usando a CLI do Azure:

# Account-level SAS
az storage account generate-sas \
    --account-name <storage-or-cosmosdb-account-name> \
    --services t \
    --resource-types <resource-types> \
    --permissions <permissions> \
    --expiry <expiry-date>

# Table-level SAS
az storage table generate-sas \
    --name <table-name>

TokenCredential

As Tabelas do Azure fornecem integração com o AAD (Azure Active Directory) para autenticação baseada em identidade de solicitações para o serviço Tabela ao direcionar um ponto de extremidade de Armazenamento. Com o AAD, você pode usar o RBAC (controle de acesso baseado em função) para conceder acesso aos recursos da Tabela do Azure a usuários, grupos ou aplicativos.

Para acessar um recurso de tabela com um TokenCredential, a identidade autenticada deve ter a função "Colaborador de Dados da Tabela de Armazenamento" ou "Leitor de Dados da Tabela de Armazenamento".

Com o azure-identity pacote, você pode autorizar diretamente solicitações em ambientes de desenvolvimento e produção. Para saber mais sobre Azure AD integração no Armazenamento do Azure, consulte o LEIAME de Identidade do Azure.

Principais conceitos

  • TableServiceClient – Um TableServiceClient é um objeto cliente que permite interagir com o Serviço de Tabela para criar, listar e excluir tabelas.
  • TableClient – Um TableClient é um objeto cliente que permite que você interaja com uma tabela específica para criar, upsert, atualizar, obter, listar e excluir entidades dentro dela.
  • Tabela – uma tabela é uma coleção de entidades. As tabelas não impõem um esquema nas entidades, o que significa que uma única tabela pode conter entidades com diferentes conjuntos de propriedades.
  • Entidade – uma entidade é um conjunto de propriedades, semelhante a uma linha de banco de dados. Uma entidade no Armazenamento do Azure pode ser de até 1MB de tamanho. Uma entidade no Azure Cosmos DB pode ser de até 2MB de tamanho. Uma entidade tem uma chave de partição e uma chave de linha que juntas identificam exclusivamente a entidade dentro da tabela.
  • Propriedades – uma propriedade é um par nome-valor. Cada entidade pode incluir até 252 propriedades para armazenar dados. Cada entidade possui também três propriedades do sistema que especificam uma chave de partição, uma chave de linha e um carimbo de hora.
  • Chave de Partição – a chave de partição de uma entidade identifica a partição dentro da tabela à qual a entidade pertence. As entidades com a mesma chave de partição podem ser consultadas mais rapidamente e inseridas/atualizadas em operações atômicas.
  • Chave de Linha – a chave de linha de uma entidade é seu identificador exclusivo dentro de uma partição.

Os usos comuns do serviço Tabelas incluem:

  • Armazenamento de TBs de dados estruturados capazes de atender a aplicativos de dimensionamento da Web
  • Armazenar conjuntos de dados que não exigem junções complexas, chaves estrangeiras ou procedimentos armazenados e podem ser des normalizados para acesso rápido
  • Consulta rápida de dados usando um índice clusterizado
  • Acessando dados usando o protocolo OData

Exemplos

Autenticar um cliente

Autenticar com um cadeia de conexão

Para usar um cadeia de conexão para autorizar seu cliente, chame o método do connectionString construtor com seu cadeia de conexão.

TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .connectionString("<your-connection-string>")
    .buildClient();

Autenticar com uma chave compartilhada

Para usar uma Chave Compartilhada para autorizar seu cliente, crie uma instância do com o nome da sua conta e a chave de AzureNamedKeyCredential acesso. Chame o método do construtor com a URL da endpoint conta e o credential método com o AzureNamedKeyCredential objeto que você criou.

AzureNamedKeyCredential credential = new AzureNamedKeyCredential("<your-account-name>", "<account-access-key>");
TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .credential(credential)
    .buildClient();

Autenticar com uma SAS (Assinatura de Acesso Compartilhado)

Para usar uma SAS para autorizar seu cliente, chame o método do construtor com a URL da endpoint conta e o sasToken método com sua SAS.

TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .sasToken("<sas-token-string>")
    .buildClient();

Autenticar com credenciais de token

Para autorizar seu cliente por meio do AAD, crie uma instância de uma classe de credenciais que implementa TokenCredential. Chame o método do construtor com a URL da endpoint conta e o credential método com o TokenCredential objeto que você criou.

TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .credential(tokenCredential)
    .buildClient();

Criar, listar e excluir tabelas do Azure

Construir um TableServiceClient

Construa um TableServiceClient criando uma instância de TableServiceClientBuilder e, em seguida, chamando os métodos ou buildAsyncClient do buildClient construtor.

TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .connectionString("<your-connection-string>") // or use any of the other authentication methods
    .buildClient();

Criar uma tabela

Crie uma tabela chamando o TableServiceClientmétodo do .createTable Um TableClient será retornado, esse cliente permite executar operações na tabela. Uma exceção será gerada se houver uma tabela com o nome fornecido.

TableClient tableClient = tableServiceClient.createTable(tableName);

Como alternativa, você pode chamar o createTableIfNotExists método que criará a tabela somente se essa tabela não existir e não gerar uma exceção. Um TableClient também será retornado.

TableClient tableClient = tableServiceClient.createTableIfNotExists(tableName);

Listar tabelas

Liste ou consulte o conjunto de tabelas existentes chamando o TableServiceClientmétodo do listTables , opcionalmente passando uma ListTablesOptions instância para filtrar ou limitar os resultados da consulta. Consulte Opções de consulta com suporte para obter detalhes sobre as opções de consulta com suporte.

ListTablesOptions options = new ListTablesOptions()
    .setFilter(String.format("TableName eq '%s'", tableName));

for (TableItem tableItem : tableServiceClient.listTables(options, null, null)) {
    System.out.println(tableItem.getName());
}

Excluir uma tabela

Exclua uma tabela chamando o TableServiceClientmétodo do .deleteTable

tableServiceClient.deleteTable(tableName);

Criar, listar e excluir entidades de tabela

Construir um TableClient

Construa um TableClient criando uma instância de TableClientBuilder, chamando o método do tableName construtor com o nome da tabela e chamando seus buildClient métodos ou buildAsyncClient .

TableClient tableClient = new TableClientBuilder()
    .connectionString("<your-connection-string>") // or use any of the other authentication methods
    .tableName(tableName)
    .buildClient();

Como alternativa, um TableClient pode ser recuperado de um existente TableServiceClient chamando seu getTableClient método.

TableClient tableClient = tableServiceClient.getTableClient(tableName);

Criar uma entidade

Crie uma nova TableEntity instância, fornecendo a chave de partição e a chave de linha da entidade a ser criada, opcionalmente adicionando propriedades ao objeto criado. Em seguida, passe o objeto para o TableClientmétodo do .createEntity Uma exceção será gerada se uma entidade com a chave de partição fornecida e a chave de linha existirem dentro da tabela.

TableEntity entity = new TableEntity(partitionKey, rowKey)
    .addProperty("Product", "Marker Set")
    .addProperty("Price", 5.00)
    .addProperty("Quantity", 21);

tableClient.createEntity(entity);

Listar entidades

Liste ou consulte o conjunto de entidades dentro da tabela chamando o TableClientmétodo 's listEntities , opcionalmente passando uma ListEntitiesOptions instância para filtrar, selecionar ou limitar os resultados da consulta. Consulte Opções de consulta com suporte para obter detalhes sobre as opções de consulta com suporte.

List<String> propertiesToSelect = new ArrayList<>();
propertiesToSelect.add("Product");
propertiesToSelect.add("Price");

ListEntitiesOptions options = new ListEntitiesOptions()
    .setFilter(String.format("PartitionKey eq '%s'", partitionKey))
    .setSelect(propertiesToSelect);

for (TableEntity entity : tableClient.listEntities(options, null, null)) {
    Map<String, Object> properties = entity.getProperties();
    System.out.printf("%s: %.2f%n", properties.get("Product"), properties.get("Price"));
}

Excluir uma entidade

Exclua uma entidade chamando o TableClientmétodo do .deleteEntity

tableClient.deleteEntity(partitionKey, rowKey);

Solução de problemas

Geral

Quando você interage com o serviço Tabelas usando a biblioteca tabelas do Azure para Java, os erros retornados pelo serviço correspondem aos mesmos códigos http status retornados para solicitações de API REST.

Por exemplo, se você tentar criar uma tabela que já existe, um 409 erro será retornado, indicando "Conflito".

// Create the table if it doesn't already exist.
tableServiceClient.createTableIfNotExists(tableName);

// Now attempt to create the same table unconditionally.
try {
    tableServiceClient.createTable(tableName);
} catch (TableServiceException e) {
    System.out.println(e.getResponse().getStatusCode()); // 409
}

Registro em log

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a AZURE_LOG_LEVEL variável de ambiente como a verbosidade desejada. Consulte LogLevel para obter uma descrição dos níveis de log disponíveis.

Próximas etapas

Introdução aos nossos exemplos de Tabela.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder e de fato concede, os direitos de usar sua contribuição.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões