Jak používat klientskou knihovnu Azure Tables pro Javu

Článek
10/16/2024

PLATÍ PRO: Stůl

Tip

Obsah v tomto článku se týká služby Azure Table Storage a Azure Cosmos DB for Table. Rozhraní API pro tabulku je prémiová nabídka pro úložiště tabulek, která nabízí tabulky optimalizované pro propustnost, globální distribuci a automatické sekundární indexy.

V tomto článku se dozvíte, jak vytvářet tabulky, ukládat data a provádět operace CRUD na uvedených datech. Ukázky jsou napsané v Javě a používají klientskou knihovnu Azure Tables pro Javu. Popsané scénáře zahrnují vytváření, výpis a odstraňování tabulek a také vkládání, dotazování, úpravy a odstraňování entit v tabulce. Další informace o tabulkách najdete v části Další kroky.

Důležité

Poslední verze klientské knihovny Azure Tables podporující Table Storage a tabulky Azure Cosmos DB je 12 a novější.

Vytvoření účtu služby Azure

S tabulkami můžete pracovat pomocí služby Azure Table Storage nebo Azure Cosmos DB. Další informace o rozdílech mezi nabídkami tabulek v těchto dvou službách najdete v přehledu rozhraní API pro tabulky. U služby, kterou budete používat, si budete muset vytvořit účet. Následující části ukazují, jak vytvořit úložiště Azure Table Storage i účet služby Azure Cosmos DB, ale můžete použít jenom jednu z nich.

Vytvoření účtu úložiště Azure

Nejjednodušší způsob, jak vytvořit účet úložiště Azure, je použití webu Azure Portal. Další informace naleznete v tématu Vytvoření účtu úložiště

Účet úložiště Azure můžete vytvořit také pomocí Azure PowerShellu nebo Azure CLI.

Pokud v tuto chvíli nechcete vytvořit účet úložiště, můžete také pomocí emulátoru úložiště Azure spustit a otestovat kód v místním prostředí. Další informace najdete v tématu Použití emulátoru úložiště Azure pro vývoj a testování.

Vytvoření účtu služby Azure Cosmos DB

Pokyny k vytvoření účtu tabulky služby Azure Cosmos DB najdete v tématu Vytvoření databázového účtu.

Vytvoření aplikace Java

Použití ukázek v tomto článku:

Nainstalujte sadu Java Development Kit (JDK).
Ve svém předplatném Azure vytvořte účet úložiště Azure nebo účet služby Azure Cosmos DB.
Ověřte, že váš vývojový systém splňuje minimální požadavky a závislosti uvedené v klientské knihovně Azure Tables pro úložiště Java na GitHubu.
Podle pokynů stáhněte a nainstalujte knihovny Azure Storage pro Javu do systému z tohoto úložiště.
Vytvořte aplikaci v Javě, která používá příklady v tomto článku.

Konfigurace aplikace pro přístup ke službě Table Storage

Do oddílu dependencies souboru pom.xml přidejte následující položku:

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

Pak do horní části souboru Java přidejte následující import příkazy, ve kterých chcete pro přístup k tabulkám používat rozhraní API tabulek Azure:

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

Vytvoření tabulky

Objekt TableServiceClient umožňuje interakci se službou Tables, abyste mohli vytvářet, vypisovat a odstraňovat tabulky. Následující kód vytvoří TableServiceClient objekt a použije ho k vytvoření nového TableClient objektu, který představuje tabulku s názvem Employees. Objekt TableServiceClient je vytvořen pomocí přihlašovacích údajů typu TokenCredential. Třída DefaultAzureCredential vytvoří zřetězený přihlašovací údaje tokenu, které fungují pro většinu aplikací, které používají sadu Azure SDK, tím, že vyzkouší více typů přihlašovacích údajů. Další informace najdete na webu 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();
}

Výpis tabulek

Pokud chcete získat seznam tabulek, zavolejte metodu TableServiceClient.listTables , která načte iterable seznam názvů tabulek.

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

Přidání entity do tabulky

Následující kód vytvoří novou instanci TableEntity třídy s některými zákaznickými daty, která se mají uložit. Kód volá metodu upsertEntity objektu TableClient . Tato metoda buď vloží novou entitu zákazníka do Employees tabulky, nebo nahradí entitu, pokud už existuje.

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

Vložení dávky entit

V rámci jedné operace zápisu můžete do služby Table Storage vložit dávku entit. Následující kód vytvoří List<TableTransactionAction> objekt a pak do něj přidá tři operace upsertu. Každá operace se přidá vytvořením nového TableEntity objektu, nastavením jeho vlastností a následným voláním submitTransaction metody na objektu 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();
}

O dávkových operacích byste měli vědět několik věcí:

V jedné dávce můžete provést jakoukoli kombinaci až 100 operací vložení, odstranění, sloučení, nahrazení, vložení nebo sloučení a vložení nebo nahrazení.
Dávková operace může obsahovat operaci načtení, pokud se jedná o jedinou operaci v dávce.
Všechny entity v jedné dávkové operaci musí mít stejný klíč oddílu.
Velikost datové části dávkové operace je omezená na 4 MB.

Načtení všech entit v oddílu

K dotazování tabulky pro entity v oddílu můžete použít .ListEntitiesOptions Volání ListEntitiesOptions.setFilter pro vytvoření dotazu na konkrétní tabulku, která vrací zadaný typ výsledku. Následující kód určuje filtr entit, ve kterých Sales je klíč oddílu. Když se dotaz spustí s voláním listEntities objektu TableClient , vrátí hodnotu Iterator TableEntity. Výsledky pak můžete využít pomocí Iterator vrácené smyčky ForEach. Tento kód v konzole zobrazí pole každé entity z výsledků dotazu.

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

Načtení rozsahu entit v oddílu

Pokud nechcete dotazovat všechny entity v oddílu, zadejte rozsah pomocí relačních operátorů ve filtru. Následující kód kombinuje dva filtry pro získání všech entit v oddílu Sales s klíčem řádku mezi 0001 a 0004. Pak zobrazí výsledky dotazu. Pokud použijete entity přidané do tabulky v části Dávkové vložení tohoto průvodce, vrátí se tentokrát jenom dvě entity (Ben a 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();
}

Načtení jedné entity

Můžete napsat dotaz pro načtení jedné konkrétní entity. Následující volání TableClient.getEntity kódu s parametry klíče oddílu a klíče řádku k načtení entity pro zaměstnance Jeff Smith místo vytvoření ListEntitiesOptions a použití filtrů k provedení stejné věci. Po spuštění operace načtení vrátí místo kolekce pouze jednu entitu. Pokud null žádná entita nemá přesnou shodu klíče oddílu a řádku, vrátí se hodnota. Určení jak klíčů oddílu, tak klíčů řádků v dotazu představuje nejrychlejší způsob, jak načíst jednu entitu ze služby Table service.

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

Úprava entity

Pokud chcete entitu upravit, načtěte ji ze služby Table Storage, proveďte změny objektu entity a uložte změny zpět do služby Table Storage pomocí operace nahrazení nebo sloučení. Následující kód změní telefonní číslo stávajícího zákazníka. Místo volání tableClient.upsertEntity tak, jak jsme to udělali, tento kód volá 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();
}

Dotaz na podmnožinu vlastností entity

Dotaz na tabulku dokáže z entity načíst pouze několik vlastností. Tato technika, označovaná jako projekce, snižuje šířku pásma a může zlepšit výkon dotazů, zejména u velkých entit. Dotaz v následujícím kódu používá metodu ListEntitiesOptions.setSelect k vrácení pouze e-mailových adres entit v tabulce.

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

Vložení nebo nahrazení entity

Často chcete do tabulky přidat entitu, aniž byste věděli, jestli v ní již neexistuje. Operace vložení nebo nahrazení umožňuje vytvořit jeden požadavek. Tento požadavek buď vloží entitu, pokud neexistuje, nebo nahradí existující entitu, pokud ano. Následující kód staví na předchozích příkladech a vloží nebo nahradí entitu Walter Harp. Po vytvoření nové entity tento kód volá metodu 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();
}

Odstranění entity

Entitu můžete odstranit zadáním klíče oddílu a klíče řádku prostřednictvím 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();
}

Odstraní tabulku

Následující kód nakonec odstraní tabulku z účtu. Přibližně 40 sekund po odstranění tabulky ji nemůžete znovu vytvořit.

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

Projděte si úložiště s ukázkami kódu pro Azure Storage

Snadno použitelné a úplné ukázky kódu pro Azure Storage, které si můžete stáhnout a použít, jsou shrnuté v seznamu ukázky pro Azure Storage.

Další kroky

Začínáme se službou Azure Table Storage v Javě
Microsoft Azure Storage Explorer je bezplatná samostatná aplikace od Microsoftu, která umožňuje vizuálně pracovat s daty Azure Storage ve Windows, macOS a Linuxu.
Klientská knihovna Azure Tables pro Javu
Referenční informace ke klientské knihovně Azure Tables
Rozhraní REST API pro tabulky Azure
Týmový blog o tabulkách Azure

Další informace najdete na webu Azure pro vývojáře v Javě.

Sdílet prostřednictvím