De Azure Tables-clientbibliotheek voor Java gebruiken

VAN TOEPASSING OP: Tafel

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

Tip

De inhoud in dit artikel is van toepassing op Azure Table Storage en Azure Cosmos DB for Table. De API voor Table is een premium-aanbieding voor tabelopslag met tabellen die zijn geoptimaliseerd voor doorvoer, wereldwijde distributie en automatische secundaire indexen.

In dit artikel leest u hoe u tabellen maakt, uw gegevens opslaat en CRUD-bewerkingen uitvoert op deze gegevens. De voorbeelden worden geschreven in Java en gebruiken de Azure Tables-clientbibliotheek voor Java. De volgende scenario's worden behandeld: het maken, in een lijst opnemen en verwijderen van tabellen, alsmede het invoegen, uitvoeren van query's, aanpassen en verwijderen van entiteiten in een tabel. Zie de sectie Volgende stappen voor meer informatie over tabellen.

Belangrijk

De laatste versie van de Azure Tables-clientbibliotheek die Table Storage en Azure Cosmos DB Table ondersteunt, is 12+.

Een Azure-serviceaccount maken

U kunt in Azure Table Storage of in Azure Cosmos DB met tabellen werken. Zie het overzicht van de API voor Table voor meer informatie over de verschillen tussen tabelaanbiedingen in deze twee services. U moet een account maken voor de service die u gaat gebruiken. De volgende secties laten zien hoe u zowel een Azure Table Storage- als een Azure Cosmos DB-account maakt. U kunt echter slechts één daarvan gebruiken.

Een Azure-opslagaccount maken

De eenvoudigste manier om uw eerste Azure-opslagaccount te maken, is via de Azure-portal. Zie: Een opslagaccount maken voor meer informatie.

U kunt ook een Azure Storage-account maken met behulp van Azure PowerShell of de Azure CLI.

Als u op dit moment liever nog geen opslagaccount maakt, kunt u ook de Azure-opslagemulator gebruiken om de code in een lokale omgeving uit te voeren en te testen. Zie De Azure-opslagemulator gebruiken voor ontwikkelen en testen voor meer informatie.

Azure Cosmos DB-account maken

Zie Een databaseaccount maken voor instructies voor het maken van een Azure Cosmos DB for Table-account.

Een Java-toepassing maken

De voorbeelden in dit artikel gebruiken:

1. Installeer de Java Development Kit (JDK).
2. Maak een Azure-opslagaccount of Een Azure Cosmos DB-account in uw Azure-abonnement.
3. Controleer of uw ontwikkelsysteem voldoet aan de minimale vereisten en afhankelijkheden die worden vermeld in de Azure Tables-clientbibliotheek voor Java-opslagplaats op GitHub.
4. Volg de instructies voor het downloaden en installeren van de Azure Storage-bibliotheken voor Java op uw systeem vanuit die opslagplaats.
5. Maak een Java-app die gebruikmaakt van de voorbeelden in dit artikel.

Uw app configureren voor toegang tot Table Storage

Voeg de volgende vermelding toe aan de sectie van dependencies het pom.xml-bestand:

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

Voeg vervolgens de volgende import instructies toe aan het begin van het Java-bestand waar u Azure Tables-API's wilt gebruiken voor toegang tot tabellen:

// 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;

Een tabel maken

Met een TableServiceClient object kunt u communiceren met de Tabellen-service om tabellen te maken, weer te geven en te verwijderen. Met de volgende code wordt een TableServiceClient object gemaakt en gebruikt om een nieuw TableClient object te maken, dat een tabel met de naam Employeesvertegenwoordigt. Het TableServiceClient object wordt gemaakt met behulp van een referentie van het type TokenCredential. De DefaultAzureCredential klasse maakt een gekoppelde tokenreferentie die werkt voor de meeste toepassingen die gebruikmaken van de Azure SDK door meerdere typen referenties te proberen. Zie DefaultAzureCredential voor meer informatie.

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();
}

De tabellen vermelden

Als u een lijst met tabellen wilt ophalen, roept u de TableServiceClient.listTables methode aan om een iterable lijst met tabelnamen op te halen.

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();
}

Een entiteit toevoegen aan een tabel

Met de volgende code maakt u een nieuwe instantie van de klasse TableEntity, waarbij een aantal klantgegevens worden opgeslagen. Met de code wordt de upsertEntity methode voor het TableClient object aangeroepen. Met deze methode wordt de nieuwe klantentiteit in de Employees tabel ingevoegd of wordt de entiteit vervangen als deze al bestaat.

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();
}

Een batch entiteiten invoegen

U kunt in één schrijfbewerking een batch entiteiten invoegen in de tabelservice. Met de volgende code wordt een List<TableTransactionAction> object gemaakt en worden er vervolgens drie upsert-bewerkingen aan toegevoegd. Elke bewerking wordt toegevoegd door een nieuw TableEntity object te maken, de eigenschappen ervan in te stellen en vervolgens de submitTransaction methode voor het object aan te TableClient roepen.

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();
}

Een aantal zaken die u moet weten over batchbewerkingen:

• U kunt maximaal 100 bewerkingen voor invoegen, verwijderen, samenvoegen, vervangen, invoegen of samenvoegen, en invoegen of vervangen in elke willekeurige combinatie in één batch uitvoeren.
• Een batchbewerking kan een ophaalbewerking hebben als dit de enige bewerking in de batch is.
• Alle entiteiten in een batchbewerking moeten dezelfde partitiesleutel hebben.
• Een batchbewerking is beperkt tot een gegevensnettolading van 4 MB.

Alle entiteiten in een partitie ophalen

Gebruik een ListEntitiesOptions om een tabel met entiteiten in een partitie op te vragen. Roep ListEntitiesOptions.setFilter aan om een query op een specifieke tabel te maken waarmee een opgegeven resultaattype wordt geretourneerd. De volgende code geeft een filter op voor entiteiten waar Sales de partitiesleutel is. Wanneer de query wordt uitgevoerd met een aanroep naar listEntities het object, retourneert deze TableClient een Iterator van TableEntity. U kunt vervolgens de geretourneerde Iterator in een 'ForEach'-lus gebruiken om de resultaten te gebruiken. In deze code worden de velden van elke entiteit in de queryresultaten naar de console afgedrukt.

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();
}

Een bereik van entiteiten in een partitie ophalen

Als u niet alle entiteiten in een partitie wilt opvragen, geeft u een bereik op met behulp van vergelijkingsoperators in een filter. De volgende code combineert twee filters om alle entiteiten in de partitie Sales op te halen met een rijsleutel tussen '0001' en '0004'. Vervolgens worden de queryresultaten afgedrukt. Als u de entiteiten gebruikt die zijn toegevoegd aan de tabel in de sectie batchinvoeging van deze handleiding, worden deze keer slechts twee entiteiten geretourneerd (Ben en 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();
}

Eén entiteit ophalen

U kunt een query schrijven om één specifieke entiteit op te halen. Met de volgende code worden parameters voor partitiesleutel en rijsleutel aanroepen TableClient.getEntity om de entiteit op te halen voor werknemer Jeff Smith, in plaats van filters ListEntitiesOptions te maken om hetzelfde te doen. Wanneer de ophaalbewerking wordt uitgevoerd, wordt slechts één entiteit geretourneerd in plaats van een hele verzameling. Er wordt een null waarde geretourneerd als er geen entiteit een exacte partitie- en rijsleutelovereenkomst heeft. Het opgeven van zowel partitie- als rijsleutels in een query is de snelste manier om één entiteit op te halen uit de Tabelservice.

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();
}

Een entiteit aanpassen

Als u een entiteit wilt aanpassen, haalt u deze op uit de tabelservice, wijzigt u het entiteitsobject en slaat u de wijzigingen weer op in de tabelservice met een vervangings- of samenvoegingsbewerking. De volgende code wijzigt het telefoonnummer van een bestaande klant. In plaats van aan te roepen tableClient.upsertEntity zoals we hebben gedaan om in te voegen, roept tableClient.updateEntitydeze code aan.

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();
}

Een query uitvoeren op een subset van entiteitseigenschappen

Met een query naar een tabel kunnen slechts enkele eigenschappen van een entiteit worden opgehaald. Deze methode, projectie genoemd, verbruikt minder bandbreedte en kan de queryprestaties verbeteren, vooral bij grote entiteiten. Met de query in de volgende code gebruikt u de methode ListEntitiesOptions.setSelect om alleen de e-mailadressen van de entiteiten in de tabel te retourneren.

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();
}

Een entiteit invoegen of vervangen

Vaak zult u een entiteit aan een tabel willen toevoegen zonder te weten of deze entiteit al in de tabel bestaat. Met een invoeg- of vervangingsbewerking kunt u één aanvraag indienen. Met deze aanvraag wordt de entiteit ingevoegd als deze niet bestaat of als deze de bestaande aanvraag vervangt. Op basis van de vorige voorbeelden voegt u met de volgende code de entiteit voor ‘Walter Harp’ in of vervangt u met de code deze entiteit. Nadat u een nieuwe entiteit hebt gemaakt, roept deze code de TableClient.upsertEntity methode aan.

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();
}

Een entiteit verwijderen

U kunt een entiteit verwijderen door de partitiesleutel en rijsleutel op te geven via 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();
}

Een tabel verwijderen

Ten slotte verwijdert de volgende code een tabel uit een account. Gedurende ongeveer 40 seconden nadat u een tabel hebt verwijderd, kunt u deze niet opnieuw maken.

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();
}

Tip

Bekijk de opslagplaats met codevoorbeelden van Azure Storage

Raadpleeg onze lijst met Azure Storage-voorbeelden voor eenvoudig te gebruiken end-to-end Azure Storage-codevoorbeelden die u kunt downloaden en uitvoeren.

Volgende stappen

• Aan de slag met de Azure-tabelservice in Java
• Microsoft Azure Storage Explorer is een gratis, zelfstandige app van Microsoft waarmee u visueel met Azure Storage-gegevens kunt werken in Windows, macOS en Linux.
• Azure Tables-clientbibliotheek voor Java
• Naslaginformatie voor Azure Tables-clientbibliotheek
• Azure Tables REST API
• Azure Tables Team Blog

Voor meer informatie gaat u naar Azure voor Java-ontwikkelaars.