Cara menggunakan pustaka klien Tabel Azure untuk Java

BERLAKU UNTUK: Meja

• .NET
• Node.js
• Java
• C++
• PHP
• Go

Tip

Konten dalam artikel ini berlaku untuk penyimpanan Azure Table dan Azure Cosmos DB for Table. API untuk Tabel adalah penawaran premium untuk penyimpanan tabel yang menawarkan tabel yang dioptimalkan throughput, distribusi global, dan indeks sekunder otomatis.

Artikel ini menunjukkan cara membuat tabel, menyimpan data Anda, dan melakukan operasi CRUD pada data tersebut. Sampel ditulis dalam Java dan menggunakan pustaka klien Tabel Azure untuk Java. Skenario yang dibahas termasuk membuat, mencantumkan, dan menghapus tabel, serta menyisipkan, mengkueri, memodifikasi, dan menghapus entitas dalam tabel. Untuk informasi selengkapnya tentang tabel, lihat bagian Langkah berikutnya.

Penting

Versi terakhir pustaka klien Azure Tables yang mendukung Table Storage dan Azure Cosmos DB Table adalah 12+.

Membuat akun layanan Azure

Anda dapat bekerja dengan tabel menggunakan penyimpanan Azure Table atau Azure Cosmos DB. Untuk mempelajari selengkapnya tentang perbedaan antara penawaran tabel di kedua layanan ini, lihat gambaran umum API untuk Tabel. Anda harus membuat akun untuk layanan yang akan Anda gunakan. Bagian berikut menunjukkan cara membuat penyimpanan Azure Table dan akun Azure Cosmos DB, tetapi Anda bisa menggunakan salah satunya.

Membuat akun Azure Storage

Cara termudah untuk membuat akun penyimpanan Azure adalah dengan menggunakan portal Azure. Untuk mempelajari selengkapnya, lihat Buat akun penyimpanan.

Anda juga bisa membuat akun penyimpanan Azure dengan menggunakan Azure PowerShell atau Azure CLI.

Jika Anda lebih suka tidak membuat akun penyimpanan saat ini, Anda juga dapat menggunakan Azure Storage emulator untuk menjalankan dan menguji kode Anda di lingkungan lokal. Untuk informasi selengkapnya, lihat Menggunakan Azure Storage Emulator untuk pengembangan dan pengujian.

Membuat akun Azure Cosmos DB

Untuk instruksi tentang membuat akun Azure Cosmos DB for Table, lihat Membuat akun database.

Membuat aplikasi Java

Untuk menggunakan sampel dalam artikel ini:

1. Pasang Java Development Kit (JDK).
2. Buat akun penyimpanan Azure atau akun Azure Cosmos DB di langganan Azure Anda.
3. Verifikasi bahwa sistem pengembangan Anda memenuhi persyaratan dan dependensi minimum yang tercantum dalam repositori Pustaka klien Tabel Azure untuk Java di GitHub.
4. Ikuti instruksi untuk mengunduh dan menginstal Pustaka Azure Storage untuk Java di sistem Anda dari repositori itu.
5. Buat aplikasi Java yang menggunakan contoh dalam artikel ini.

Mengonfigurasi aplikasi Anda untuk mengakses Table Storage

Tambahkan entri berikut ke bagian dependencies file pom.xml Anda:

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

Kemudian, tambahkan pernyataan import berikut ke bagian atas file Java tempat Anda ingin menggunakan API Tabel Azure untuk mengakses tabel:

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

Menambahkan string koneksi Anda

Anda dapat menyambungkan ke akun penyimpanan Azure atau akun Azure Cosmos DB for Table. Dapatkan string koneksi berdasarkan tipe akun yang Anda gunakan.

Menambahkan string koneksi Azure Storage

Klien Tabel Azure dapat menggunakan string koneksi penyimpanan untuk menyimpan titik akhir dan info masuk untuk mengakses layanan manajemen data. Saat menjalankan di aplikasi klien, Anda harus memberikan string koneksi Storage dalam format berikut, menggunakan nama akun Penyimpanan Anda dan kunci akses Utama untuk akun Penyimpanan yang tercantum di portal Microsoft Azure untuk nilai AccountName dan AccountKey.

Contoh ini memperlihatkan bagaimana Anda dapat mendeklarasikan bidang statis untuk menahan string koneksi:

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

Menambahkan Azure Cosmos DB for Table string koneksi

Akun Azure Cosmos DB menggunakan string koneksi untuk menyimpan titik akhir tabel dan kredensial Anda. Saat menjalankan di aplikasi klien, Anda harus menyediakan string koneksi Azure Cosmos DB dalam format berikut, menggunakan nama akun Azure Cosmos DB Anda dan kunci akses utama untuk akun yang tercantum di portal Microsoft Azure untuk nilai AccountName dan AccountKey.

Contoh ini memperlihatkan bagaimana Anda dapat mendeklarasikan bidang statis untuk menahan string koneksi Azure Cosmos DB:

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

Dalam aplikasi yang berjalan dalam peran di Azure, Anda dapat menyimpan string ini di file konfigurasi layanan, ServiceConfiguration.cscfg. Anda dapat mengaksesnya dengan panggilan ke metode System.getenv. Berikut ini contoh mendapatkan string koneksi dari elemen Pengaturan bernama ConnectionString dalam file konfigurasi layanan:

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

Anda juga dapat menyimpan string koneksi dalam file config.properties project:

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

Sampel berikut mengasumsikan bahwa Anda telah menggunakan salah satu metode ini untuk mendapatkan string koneksi penyimpanan.

Buat tabel

Objek TableServiceClient memungkinkan Anda berinteraksi dengan layanan Tabel untuk membuat, mencantumkan, dan menghapus tabel. Kode berikut membuat objek TableServiceClient dan menggunakannya untuk membuat objek baru TableClient, yang mewakili tabel bernama 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();
}

Mencantumkan tabel

Untuk mendapatkan daftar tabel, panggil metode TableServiceClient.listTables untuk mengambil daftar nama tabel yang dapat diubah.

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

Menambahkan entitas pada tabel

Kode berikut membuat contoh baru kelas TableEntity dengan beberapa data pelanggan yang akan disimpan. Kode memanggil metode upsertEntity pada objek TableClient. Metode tersebut memasukkan entitas pelanggan baru ke dalam tabel Employees atau mengganti entitas jika sudah ada.

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

Menyisipkan batch entitas

Anda dapat memasukkan batch entitas ke layanan tabel dalam satu operasi penulisan. Kode berikut membuat objek List<TableTransactionAction>, lalu menambahkan tiga operasi upsert ke objek tersebut. Setiap operasi ditambahkan dengan membuat objek TableEntity baru, mengatur propertinya, lalu memanggil metode submitTransaction pada objek 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();
}

Beberapa hal yang perlu diperhatikan pada operasi batch:

• Anda dapat melakukan hingga 100 menyisipkan, menghapus, menggabungkan, mengganti, menyisipkan atau menggabungkan, dan menyisipkan atau mengganti operasi dalam kombinasi apa pun dalam satu batch.
• Operasi batch dapat memiliki operasi mengambil, jika itu adalah satu-satunya operasi dalam batch.
• Semua entitas dalam satu operasi batch harus memiliki kunci partisi yang sama.
• Operasi batch terbatas pada payload data 4-MB.

Mengambil semua entitas dalam partisi

Untuk mengkueri tabel untuk entitas dalam partisi, Anda bisa menggunakan ListEntitiesOptions. Panggilan ListEntitiesOptions.setFilter untuk membuat kueri pada tabel tertentu yang mengembalikan tipe hasil tertentu. Kode berikut menentukan filter untuk entitas di mana Sales adalah kunci partisi. Saat kueri dijalankan dengan panggilan ke listEntities pada objek TableClient, kueri mengembalikan Iterator dari TableEntity. Anda kemudian dapat menggunakan Iterator yang dikembalikan dalam loop "ForEach" untuk mengkonsumsi hasilnya. Kode ini mencetak bidang setiap entitas dalam hasil kueri ke konsol.

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

Mengambil berbagai entitas dalam partisi

Jika Anda tidak ingin membuat kueri semua entitas dalam partisi, tentukan rentang menggunakan operator perbandingan dalam filter. Kode berikut menggabungkan dua filter untuk mendapatkan semua entitas di partisi Sales dengan kunci baris antara '0001' dan '0004'. Lalu mencetak hasil kueri. Jika Anda menggunakan entitas yang ditambahkan ke tabel di bagian penyisipan batch dari panduan ini, hanya dua entitas yang dikembalikan kali ini (Ben dan 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();
}

Mengambil satu entitas

Anda dapat menulis kueri untuk mengambil satu entitas tertentu. Kode berikut memanggil TableClient.getEntity dengan parameter kunci partisi dan kunci baris untuk mengambil entitas untuk karyawan "Jeff Smith", alih-alih membuat ListEntitiesOptions dan menggunakan filter untuk melakukan hal yang sama. Ketika dijalankan, operasi pengambilan hanya mengembalikan satu entitas, bukan koleksi. Nilai null dikembalikan jika tidak ada entitas yang memiliki kecocokan partisi dan kunci baris yang sama persis. Menentukan tombol partisi dan baris dalam kueri adalah cara tercepat untuk mengambil satu entitas dari layanan 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();
}

Mengubah entitas

Untuk memodifikasi entitas, ambil dari layanan tabel, buat perubahan pada objek entitas, dan simpan kembali perubahan ke layanan tabel dengan operasi ganti atau gabungkan. Kode berikut mengubah nomor telepon pelanggan yang sudah ada. Alih-alih memanggil tableClient.upsertEntity seperti yang kita lakukan untuk menyisipkan, kode ini memanggil 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();
}

Mengkueri subset properti entitas

Kueri ke tabel bisa mengambil hanya beberapa properti dari entitas. Teknik ini, yang disebut proyeksi, mengurangi bandwidth dan dapat meningkatkan performa kueri, terutama untuk entitas besar. Kueri dalam kode berikut menggunakan metode ListEntitiesOptions.setSelect untuk mengembalikan hanya alamat email entitas dalam 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();

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

Menyisipkan atau Mengganti entitas

Seringkali Anda ingin menambahkan entitas ke tabel tanpa mengetahui apakah sudah ada dalam tabel. Operasi sisipkan atau ganti memungkinkan Anda membuat satu permintaan. Permintaan itu akan memasukkan entitas jika tidak ada atau mengganti yang sudah ada jika ada. Membangun pada contoh sebelumnya, kode berikut menyisipkan atau mengganti entitas untuk "Walter Harp". Setelah membuat entitas baru, kode ini memanggil metode 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();
}

Menghapus entitas

Anda dapat menghapus entitas dengan memberikan kunci partisi dan kunci barisnya melalui 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();
}

Menghapus tabel

Terakhir, kode berikut menghapus tabel dari akun. Sekitar 40 detik setelah Anda menghapus tabel, Anda tidak dapat membuatnya kembali.

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

Lihat repositori contoh kode Azure Storage

Untuk contoh kode Azure Storage ujung ke ujung yang mudah digunakan yang dapat Anda unduh dan jalankan, lihat daftar Contoh Azure Storage kami.

Langkah berikutnya

• Memulai Layanan Tabel Azure di Java
• Explorer Microsoft Azure Storage adalah aplikasi mandiri gratis dari Microsoft yang memungkinkan Anda bekerja secara visual dengan data Azure Storage di Windows, macOS, dan Linux.
• Pustaka klien Tabel Azure untuk Java
• Referensi pustaka klien Tabel Azure
• REST API Tabel Azure
• Blog Tim Tabel Azure

Untuk informasi selengkapnya, kunjungi pengembang Azure for Java.