Come usare la libreria client di Azure Tables per Java

SI APPLICA A: Tabella

• .NET
• Node.JS
• Java
• C++
• PHP
• Go

Suggerimento

Il contenuto di questo articolo è applicabile alla risorsa di archiviazione di Azure Table e ad Azure Cosmos DB for Table. L'API per Table è un'offerta Premium per Azure Table Storage che include tabelle con ottimizzazione per la velocità effettiva, distribuzione globale e indici secondari automatici.

Questo articolo illustra come creare tabelle, archiviare i dati ed eseguire operazioni CRUD sui dati. Gli esempi sono scritti in PHP e usano la libreria client di Azure Tables per Java. Gli scenari presentati includono creazione, visualizzazione di un elenco ed eliminazione di tabelle, nonché inserimento, esecuzione di query, modifica ed eliminazione di entità in una tabella. Per altre informazioni sulle tabelle, vedere la sezione Passaggi successivi .

Importante

L'ultima versione della libreria client di Azure Tables che supporta Azure Table Storage e Azure Cosmos DB Table è 12+.

Creare un account del servizio di Azure

È possibile usare le tabelle con l'archiviazione tabelle di Azure o con Azure Cosmos DB. Per ulteriori informazioni sulle differenze tra le offerte per tabelle in questi due servizi, vedere Panoramica dell'API per Table. Sarà necessario creare un account per il servizio che si intende usare. Le sezioni seguenti illustrano come creare sia l'archiviazione tabelle di Azure che l'account Azure Cosmos DB, tuttavia è possibile scegliere tra uno dei due.

Creare un account di archiviazione di Azure

Il modo più semplice per creare un account di archiviazione di Azure consiste nell'usare il portale di Azure. Per ulteriori informazioni, vedi Creare un account di archiviazione.

È possibile anche creare un account di archiviazione di Azure usando Azure PowerShell o l'interfaccia della riga di comando di Azure.

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. Per altre informazioni, vedere Usare l'emulatore di archiviazione di Azure per sviluppo e test.

Creare un account di Azure Cosmos DB

Per istruzioni per la creazione di un account Azure Cosmos DB for Table, vedere Creare un account di database.

Creare un'applicazione Java

Per poter usare gli esempi di questo articolo, è necessario:

1. Installare Java Development Kit (JDK).
2. Creare un account di Archiviazione di Azure o un account Azure Cosmos DB nella sottoscrizione di Azure.
3. Verificare che il sistema di sviluppo in uso soddisfi i requisiti minimi e le dipendenze elencate nel repository Libreria client di Azure Tables per Java in GitHub.
4. Seguire le istruzioni per scaricare e installare le librerie di Archiviazione di Azure per Java nel sistema dal repository indicato.
5. Creare un'app Java che usi gli esempi presenti in questo articolo.

Configurare l'app per accedere a Table Storage

Aggiungere la voce seguente alla sezione dependencies del file pom.xml:

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

Aggiungere quindi le istruzioni import seguenti all'inizio del file Java in cui si desidera usare le API Azure Tables per accedere alle tabelle:

// Include the following imports to use table APIs
import com.azure.data.tables.TableClient;
import com.azure.data.tables.TableClientBuilder;
import com.azure.data.tables.TableServiceClient;
import com.azure.data.tables.TableServiceClientBuilder;
import com.azure.data.tables.models.ListEntitiesOptions;
import com.azure.data.tables.models.TableEntity;
import com.azure.data.tables.models.TableEntityUpdateMode;
import com.azure.data.tables.models.TableTransactionAction;
import com.azure.data.tables.models.TableTransactionActionType;

Crea una tabella

Un oggetto TableServiceClient consente di interagire con il servizio Table per creare, elencare ed eliminare tabelle. Il codice seguente consente di creare un oggetto TableServiceClient e di usarlo per creare un nuovo oggetto TableClient che rappresenta una tabella denominata Employees. L'oggetto TableServiceClient viene creato usando una credenziale di tipo TokenCredential. La DefaultAzureCredential classe crea una credenziale del token concatenato che funziona per la maggior parte delle applicazioni che usano Azure SDK provando più tipi di credenziali. Per ulteriori informazioni, vedere DefaultAzureCredential.

try
{
    final String tableName = "Employees";

    // Create a chained token credential
    TokenCredential credential = new DefaultAzureCredentialBuilder()
      .build();

    // Create a TableServiceClient with the token credential.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .endpoint("<endpoint>")
        .credential(credential)
        .buildClient();

    // Create the table if it not exists.
    TableClient tableClient = tableServiceClient.createTableIfNotExists(tableName);

}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Elencare le tabelle

Per ottenere un elenco di tabelle, chiamare il metodo TableServiceClient.listTables per recuperare un elenco iterabile di nomi di tabelle.

try
{
    // Create a chained token credential
    TokenCredential credential = new DefaultAzureCredentialBuilder()
      .build();

    // Create a TableServiceClient with the token credential.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .endpoint("<endpoint>")
        .credential(credential)
        .buildClient();

    // Loop through a collection of table names.
    tableServiceClient.listTables().forEach(tableItem -> 
        System.out.printf(tableItem.getName())
    );
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Aggiungere un'entità a una tabella

Il codice seguente consente di creare una nuova istanza della classe TableEntity con alcuni dati del cliente da archiviare. Il codice chiama il metodo upsertEntity sull'oggetto TableClient. Questo metodo inserisce la nuova entità cliente nella tabella Employees oppure sostituisce l'entità, se esiste già.

try
{
    final String tableName = "Employees";

    // Create a chained token credential
    TokenCredential credential = new DefaultAzureCredentialBuilder()
      .build();

    // Create a TableServiceClient with the token credential.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .endpoint("<endpoint>")
        .credential(credential)
        .tableName(tableName)
        .buildClient();

    // Create a new employee TableEntity.
    String partitionKey = "Sales";
    String rowKey = "0001";
    Map<String, Object> personalInfo= new HashMap<>();
    personalInfo.put("FirstName", "Walter");
    personalInfo.put("LastName", "Harp");
    personalInfo.put("Email", "Walter@contoso.com");
    personalInfo.put("PhoneNumber", "425-555-0101");
    TableEntity employee = new TableEntity(partitionKey, rowKey).setProperties(personalInfo);
        
    // Upsert the entity into the table
    tableClient.upsertEntity(employee);
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Inserire un batch di entità

Per inserire un batch di entità nel servizio tabelle, è possibile usare un'unica operazione di scrittura. Il codice seguente crea un oggetto List<TableTransactionAction> e quindi vi aggiunge tre operazioni di upsert. Ogni operazione viene aggiunta creando un nuovo oggetto TableEntity, impostandone le proprietà e quindi chiamando il metodo submitTransaction sull'oggetto TableClient.

try
{
    final String tableName = "Employees";

    // Create a chained token credential
    TokenCredential credential = new DefaultAzureCredentialBuilder()
      .build();

    // Create a TableServiceClient with the token credential.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .endpoint("<endpoint>")
        .credential(credential)
        .tableName(tableName)
        .buildClient();

    String partitionKey = "Sales";
    List<TableTransactionAction> tableTransactionActions = new ArrayList<>();
    
    Map<String, Object> personalInfo1 = new HashMap<>();
    personalInfo1.put("FirstName", "Jeff");
    personalInfo1.put("LastName", "Smith");
    personalInfo1.put("Email", "Jeff@contoso.com");
    personalInfo1.put("PhoneNumber", "425-555-0104");
    
    // Create an entity to add to the table.
    tableTransactionActions.add(new TableTransactionAction(
        TableTransactionActionType.UPSERT_MERGE,
        new TableEntity(partitionKey, "0001")
            .setProperties(personalInfo1)
    ));
    
    Map<String, Object> personalInfo2 = new HashMap<>();
    personalInfo2.put("FirstName", "Ben");
    personalInfo2.put("LastName", "Johnson");
    personalInfo2.put("Email", "Ben@contoso.com");
    personalInfo2.put("PhoneNumber", "425-555-0102");
    
    // Create another entity to add to the table.
    tableTransactionActions.add(new TableTransactionAction(
        TableTransactionActionType.UPSERT_MERGE,
        new TableEntity(partitionKey, "0002")
            .setProperties(personalInfo2)
    ));
    
    Map<String, Object> personalInfo3 = new HashMap<>();
    personalInfo3.put("FirstName", "Denise");
    personalInfo3.put("LastName", "Rivers");
    personalInfo3.put("Email", "Denise@contoso.com");
    personalInfo3.put("PhoneNumber", "425-555-0103");
    
    // Create a third entity to add to the table.
    tableTransactionActions.add(new TableTransactionAction(
        TableTransactionActionType.UPSERT_MERGE,
        new TableEntity(partitionKey, "0003")
            .setProperties(personalInfo3)
    ));

    // Submit transaction on the "Employees" table.
    tableClient.submitTransaction(tableTransactionActions);
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Di seguito sono riportate alcune informazioni sulle operazioni batch:

• È possibile eseguire fino a 100 operazioni di inserimento, eliminazione, unione, sostituzione, inserimento o unione e inserimento o sostituzione in qualsiasi combinazione in un unico batch.
• Un'operazione batch può prevedere un'operazione di recupero, se è l'unica operazione nel batch.
• A tutte le entità di una singola operazione batch deve essere associata la stessa chiave di partizione.
• Un'operazione batch è limitata a un payload di dati di 4 MB.

Recuperare tutte le entità di una partizione

Per eseguire una query su tabella per recuperare le entità in una partizione è possibile usare ListEntitiesOptions. Chiamare ListEntitiesOptions.setFilter per creare su una particolare tabella una query che restituisca un tipo di risultato specificato. Nel codice seguente viene specificato un filtro per le entità in cui la chiave di partizione è Sales. Quando la query viene eseguita con una chiamata a listEntities sull'oggetto TableClient, restituisce un oggetto Iterator di TableEntity. Per utilizzare i risultati, è quindi possibile usare l'oggetto Iterator restituito in un ciclo "ForEach". Il codice seguente consente di stampare sulla console i campi di ogni entità inclusa nei risultati della query.

try
{
    // Define constants for filters.
    final String PARTITION_KEY = "PartitionKey";
    final String tableName = "Employees";

    // Create a chained token credential
    TokenCredential credential = new DefaultAzureCredentialBuilder()
      .build();

    // Create a TableServiceClient with the token credential.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .endpoint("<endpoint>")
        .credential(credential)
        .tableName(tableName)
        .buildClient();

    // Create a filter condition where the partition key is "Sales".
    ListEntitiesOptions options = new ListEntitiesOptions().setFilter(PARTITION_KEY + " eq 'Sales'");

    // Loop through the results, displaying information about the entities.
    tableClient.listEntities(options, null, null).forEach(tableEntity -> {
        System.out.println(tableEntity.getPartitionKey() +
            " " + tableEntity.getRowKey() +
            "\t" + tableEntity.getProperty("FirstName") +
            "\t" + tableEntity.getProperty("LastName") +
            "\t" + tableEntity.getProperty("Email") +
            "\t" + tableEntity.getProperty("PhoneNumber"));
    });
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Recuperare un intervallo di entità in una partizione

Se non si desidera eseguire una query su tutte le entità di una partizione, specificare un intervallo usando gli operatori di confronto in un filtro. Il codice seguente combina due filtri per ottenere tutte le entità nella partizione Sales con una chiave di riga compresa tra '0001' e '0004'. e quindi stampare i risultati della query. Se si utilizzano le entità aggiunte alla tabella nella sezione di inserimento batch di questa guida, questa volta verranno restituite solo due entità, ovvero Ben e Denise.

try
{
    // Define constants for filters.
    final String PARTITION_KEY = "PartitionKey";
    final String ROW_KEY = "RowKey";
    final String tableName = "Employees";

    // Create a chained token credential
    TokenCredential credential = new DefaultAzureCredentialBuilder()
      .build();

    // Create a TableServiceClient with the token credential.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .endpoint("<endpoint>")
        .credential(credential)
        .tableName(tableName)
        .buildClient();

    // Create a filter condition where the partition key is "Sales".
    ListEntitiesOptions options = new ListEntitiesOptions().setFilter(PARTITION_KEY + " eq 'Sales' AND " + ROW_KEY + " lt '0004' AND " + ROW_KEY + " gt '0001'");
    
    // Loop through the results, displaying information about the entities.
    tableClient.listEntities(options, null, null).forEach(tableEntity -> {
        System.out.println(tableEntity.getPartitionKey() +
            " " + tableEntity.getRowKey() +
            "\t" + tableEntity.getProperty("FirstName") +
            "\t" + tableEntity.getProperty("LastName") +
            "\t" + tableEntity.getProperty("Email") +
            "\t" + tableEntity.getProperty("PhoneNumber"));
    });
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Recuperare una singola entità

Per recuperare una singola entità specifica, è possibile scrivere una query. Il codice seguente chiama TableClient.getEntity con i parametri della chiave di partizione e della chiave di riga per recuperare l'entità del dipendente "Jeff Smith", anziché creare un oggetto ListEntitiesOptions e usare filtri per eseguire la stessa operazione. Quando si esegue l'operazione di recupero viene restituita una sola entità piuttosto che una raccolta. Viene restituito un valore null se per nessuna entità è disponibile una corrispondenza esatta di chiave di riga e chiave di partizione. La specifica delle chiavi di partizione e di riga in una query costituisce la soluzione più rapida per recuperare una singola entità dal servizio tabelle .

try
{
    final String tableName = "Employees";

    // Create a chained token credential
    TokenCredential credential = new DefaultAzureCredentialBuilder()
      .build();

    // Create a TableServiceClient with the token credential.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .endpoint("<endpoint>")
        .credential(credential)
        .tableName(tableName)
        .buildClient();

    // Get the specific entity.
    TableEntity specificEntity = tableClient.getEntity("Sales", "0001");

    // Output the entity.
    if (specificEntity != null)
    {
        System.out.println(specificEntity.getPartitionKey() +
            " " + specificEntity.getRowKey() +
            "\t" + specificEntity.getProperty("FirstName") +
            "\t" + specificEntity.getProperty("LastName") +
            "\t" + specificEntity.getProperty("Email") +
            "\t" + specificEntity.getProperty("PhoneNumber"));
    }
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Modificare un'entità

Per modificare un'entità, recuperarla dal servizio tabelle, modificare l'oggetto entità e quindi salvare le modifiche nel servizio tabelle con un'operazione di sostituzione o unione. Il codice seguente consente di modificare il numero di telefono di un cliente esistente. Anziché chiamare tableClient.upsertEntity come è stato fatto per l'inserimento, questo codice chiama tableClient.updateEntity.

try
{
    final String tableName = "Employees";

    // Create a chained token credential
    TokenCredential credential = new DefaultAzureCredentialBuilder()
      .build();

    // Create a TableServiceClient with the token credential.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .endpoint("<endpoint>")
        .credential(credential)
        .tableName(tableName)
        .buildClient();

    // Get the specific entity.
    TableEntity specificEntity = tableClient.getEntity("Sales", "0001");

    // Specify a new phone number
    specificEntity.getProperties().put("PhoneNumber", "425-555-0105");

    // Update the specific entity
    tableClient.updateEntity(specificEntity, TableEntityUpdateMode.REPLACE);
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Eseguire query su un subset di proprietà di entità

Mediante una query su una tabella è possibile recuperare solo alcune proprietà da un'entità. Questa tecnica, denominata proiezione, consente di ridurre la larghezza di banda e di migliorare le prestazioni della query, in particolare per entità di grandi dimensioni. La query nel codice seguente usa il metodo ListEntitiesOptions.setSelect per restituire solo gli indirizzi di posta elettronica di entità nella tabella.

try
{
    final String tableName = "Employees";

    // Create a chained token credential
    TokenCredential credential = new DefaultAzureCredentialBuilder()
      .build();

    // Create a TableServiceClient with the token credential.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .endpoint("<endpoint>")
        .credential(credential)
        .tableName(tableName)
        .buildClient();

    // Create a filter condition that retrieves only the Email property.
    List<String> attributesToRetrieve = new ArrayList<>();
    attributesToRetrieve.add("Email");
    
    ListEntitiesOptions options = new ListEntitiesOptions().setSelect(attributesToRetrieve);

    // Loop through the results, displaying the Email values.
    tableClient.listEntities(options, null, null).forEach(tableEntity -> {
        System.out.println(tableEntity.getProperty("Email"));
    });
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Inserire o sostituire un'entità

Spesso si desidera aggiungere un'entità a una tabella senza sapere se sia già esistente nella tabella. Un'operazione di inserimento o sostituzione consente di effettuare una singola richiesta, che inserirà l'entità se non esiste o sostituirà quella esistente, se ne esiste già una. Sulla base degli esempi precedenti, il codice seguente consente di inserire o sostituire l'entità per "Walter Harp". Dopo aver creato una nuova entità, questo codice chiama il metodo TableClient.upsertEntity.

try
{
    final String tableName = "Employees";

    // Create a chained token credential
    TokenCredential credential = new DefaultAzureCredentialBuilder()
      .build();

    // Create a TableServiceClient with the token credential.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .endpoint("<endpoint>")
        .credential(credential)
        .tableName(tableName)
        .buildClient();

    // Create a new table entity.
    Map<String, Object> properties = new HashMap<>();
    properties.put("FirstName", "Walter");
    properties.put("LastName", "Harp");
    properties.put("Email", "Walter@contoso.com");
    properties.put("PhoneNumber", "425-555-0101");
        
    TableEntity newEmployee = new TableEntity("Sales", "0004")
        .setProperties(properties);
        
    // Add the new customer to the Employees table.
    tableClient.upsertEntity(newEmployee);
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Eliminazione di un'entità

È possibile eliminare un'entità usando le relative chiavi di partizione e di riga tramite TableClient.deleteEntity.

try
{
    final String tableName = "Employees";

    // Create a chained token credential
    TokenCredential credential = new DefaultAzureCredentialBuilder()
      .build();

    // Create a TableServiceClient with the token credential.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .endpoint("<endpoint>")
        .credential(credential)
        .tableName(tableName)
        .buildClient();

    // Delete the entity for partition key 'Sales' and row key '0001' from the table.
    tableClient.deleteEntity("Sales", "0001");
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Elimina una tabella

Nell'esempio di codice seguente viene infine illustrato come eliminare una tabella da un account. Per circa 40 secondi in seguito all'eliminazione di una tabella, non è possibile ricrearla.

try
{
    final String tableName = "Employees";

    // Create a chained token credential
    TokenCredential credential = new DefaultAzureCredentialBuilder()
      .build();

    // Create a TableServiceClient with the token credential.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .endpoint("<endpoint>")
        .credential(credential)
        .tableName(tableName)
        .buildClient();

    // Delete the table and all its data.
    tableClient.deleteTable();
}
catch (Exception e)
{
    // Output the stack trace.
    e.printStackTrace();
}

Suggerimento

Estrarre il repository degli esempi di codice di Archiviazione di Azure

Per esempi di codice end-to-end facile da usare che è possibile scaricare ed eseguire, vedere l'elenco di esempi di Archiviazione di Azure.

Passaggi successivi

• Getting Started with Azure Table Service in Java (Introduzione al servizio tabelle di Azure in Java)
• Microsoft Azure Storage Explorer è un'app autonoma gratuita di Microsoft che consente di rappresentare facilmente dati di Archiviazione di Azure in Windows, macOS e Linux.
• Libreria client di Azure Tables per Java
• Informazioni di riferimento sulla libreria client di Azure Tables
• API REST di Azure Tables
• Blog del team di Azure Tables

Per altre informazioni, vedere Azure for Java developers (Azure per sviluppatori Java).