Så här använder du Azure Tables-klientbiblioteket för Java

GÄLLER FÖR: Tabell

Dricks

Innehållet i den här artikeln gäller för Azure Table Storage och Azure Cosmos DB for Table. API för tabell är ett premiumerbjudande för tabelllagring som erbjuder dataflödesoptimerade tabeller, global distribution och automatiska sekundära index.

Den här artikeln visar hur du skapar tabeller, lagrar dina data och utför CRUD-åtgärder på dessa data. Exemplen är skrivna i Java och använder Azure Tables-klientbiblioteket för Java. De scenarier som behandlas beskriver hur du skapar, listar och tar bort tabeller samt hur du infogar, kör frågor mot, modifierar och tar bort poster i en tabell. Mer information om tabeller finns i avsnittet Nästa steg.

Viktigt!

Den senaste versionen av Azure Tables-klientbiblioteket som stöder Table Storage och Azure Cosmos DB Table är 12+.

Skapa ett Azure-tjänstkonto

Du kan arbeta med tabeller med hjälp av Azure Table Storage eller Azure Cosmos DB. Mer information om skillnaderna mellan tabellerbjudanden i dessa två tjänster finns i API:et för tabellöversikt. Du måste skapa ett konto för den tjänst som du ska använda. Följande avsnitt visar hur du skapar både Azure Table Storage och Azure Cosmos DB-kontot, men du kan bara använda en av dem.

Skapa ett Azure Storage-konto

Det enklaste sättet att skapa ett Azure-lagringskonto är att använda Azure-portalen. För mer information, se Skapa ett lagringskonto.

Du kan även skapa ett Azure-lagringskonto med hjälp av Azure PowerShell eller Azure CLI.

Om du föredrar att inte skapa ett lagringskonto just nu kan du även använda Azure Storage-emulatorn för att köra och testa koden i en lokal miljö. Mer information finns i Använda Azure Storage-emulatorn för utveckling och testning.

Skapa ett Azure Cosmos DB-konto

Anvisningar om hur du skapar ett Azure Cosmos DB för tabellkonto finns i Skapa ett databaskonto.

Skapa ett Java-program

Så här använder du exemplen i den här artikeln:

  1. Installera Java Development Kit (JDK).
  2. Skapa ett Azure Storage-konto eller Ett Azure Cosmos DB-konto i din Azure-prenumeration.
  3. Kontrollera att ditt utvecklingssystem uppfyller minimikraven och beroendena som anges i Azure Tables-klientbiblioteket för Java-lagringsplatsen på GitHub.
  4. Följ anvisningarna för att ladda ned och installera Azure Storage Libraries för Java på ditt system från den lagringsplatsen.
  5. Skapa en Java-app som använder exemplen i den här artikeln.

Konfigurera din app för åtkomst till Table Storage

Lägg till följande post i avsnittet för din pom.xml-fildependencies:

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

Lägg sedan till följande import instruktioner överst i Java-filen där du vill använda Azure Tables-API:er för att komma åt tabeller:

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

Lägg till din anslutningssträng

Du kan antingen ansluta till Azure Storage-kontot eller Azure Cosmos DB för tabellkontot. Hämta anslutningssträng baserat på vilken typ av konto du använder.

Lägga till en Azure Storage-anslutningssträng

En Azure Tables-klient kan använda en lagrings-anslutningssträng för att lagra slutpunkter och autentiseringsuppgifter för åtkomst till datahanteringstjänster. När du kör i en klientapp måste du ange storage-anslutningssträng i följande format, med hjälp av namnet på ditt lagringskonto och den primära åtkomstnyckeln för lagringskontot som anges i Azure-portalen för värdena AccountName och AccountKey.

Det här exemplet visar hur du kan deklarera ett statiskt fält för lagring av anslutningssträngen:

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

Lägga till en Azure Cosmos DB för table anslutningssträng

Ett Azure Cosmos DB-konto använder en anslutningssträng för att lagra tabellslutpunkten och dina autentiseringsuppgifter. När du kör i en klientapp måste du ange Azure Cosmos DB-anslutningssträng i följande format med hjälp av namnet på ditt Azure Cosmos DB-konto och den primära åtkomstnyckeln för kontot som anges i Azure-portalen för värdena AccountName och AccountKey.

Det här exemplet visar hur du kan deklarera ett statiskt fält för lagring av Azure Cosmos DB-anslutningssträngen:

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

I en app som körs inom en roll i Azure kan du lagra den här strängen i tjänstkonfigurationsfilen ServiceConfiguration.cscfg. Du kan komma åt den med ett anrop till System.getenv metoden. Här är ett exempel på hur du hämtar anslutningssträng från ett inställningselement med namnet Anslut ionString i tjänstkonfigurationsfilen:

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

Du kan även lagra anslutningssträngen i projektets config.properties-fil:

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

Följande exempel förutsätter att du har använt någon av dessa metoder för att hämta anslutningssträngen för lagring.

Skapa en tabell

Med ett TableServiceClient objekt kan du interagera med tjänsten Tabeller för att skapa, lista och ta bort tabeller. Följande kod skapar ett TableServiceClient objekt och använder det för att skapa ett nytt TableClient objekt, som representerar en tabell med namnet 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();
}

Lista tabellerna

Om du vill hämta en lista över tabeller anropar TableServiceClient.listTables du metoden för att hämta en iterbar lista med tabellnamn.

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

Lägga till en entitet i en tabell

Följande kod skapar en ny instans av TableEntity klassen med vissa kunddata som ska lagras. Koden anropar upsertEntity -metoden för TableClient objektet. Den metoden infogar antingen den nya kundentiteten i Employees tabellen eller ersätter entiteten om den redan finns.

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

Infoga en batch med entiteter

Du kan skriva en batch med entiteter till Table Service i samma skrivåtgärd. Följande kod skapar ett List<TableTransactionAction> objekt och lägger sedan till tre upsert-åtgärder till det. Varje åtgärd läggs till genom att skapa ett nytt TableEntity objekt, ange dess egenskaper och sedan anropa submitTransaction metoden för TableClient objektet.

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

Några saker att tänka på när du använder batchåtgärder:

  • Du kan utföra upp till 100 insert-, delete-, merge-, replace-, insert-or-merge- samt insert-or-replace-åtgärder i valfri kombination i samma batch.
  • En batchåtgärd kan innehålla en retrieve-åtgärd om det är den enda åtgärden i batchen.
  • Alla entiteter i samma batchåtgärd måste ha samma partitionsnyckel.
  • Batchåtgärder är begränsade till en nyttolast på 4 MB.

Hämta alla entiteter i en partition

Om du vill köra frågor mot en tabell för entiteter i en partition kan du använda en ListEntitiesOptions. Anropa ListEntitiesOptions.setFilter för att skapa en fråga i en viss tabell som returnerar en angiven resultattyp. Följande kod anger ett filter för entiteter där Sales är partitionsnyckeln. När frågan körs med ett anrop till listEntitiesTableClient objektet returneras en Iterator av TableEntity. Du kan sedan använda den Iterator returnerade i en ForEach-loop för att använda resultatet. Med den här koden skrivs fälten för varje entitet i frågeresultatet ut till konsolen.

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

Hämta ett intervall med enheter i en partition

Om du inte vill köra frågor mot alla entiteter i en partition anger du ett intervall med hjälp av jämförelseoperatorer i ett filter. Följande kod kombinerar två filter för att hämta alla entiteter i partitionen Sales med en radnyckel mellan "0001" och "0004". Sedan skrivs frågeresultatet ut. Om du använder entiteterna som läggs till i tabellen i avsnittet batch insert i den här guiden returneras endast två entiteter den här gången (Ben och 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();
}

Hämta en enda entitet

Du kan skriva en fråga för att hämta en enda, specifik entitet. Följande kod anropar TableClient.getEntity med parametrar för partitionsnyckel och radnyckel för att hämta entiteten för medarbetaren "Jeff Smith", i stället för att skapa en ListEntitiesOptions och använda filter för att göra samma sak. Vid exekvering returnerar hämtningsåtgärden endast en entitet i stället för en samling. Ett null värde returneras om ingen entitet har en exakt partitions- och radnyckelmatchning. Det snabbaste sättet att hämta en enskild entitet från tabelltjänsten är att ange både partitions- och radnycklar i en fråga.

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

Ändra en entitet

Om du vill ändra en entitet hämtar du den från Table Storage, ändrar entitetsobjektet och sparar ändringarna till Table Storage igen med en replace- eller en merge-åtgärd. Följande kod ändrar en befintlig kunds telefonnummer. I stället för att anropa tableClient.upsertEntity som vi gjorde för att infoga anropar tableClient.updateEntityden här koden .

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

Fråga en deluppsättning entitetsegenskaper

En fråga till en tabell kan hämta några få egenskaper från en entitet. Den här tekniken, kallad projektion, minskar bandbredden och kan förbättra frågeprestanda, i synnerhet för stora entiteter. Frågan i följande kod använder ListEntitiesOptions.setSelect metoden för att endast returnera e-postadresserna för entiteter i tabellen.

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

Infoga eller ersätta en entitet

Ofta finns det ett behov av att lägga till en entitet i en tabell utan kännedom om huruvida den redan finns i tabellen. Med en insert-or-replace-åtgärd kan du göra en enda begäran. Den begäran infogar antingen entiteten om den inte finns eller ersätter den befintliga om den gör det. Följande kod bygger på föregående exempel och infogar eller ersätter entiteten för ”Walter Harp”. När du har skapat en ny entitet anropar TableClient.upsertEntity den här koden metoden.

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

Ta bort en entitet

Du kan ta bort en entitet genom att ange dess partitionsnyckel och radnyckel 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();
}

Ta bort en tabell

Slutligen tar följande kod bort en tabell från ett konto. Cirka 40 sekunder efter att du har tagit bort en tabell kan du inte återskapa den.

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

Dricks

Ta en titt på databasen med Azure Storage-kodexempel

Lättanvända Azure Storage-kodexempel från slutpunkt till slutpunkt som du kan ladda ned och köra finns i vår lista med Azure Storage-exempel.

Nästa steg

Mer information finns i Azure för Java-utvecklare.