Jak používat klientskou knihovnu Azure Tables pro Javu

PLATÍ PRO: Tabulka

• .NET
• Node.js
• Java
• C++
• PHP
• Přejít

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:

1. Nainstalujte sadu Java Development Kit (JDK).
2. Ve svém předplatném Azure vytvořte účet úložiště Azure nebo účet služby Azure Cosmos DB.
3. 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.
4. Podle pokynů stáhněte a nainstalujte knihovny Azure Storage pro Javu do systému z tohoto úložiště.
5. 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;

Přidání připojovací řetězec

Můžete se buď připojit k účtu úložiště Azure, nebo k účtu služby Azure Cosmos DB for Table. Získejte připojovací řetězec na základě typu účtu, který používáte.

Přidání připojovací řetězec azure Storage

Klient Azure Tables může použít připojovací řetězec úložiště k ukládání koncových bodů a přihlašovacích údajů pro přístup ke službám pro správu dat. Při spuštění v klientské aplikaci musíte zadat připojovací řetězec úložiště v následujícím formátu, a to pomocí názvu účtu úložiště a primárního přístupového klíče pro účet úložiště uvedený na webu Azure Portal pro hodnoty AccountName a AccountKey.

Tento příklad ukazuje deklaraci statického pole pro uložení připojovacího řetězce:

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

Přidání služby Azure Cosmos DB pro připojovací řetězec tabulky

Účet služby Azure Cosmos DB používá připojovací řetězec k uložení koncového bodu tabulky a vašich přihlašovacích údajů. Při spuštění v klientské aplikaci musíte zadat připojovací řetězec Azure Cosmos DB v následujícím formátu, a to pomocí názvu účtu Azure Cosmos DB a primárního přístupového klíče pro účet uvedený na webu Azure Portal pro hodnoty AccountName a AccountKey.

Tento příklad ukazuje deklaraci statického pole pro uložení připojovacího řetězce služby Azure Cosmos DB:

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

V aplikaci spuštěné v rámci role v Azure můžete tento řetězec uložit do konfiguračního souboru služby ServiceConfiguration.cscfg. Můžete k němu přistupovat voláním System.getenv metody. Tady je příklad získání připojovací řetězec z elementu Setting s názvem Připojení ionString v konfiguračním souboru služby:

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

Připojovací řetězec můžete uložit také do souboru config.properties vašeho projektu:

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

V následujících ukázkách se předpokládá, že jste pomocí některé z těchto metod získali připojovací řetězec úložiště.

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.

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

Výpis tabulek

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

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

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

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

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

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

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

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

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

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

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

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

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ě.