Jak używać biblioteki klienta tabel platformy Azure dla języka Java

DOTYCZY: Tabeli

• .NET
• Node.js
• Java
• C++
• PHP
• Przejdź

Napiwek

Zawartość tego artykułu dotyczy usług Azure Table Storage i Azure Cosmos DB for Table. Interfejs API dla tabel to oferta premium dla magazynu tabel, która oferuje tabele zoptymalizowane pod kątem przepływności, dystrybucję globalną i automatyczne indeksy pomocnicze.

W tym artykule pokazano, jak tworzyć tabele, przechowywać dane i wykonywać operacje CRUD na tych danych. Przykłady są napisane w języku Java i korzystają z biblioteki klienta tabel platformy Azure dla języka Java. Omówiono scenariusze tworzenia, wyświetlania listy i usuwania tabel, a także wstawiania jednostek w tabeli i wykonywania na nich zapytań oraz modyfikowania i usuwania jednostek w tabeli. Aby uzyskać więcej informacji na temat tabel, zobacz sekcję Następne kroki.

Ważne

Ostatnia wersja biblioteki klienta tabel platformy Azure obsługująca usługę Table Storage i tabelę usługi Azure Cosmos DB to 12+.

Tworzenie konta usługi Azure

Możesz pracować z tabelami przy użyciu usługi Azure Table Storage lub usługi Azure Cosmos DB. Aby dowiedzieć się więcej o różnicach między ofertami tabel w tych dwóch usługach, zobacz omówienie interfejsu API dla tabel. Aby móc korzystać z wybranej usługi, musisz w niej utworzyć konto. W poniższych sekcjach pokazano, jak utworzyć zarówno usługę Azure Table Storage, jak i konto usługi Azure Cosmos DB, jednak możesz po prostu użyć jednego z nich.

Tworzenie konta usługi Azure Storage

Najprostszym sposobem utworzenia konta usługi Azure Storage jest użycie witryny Azure Portal. Więcej informacji można znaleźć w temacie Tworzenie konta magazynu.

Możesz utworzyć konto usługi Azure Storage przy użyciu programu Azure PowerShell lub interfejsu wiersza polecenia platformy Azure.

Jeśli w tej chwili nie chcesz tworzyć konta magazynu, możesz również użyć emulatora usługi Azure Storage do uruchomienia i przetestowania kodu w środowisku lokalnym. Aby uzyskać więcej informacji, zobacz Use the Azure Storage Emulator for development and testing (Używanie emulatora usługi Azure Storage do programowania i testowania).

Tworzenie konta usługi Azure Cosmos DB

Aby uzyskać instrukcje dotyczące tworzenia konta usługi Azure Cosmos DB dla tabel, zobacz Tworzenie konta bazy danych.

Tworzenie aplikacji Java

Aby użyć przykładów w tym artykule:

1. Zainstaluj zestaw Java Development Kit (JDK).
2. Utwórz konto usługi Azure Storage lub konto usługi Azure Cosmos DB w ramach subskrypcji platformy Azure.
3. Sprawdź, czy system deweloperski spełnia minimalne wymagania i zależności wymienione w bibliotece klienta tabel platformy Azure dla repozytorium Java w usłudze GitHub.
4. Postępuj zgodnie z instrukcjami, aby pobrać i zainstalować biblioteki usługi Azure Storage dla języka Java w systemie z tego repozytorium.
5. Utwórz aplikację Java, która używa przykładów w tym artykule.

Konfigurowanie aplikacji w celu uzyskania dostępu do usługi Table Storage

Dodaj następujący wpis do sekcji pliku dependencies pom.xml:

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

Następnie dodaj następujące import instrukcje na początku pliku Java, w którym chcesz uzyskać dostęp do tabel przy użyciu interfejsów API tabel platformy 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;

Dodawanie parametry połączenia

Możesz nawiązać połączenie z kontem usługi Azure Storage lub kontem usługi Azure Cosmos DB dla tabeli. Pobierz parametry połączenia na podstawie typu używanego konta.

Dodawanie parametry połączenia usługi Azure Storage

Klient tabel platformy Azure może używać parametry połączenia magazynu do przechowywania punktów końcowych i poświadczeń na potrzeby uzyskiwania dostępu do usług zarządzania danymi. W przypadku uruchamiania w aplikacji klienckiej należy podać parametry połączenia usługi Storage w następującym formacie, używając nazwy konta magazynu i podstawowego klucza dostępu dla konta magazynu wymienionego w witrynie Azure Portal dla wartości AccountName i AccountKey.

W tym przykładzie pokazano, jak można zadeklarować pole statyczne w celu przechowywania parametrów połączenia:

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

Dodawanie usługi Azure Cosmos DB dla parametry połączenia tabel

Na koncie usługi Azure Cosmos DB punkt końcowy tabeli i Twoje poświadczenia są przechowywane w parametrach połączenia. W przypadku uruchamiania w aplikacji klienckiej należy podać parametry połączenia usługi Azure Cosmos DB w następującym formacie, używając nazwy konta usługi Azure Cosmos DB i podstawowego klucza dostępu dla konta wymienionego w witrynie Azure Portal dla wartości AccountName i AccountKey.

W tym przykładzie pokazano, jak można zadeklarować pole statyczne w celu przechowywania parametrów połączenia usługi Azure Cosmos DB:

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

W aplikacji działającej w ramach roli na platformie Azure można przechowywać ten ciąg w pliku konfiguracji usługi ServiceConfiguration.cscfg. Dostęp do niego można uzyskać za pomocą wywołania System.getenv metody . Oto przykład pobierania parametry połączenia z elementu Setting o nazwie Połączenie ionString w pliku konfiguracji usługi:

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

Można również przechowywać parametry połączenia w pliku config.properties w projekcie:

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

W poniższych przykładach założono, że uzyskano parametry połączenia za pomocą jednej z tych metod.

Utwórz tabelę

Obiekt TableServiceClient umożliwia interakcję z usługą Tables w celu tworzenia, wyświetlania listy i usuwania tabel. Poniższy kod tworzy TableServiceClient obiekt i używa go do utworzenia nowego TableClient obiektu, który reprezentuje tabelę o nazwie 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();
}

Wyświetlanie listy tabel

Aby uzyskać listę tabel, wywołaj TableServiceClient.listTables metodę w celu pobrania iterowalnej listy nazw tabel.

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

Dodawanie jednostki do tabeli

Poniższy kod tworzy nowe wystąpienie TableEntity klasy z danymi klienta, które mają być przechowywane. Kod wywołuje metodę upsertEntityTableClient w obiekcie . Ta metoda wstawia nową jednostkę klienta do Employees tabeli lub zastępuje jednostkę, jeśli już istnieje.

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

Zbiorcze wstawianie jednostek

Możesz wstawić partię jednostek do usługi tabel w ramach jednej operacji zapisu. Poniższy kod tworzy List<TableTransactionAction> obiekt, a następnie dodaje do niego trzy operacje upsert. Każda operacja jest dodawana przez utworzenie nowego TableEntity obiektu, ustawienie jego właściwości, a następnie wywołanie submitTransaction metody w TableClient obiekcie.

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

Kilka uwag dotyczących operacji zbiorczych:

• W ramach jednej partii można wykonać maksymalnie 100 operacji wstawiania, usuwania, łączenia, zastępowania, wstawiania lub łączenia i wstawiania lub zastępowania — w dowolnej kombinacji.
• Operacja zbiorcza może zawierać operację pobierania, o ile jest to jedyna operacja w partii.
• Wszystkie jednostki w jednej operacji zbiorczej muszą mieć ten sam klucz partycji.
• Maksymalny rozmiar ładunku danych operacji zbiorczej to 4 MB.

Pobieranie wszystkich jednostek w partycji

Aby wykonać zapytanie dotyczące tabeli dla jednostek w partycji, możesz użyć elementu ListEntitiesOptions. Wywołaj ListEntitiesOptions.setFilter metodę , aby utworzyć zapytanie w określonej tabeli zwracającej określony typ wyniku. Poniższy kod określa filtr dla jednostek, w których Sales jest klucz partycji. Gdy zapytanie jest wykonywane z wywołaniem obiektu listEntitiesTableClient , zwraca wartość typu IteratorTableEntity. Następnie możesz użyć Iterator zwracanego w pętli "ForEach", aby wykorzystać wyniki. Ten kod drukuje pola każdej jednostki w wynikach zapytania w konsoli.

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

Pobieranie zakresu jednostek w partycji

Jeśli nie chcesz wykonywać zapytań dotyczących wszystkich jednostek w partycji, określ zakres przy użyciu operatorów porównania w filtrze. Poniższy kod łączy dwa filtry, aby uzyskać wszystkie jednostki w partycji Sales z kluczem wiersza z zakresu od "0001" do "0004". Następnie drukuje wyniki zapytania. Jeśli używasz jednostek dodanych do tabeli w sekcji wstawiania wsadowego tego przewodnika, tym razem zostaną zwrócone tylko dwie jednostki (Ben i 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();
}

Pobieranie pojedynczej jednostki

Można napisać zapytanie do pobrania jednej, określonej jednostki. Poniższe wywołania TableClient.getEntity kodu z kluczem partycji i parametrami klucza wiersza w celu pobrania jednostki dla pracownika "Jeff Smith", zamiast tworzyć ListEntitiesOptions filtry i używać ich do wykonywania tych samych czynności. Po wykonaniu tego kodu operacja pobierania zwróci tylko jedną jednostkę, a nie zbiór jednostek. Wartość jest zwracana, jeśli żadna null jednostka nie ma dokładnego dopasowania partycji i klucza wiersza. Określenie kluczy partycji i wiersza w pojedynczym zapytaniu jest najszybszym sposobem na pobranie jednej jednostki z usługi tabel.

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

Modyfikowanie jednostki

Aby zmodyfikować jednostkę, pobierz ją z usługi tabel, wprowadź zmiany w obiekcie jednostki, a następnie zapisz zmiany w usłudze tabel przy użyciu operacji zastępowania lub łączenia. Poniższy kod zmienia istniejący numer telefonu klienta. Zamiast wywoływać metodę tableClient.upsertEntity wstawiania, ten kod wywołuje metodę 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();
}

Tworzenie zapytania do podzbioru właściwości jednostki

Za pomocą zapytania wykonywanego względem tabeli można pobrać tylko kilka właściwości z jednostki. Ta technika, zwana projekcją, redukuje przepustowość i może poprawiać wydajność zapytań, zwłaszcza w przypadku dużych jednostek. Zapytanie w poniższym kodzie używa ListEntitiesOptions.setSelect metody , aby zwrócić tylko adresy e-mail jednostek w tabeli.

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

Wstawianie lub zastępowanie jednostki

Często zdarza się, że chcesz dodać jednostkę do tabeli, ale nie wiesz, czy taka jednostka już istnieje. Operacja wstawiania lub zastępowania umożliwia wykonanie pojedynczego żądania. To żądanie wstawi jednostkę, jeśli nie istnieje lub zastąpi istniejącą, jeśli tak się stanie. Poniższy kod, oparty na poprzednich przykładach, wstawia lub zastępuje jednostkę „Walter Harp”. Po utworzeniu nowej jednostki ten kod wywołuje metodę 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();
}

Usuwanie encji

Jednostkę można usunąć, podając klucz partycji i klucz wiersza za pomocą polecenia 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();
}

Usuń tabelę

Na koniec poniższy kod usuwa tabelę z konta. Około 40 sekund po usunięciu tabeli nie można jej odtworzyć.

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

Napiwek

Zapoznaj się z repozytorium przykładów kodu usługi Azure Storage

Nasza lista przykładów usługi Azure Storage zawiera łatwe w użyciu kompleksowe przykłady kodu usługi Azure Storage, które można pobierać i uruchamiać.

Następne kroki

• Wprowadzenie do usługi Azure Table Service w języku Java
• Microsoft Azure Storage Explorer jest bezpłatną aplikacją autonomiczną oferowaną przez firmę Microsoft, która umożliwia wizualną pracę z danymi w usłudze Azure Storage w systemach Windows, macOS i Linux.
• Biblioteka klienta tabel platformy Azure dla języka Java
• Dokumentacja biblioteki klienta tabel platformy Azure
• Interfejs API REST tabel platformy Azure
• Blog zespołu tabel platformy Azure

Aby uzyskać więcej informacji, odwiedź stronę Azure dla deweloperów języka Java.