Come usare la libreria client tabelle di Azure per Java

SI APPLICA A: Tabella

Questo articolo illustra come creare tabelle, archiviare i dati ed eseguire operazioni CRUD su tali dati. Gli esempi sono scritti in Java e usano la libreria client tabelle di Azure 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 .

Creare un account del servizio di Azure

È possibile usare le tabelle con l'archiviazione tabelle di Azure o con Azure Cosmos DB. Per altre informazioni sulle differenze tra le offerte di tabelle in questi due servizi, vedere panoramica dell'API per la tabella. 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 sulla creazione di un account Azure Cosmos DB per tabelle, vedere Creare un account di database.

Creare un'applicazione Java

Per usare gli esempi in questo articolo:

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 soddisfi i requisiti minimi e le dipendenze elencati nella libreria client tabelle di Azure per il repository Java in GitHub.
4. Seguire le istruzioni per scaricare e installare le librerie di Archiviazione di Azure per Java nel sistema da tale repository.
5. Creare un'app Java che usa gli esempi in questo articolo.

Configurare l'app per l'accesso a Table Archiviazione

Aggiungere la voce seguente alla sezione del file pom.xmldependencies:

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

Aggiungere quindi le istruzioni seguenti import all'inizio del file Java in cui si vogliono usare le API tabelle di Azure 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;

Aggiungere la stringa di connessione

È possibile connettersi all'account di archiviazione di Azure o all'account Azure Cosmos DB per tabelle. Ottenere la stringa di connessione in base al tipo di account in uso.

Aggiungere un Archiviazione di Azure stringa di connessione

Un client tabelle di Azure può usare un stringa di connessione di archiviazione per archiviare endpoint e credenziali per l'accesso ai servizi di gestione dei dati. Quando si esegue in un'app client, è necessario specificare il Archiviazione stringa di connessione nel formato seguente, usando il nome dell'account Archiviazione e la chiave di accesso primaria per l'account Archiviazione elencato nel portale di Azure per il Valori AccountName e AccountKey.

In questo esempio viene illustrato come dichiarare un campo statico per memorizzare la stringa di connessione:

// Define the connection-string with your values.
public final String connectionString =
    "DefaultEndpointsProtocol=http;" +
    "AccountName=your_storage_account;" +
    "AccountKey=your_storage_account_key;" +
    "EndpointSuffix=core.windows.net";

Aggiungere un'istanza di Azure Cosmos DB per table stringa di connessione

Un account di Azure Cosmos DB usa una stringa di connessione per archiviare l'endpoint della tabella e le credenziali. Quando si esegue in un'app client, è necessario specificare il stringa di connessione azure Cosmos DB nel formato seguente, usando il nome dell'account Azure Cosmos DB e la chiave di accesso primaria per l'account elencato nel portale di Azure per i valori AccountName e AccountKey.

Questo esempio illustra come dichiarare un campo statico per memorizzare la stringa di connessione di Azure Cosmos DB:

public final String connectionString =
    "DefaultEndpointsProtocol=https;" + 
    "AccountName=your_cosmosdb_account;" + 
    "AccountKey=your_account_key;" + 
    "TableEndpoint=https://your_endpoint;";

In un'app in esecuzione all'interno di un ruolo in Azure è possibile archiviare questa stringa nel file di configurazione del servizio ServiceConfiguration.cscfg. È possibile accedervi con una chiamata al System.getenv metodo . Ecco un esempio di recupero del stringa di connessione da un elemento Setting denominato Connessione ionString nel file di configurazione del servizio:

// Retrieve storage account from connection-string.
String connectionString = System.getenv("ConnectionString");

È anche possibile archiviare la stringa di connessione nel file config.properties del progetto:

connectionString = DefaultEndpointsProtocol=https;AccountName=your_account;AccountKey=your_account_key;TableEndpoint=https://your_table_endpoint/

Gli esempi seguenti presumono che sia stato usato uno di questi metodi per ottenere la stringa di connessione di archiviazione.

Crea una tabella

Un TableServiceClient oggetto consente di interagire con il servizio Tabelle per creare, elencare ed eliminare tabelle. Il codice seguente crea un TableServiceClient oggetto e lo usa per creare un nuovo TableClient oggetto , che rappresenta una tabella denominata Employees.

try
{
    final String tableName = "Employees";

    // Create a TableServiceClient with a connection string.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .connectionString(connectionString)
        .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 TableServiceClient.listTables metodo per recuperare un elenco iterabile di nomi di tabella.

try
{
    // Create a TableServiceClient with a connection string.
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
        .connectionString(connectionString)
        .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 upsertEntity metodo sull'oggetto TableClient . Tale metodo inserisce la nuova entità cliente nella Employees tabella o sostituisce l'entità, se già esistente.

try
{
    final String tableName = "Employees";

    // Create a TableClient with a connection string and a table name.
     TableClient tableClient = new TableClientBuilder()
        .connectionString(connectionString)
        .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 List<TableTransactionAction> oggetto, quindi aggiunge tre operazioni di upsert. Ogni operazione viene aggiunta creando un nuovo TableEntity oggetto, impostandone le proprietà e quindi chiamando il submitTransaction metodo sull'oggetto TableClient .

try
{
    final String tableName = "Employees";

    // Create a TableClient with a connection string and a table name.
    TableClient tableClient = new TableClientBuilder()
        .connectionString(connectionString)
        .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. Il codice seguente specifica un filtro per le entità in cui Sales è la chiave di partizione. Quando la query viene eseguita con una chiamata a sull'oggetto listEntitiesTableClient , restituisce un 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 TableClient with a connection string and a table name.
    TableClient tableClient = new TableClientBuilder()
        .connectionString(connectionString)
        .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 query su tutte le entità in 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 usano le entità aggiunte alla tabella nella sezione di inserimento batch di questa guida, vengono restituite solo due entità questa volta (Ben e Denise).

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

    // Create a TableServiceClient with a connection string.
    // Create a TableClient with a connection string and a table name.
    TableClient tableClient = new TableClientBuilder()
        .connectionString(connectionString)
        .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à per il dipendente "Jeff Smith", invece di creare e ListEntitiesOptions usare filtri per eseguire la stessa operazione. Quando si esegue l'operazione di recupero viene restituita una sola entità piuttosto che una raccolta. Se null nessuna entità ha una corrispondenza esatta di partizione e chiave di riga, viene restituito un valore. 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 TableClient with a connection string and a table name.
    TableClient tableClient = new TableClientBuilder()
        .connectionString(connectionString)
        .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. Invece di chiamare tableClient.upsertEntity come è stato fatto per l'inserimento, questo codice chiama tableClient.updateEntity.

try
{
    final String tableName = "Employees";

    // Create a TableClient with a connection string and a table name.
    TableClient tableClient = new TableClientBuilder()
        .connectionString(connectionString)
        .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 TableClient with a connection string and a table name.
    TableClient tableClient = new TableClientBuilder()
        .connectionString(connectionString)
        .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. Tale richiesta inserirà l'entità se non esiste o sostituirà quella esistente, se lo fa. 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 TableClient.upsertEntity metodo .

try
{
    final String tableName = "Employees";

    // Create a TableClient with a connection string and a table name.
    TableClient tableClient = new TableClientBuilder()
        .connectionString(connectionString)
        .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à specificando la chiave di partizione e la chiave di riga tramite TableClient.deleteEntity.

try
{
    final String tableName = "Employees";

    // Create a TableClient with a connection string and a table name.
    TableClient tableClient = new TableClientBuilder()
        .connectionString(connectionString)
        .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

Infine, il codice seguente elimina 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 TableClient with a connection string and a table name.
    TableClient tableClient = new TableClientBuilder()
        .connectionString(connectionString)
        .tableName(tableName)
        .buildClient();

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

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 Tabelle di Azure per Java
• Informazioni di riferimento sulla libreria client tabelle di Azure
• API REST tabelle di Azure
• Blog del team di tabelle di Azure

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