De Azure Tables-clientbibliotheek voor Java gebruiken

VAN TOEPASSING OP: Tabel

• .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;

Uw verbindingsreeks toevoegen

U kunt verbinding maken met het Azure-opslagaccount of het Azure Cosmos DB for Table-account. Haal de verbindingsreeks op voor het soort account dat u gebruikt.

Een Azure Storage-verbindingsreeks toevoegen

Een Azure Tables-client kan een opslag-verbindingsreeks gebruiken om eindpunten en referenties op te slaan voor toegang tot gegevensbeheerservices. Wanneer u in een client-app wordt uitgevoerd, moet u de Storage-verbindingsreeks in de volgende indeling opgeven met behulp van de naam van uw opslagaccount en de primaire toegangssleutel voor het opslagaccount dat wordt vermeld in Azure Portal voor de waarden AccountName en AccountKey.

In dit voorbeeld ziet u hoe u een statisch veld kunt declareren voor het opslaan van de verbindingstekenreeks:

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

Een Azure Cosmos DB voor Table-verbindingsreeks toevoegen

Een Azure Cosmos DB-account gebruikt een verbindingstekenreeks voor het opslaan van de tabeleindpunt en uw referenties. Wanneer u een client-app uitvoert, moet u de Azure Cosmos DB-verbindingsreeks in de volgende indeling opgeven met behulp van de naam van uw Azure Cosmos DB-account en de primaire toegangssleutel voor het account dat wordt vermeld in Azure Portal voor de waarden AccountName en AccountKey.

In dit voorbeeld ziet u hoe u een statisch veld kunt declareren voor het opslaan van de Azure Cosmos DB-verbindingstekenreeks:

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

In een app die wordt uitgevoerd binnen een rol in Azure, kunt u deze tekenreeks opslaan in het serviceconfiguratiebestand ServiceConfiguration.cscfg. U kunt deze openen met een aanroep naar de System.getenv methode. Hier volgt een voorbeeld van het ophalen van de verbindingsreeks van een instellingselement met de naam Verbinding maken ionString in het serviceconfiguratiebestand:

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

U kunt uw verbindingstekenreeks ook opslaan in het bestand config.properties van uw project:

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

In de volgende voorbeelden wordt er van uitgegaan dat u een van deze methoden hebt gebruikt om de opslagverbindingstekenreeks op te halen.

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.

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

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

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

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

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

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

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

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

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

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

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

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

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.