Az Azure Tables Java-ügyfélkódtárának használata

A KÖVETKEZŐKRE VONATKOZIK: Táblázat

• .NET
• Node.js
• Java
• C++
• PHP
• Ugrás

Tipp.

A cikk tartalma az Azure Table Storage-ra és az Azure Cosmos DB for Tablere vonatkozik. A Table API egy prémium szintű ajánlat a table storage számára, amely átviteli sebességre optimalizált táblákat, globális eloszlást és automatikus másodlagos indexeket kínál.

Ez a cikk bemutatja, hogyan hozhat létre táblákat, tárolhatja az adatokat, és hogyan hajthat végre CRUD-műveleteket az említett adatokon. A minták Java nyelven vannak megírva, és az Azure Tables Java-ügyfélkódtárát használják. Az ismertetett forgatókönyvek a táblák létrehozásával, listázásával és törlésével, valamint a táblákban szereplő entitások beszúrásával, lekérdezésével, módosításával és törlésével foglalkoznak. A táblákkal kapcsolatos további információkért lásd a További lépések szakaszt.

Fontos

A Table Storage-t és az Azure Cosmos DB Tableet támogató Azure Tables ügyfélkódtár utolsó verziója a 12+.

Azure-szolgáltatásfiók létrehozása

A táblákat az Azure Table Storage vagy az Azure Cosmos DB használatával használhatja. Ha többet szeretne megtudni a táblaajánlatok közötti különbségekről ebben a két szolgáltatásban, tekintse meg az API for Table áttekintését. Az Ön által kiválasztott szolgáltatás használatához hozzon létre egy fiókot. Az alábbi szakaszok bemutatják, hogyan hozható létre az Azure Table Storage és az Azure Cosmos DB-fiók is, de csak az egyiket használhatja.

Azure Storage-fiók létrehozása

Az Azure Storage-fiók létrehozásának legegyszerűbb módja az Azure Portal használata. További tudnivalókért lásd: Create a storage account (Tárfiók létrehozása).

Ezenkívül az Azure PowerShell vagy az Azure CLI használatával is létrehozhat egy Azure-tárfiókot.

Ha jelenleg nem szeretne tárfiókot létrehozni, az Azure Storage Emulator használatával helyi környezetben is futtathatja és tesztelheti a kódot. További információ: Az Azure Storage Emulator használata fejlesztéshez és teszteléshez.

Azure Cosmos DB-fiók létrehozása

Az Azure Cosmos DB táblafiókhoz való létrehozásával kapcsolatos utasításokért lásd : Adatbázisfiók létrehozása.

Java-alkalmazás létrehozása

A cikkben szereplő minták használata:

1. Telepítse a Java Fejlesztői Készletet (JDK).
2. Azure-tárfiók vagy Azure Cosmos DB-fiók létrehozása az Azure-előfizetésben.
3. Ellenőrizze, hogy a fejlesztői rendszer megfelel-e a GitHubOn található Azure Tables ügyfélkódtárban felsorolt minimális követelményeknek és függőségeknek.
4. Az utasításokat követve töltse le és telepítse a Java Azure Storage-kódtárakat a rendszerre az adattárból.
5. Hozzon létre egy Java-alkalmazást, amely a jelen cikkben szereplő példákat használja.

Az alkalmazás konfigurálása a Table Storage eléréséhez

Adja hozzá a következő bejegyzést a pom.xml fájl szakaszához dependencies :

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

Ezután adja hozzá a következő import utasításokat a Java-fájl elejéhez, ahol Azure Tables API-kat szeretne használni a táblák eléréséhez:

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

A kapcsolati sztring hozzáadása

Csatlakozhat az Azure Storage-fiókhoz vagy az Azure Cosmos DB táblafiókhoz. Kérje le a kapcsolati sztring a használt fiók típusa alapján.

Azure Storage-kapcsolati sztring hozzáadása

Az Azure Tables-ügyfél tárolási kapcsolati sztring használhat végpontok és hitelesítő adatok tárolására az adatkezelési szolgáltatások eléréséhez. Ügyfélalkalmazásban való futtatáskor a Következő formátumban kell megadnia a Storage-kapcsolati sztring a Storage-fiók nevének és az Azure Portalon felsorolt Tárfiók elsődleges hozzáférési kulcsának használatával az AccountName és AccountKey értékekhez.

Ez a példa bemutatja, hogyan deklarálhat statikus mezőt a kapcsolati sztring tárolására:

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

Azure Cosmos DB hozzáadása tábla kapcsolati sztring

Az Azure Cosmos DB-fiókok kapcsolati sztringet használnak a táblavégpontok és a hitelesítő adatok tárolásához. Ügyfélalkalmazásban való futtatáskor az Azure Cosmos DB kapcsolati sztring a következő formátumban kell megadnia az Azure Cosmos DB-fiók nevével és az Azure Portalon felsorolt fiók elsődleges hozzáférési kulcsával az AccountName és AccountKey értékekhez.

Ez a példa bemutatja, hogyan deklarálhat statikus mezőt az Azure Cosmos DB kapcsolati sztring tárolására:

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

Az Azure-ban egy szerepkörön belül futó alkalmazásban ezt a sztringet a ServiceConfiguration.cscfg szolgáltatáskonfigurációs fájlban tárolhatja. A metódus hívásával System.getenv is elérheti. Íme egy példa a kapcsolati sztring lekérésére egy Csatlakozás ionString nevű beállításelemből a szolgáltatáskonfigurációs fájlban:

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

A kapcsolati sztringet a projekt config.properties fájljában is tárolhatja:

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

Az alábbi minták azt feltételezik, hogy a tárolási kapcsolati sztringet ezen két metódus egyikével kérte le.

Tábla létrehozása

Az TableServiceClient objektumok lehetővé teszik a Táblák szolgáltatással való interakciót táblák létrehozása, listázása és törlése érdekében. Az alábbi kód létrehoz egy TableServiceClient objektumot, és egy új TableClient objektum létrehozására használja, amely egy táblát Employeesjelöl.

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

A táblák listázása

A táblák listájának lekéréséhez hívja meg a metódust a TableServiceClient.listTables táblázatnevek iteráló listájának lekéréséhez.

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

Entitás hozzáadása a táblához

Az alábbi kód létrehoz egy új példányt az TableEntity osztályból, amely néhány ügyféladatot tárol. A kód meghívja az upsertEntity objektum metódusát TableClient . Ez a módszer vagy beszúrja az új ügyfélentitást a Employees táblába, vagy lecseréli az entitást, ha már létezik.

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

Entitásköteg beszúrása

Egyetlen írási művelettel egy teljes entitásköteget is beszúrhat a Table Service-be. Az alábbi kód létrehoz egy List<TableTransactionAction> objektumot, majd hozzáad három upsert műveletet. A rendszer minden műveletet új TableEntity objektum létrehozásával, tulajdonságainak beállításával, majd a submitTransaction metódus meghívásával ad hozzá az TableClient objektumhoz.

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

Kötegelt műveletek esetében ügyeljen a következőkre:

• Akár 100 beszúrás, törlés, egyesítés, csere, beszúrás-vagy-egyesítés és beszúrás-vagy-csere műveletet is végrehajthat, bármilyen kombinációban, egyetlen kötegben.
• A kötegművelet rendelkezhet lekérési művelettel, ha ez a kötegben található egyetlen művelet.
• Egy adott kötegművelet összes entitásának ugyanazzal a partíciókulccsal kell rendelkeznie.
• A kötegműveletek 4 MB nagyságú hasznos adatra vannak korlátozva.

Egy partíció összes entitásának lekérése

Ha egy partíció entitásainak tábláit szeretné lekérdezni, használhat egy ListEntitiesOptions. Hívás ListEntitiesOptions.setFilter egy adott táblán lévő lekérdezés létrehozásához, amely egy megadott eredménytípust ad vissza. Az alábbi kód egy szűrőt ad meg azoknak az entitásoknak, ahol Sales a partíciókulcs található. Amikor a lekérdezést egy, az TableClient objektumra irányuló listEntities hívással hajtja végre, az a következőt IteratorTableEntityadja vissza: . Ezután használhatja a Iterator visszaadott "ForEach" ciklust az eredmények felhasználásához. A kód megjeleníti a konzolon a lekérdezés eredményei között szereplő entitásokhoz tartozó mezőket.

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

Partíció entitástartományának lekérése

Ha nem szeretné lekérdezni egy partíció összes entitását, adjon meg egy tartományt egy szűrő összehasonlító operátorainak használatával. Az alábbi kód két szűrőt egyesít a partíció Sales összes entitásának lekéréséhez a "0001" és a "0004" közötti sorkulccsal. Ezután kinyomtatja a lekérdezés eredményeit. Ha az útmutató köteg beszúrási szakaszában a táblához hozzáadott entitásokat használja, ezúttal csak két entitás lesz visszaadva (Ben és 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();
}

Egyetlen entitás lekérdezése

Írhat egy lekérdezést egy adott entitás lekérdezéséhez. A következő kód meghívja TableClient.getEntity a partíciókulcsot és a sorkulcs paramétereit a "Jeff Smith" alkalmazott entitásának lekéréséhez ahelyett, hogy szűrőket hoz létre ListEntitiesOptions , és ugyanezt tenné. A lekérési művelet a végrehajtásakor egy gyűjtemény helyett csak egyetlen entitást ad vissza. Az null érték akkor lesz visszaadva, ha egyetlen entitás sem rendelkezik pontos partícióval és sorkulcs-egyezéssel. Ha egyetlen entitást szeretne lekérdezni a Table szolgáltatásból, ennek leggyorsabb módja a partíció- és sorkulcsok megadása a lekérdezésben.

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

Entitás módosítása

Ha módosítani szeretne egy entitást, kérje le a Table Service-ből, módosítsa az entitásobjektumot, majd egy csere vagy egyesítés művelettel mentse a módosításokat a Table Service-be. A következő kód egy meglévő ügyfél telefonszámát módosítja. Ahelyett, hogy a beszúrni kívánt hívásokat hívnánk tableClient.upsertEntity , ez a kód hív 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();
}

Az entitástulajdonságok egy részének lekérdezése

Egy táblalekérdezéssel egy entitásnak csak bizonyos tulajdonságait is lekérdezheti. Ez a leképezésnek hívott technika csökkenti a sávszélesség felhasználását, és javíthatja a lekérdezési teljesítményt, főleg a nagy entitások esetén. Az alábbi kódban szereplő lekérdezés a ListEntitiesOptions.setSelect metódus használatával csak a tábla entitásainak e-mail-címét adja vissza.

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

Entitás beszúrása vagy cseréje

Gyakran előfordulhat, hogy egy entitást anélkül szeretne hozzáadni egy táblához, hogy tudná, az létezik-e már a táblában. A beszúrási vagy csereműveletekkel egyetlen kérést kezdeményezhet. Ez a kérés vagy beszúrja az entitást, ha nem létezik, vagy lecseréli a meglévőt, ha igen. A korábbi példák alapján az alábbi kód beszúrja vagy lecseréli „Walter Harp” entitását. Új entitás létrehozása után ez a kód meghívja a metódust 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();
}

Entitás törlése

Az entitások törléséhez adja meg a partíciókulcsot és a sorkulcsot.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();
}

Tábla törlése

Végül a következő kód töröl egy táblát egy fiókból. A táblák törlése után körülbelül 40 másodperccel nem lehet újból létrehozni.

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

Tipp.

Az Azure Storage kódmintatár megtekintése

Letölthető és futtatható, könnyen használható teljes körű Azure Storage-kódmintákért tekintse meg az Azure Storage-minták listáját.

Következő lépések

• Bevezetés az Azure Table Service használatába Javában
• A Microsoft Azure Storage Explorer egy ingyenes, önálló alkalmazás, amelynek segítségével vizuálisan dolgozhat Azure Storage-adatokkal Windows, macOS és Linux rendszereken.
• Azure Tables ügyfélkódtár Java-hoz
• Az Azure Tables ügyféloldali kódtárának referenciája
• Azure Tables REST API
• Azure Tables Team Blog

További információ: Azure Java-fejlesztőknek.