Membuat kueri untuk mencantumkan sumber daya Batch secara efisien

Sebagian besar Azure Batch aplikasi melakukan pemantauan atau operasi lain yang mengkueri layanan Batch. Kueri daftar tersebut sering terjadi secara berkala. Misalnya, sebelum dapat memeriksa tugas yang diantrekan dalam pekerjaan, Anda harus mendapatkan data pada setiap tugas dalam pekerjaan tersebut. Mengurangi jumlah data yang dikembalikan layanan Batch untuk kueri meningkatkan performa aplikasi Anda. Artikel ini menjelaskan cara membuat dan menjalankan kueri tersebut dengan cara yang efisien. Anda dapat membuat kueri yang difilter untuk pekerjaan Batch, tugas, node komputasi, dan sumber daya lainnya dengan pustaka Batch .NET.

Menentukan tingkat detail

Mungkin ada ribuan entitas seperti pekerjaan, tugas, dan node komputasi dalam aplikasi Batch produksi. Untuk setiap kueri yang Anda buat tentang sumber daya, sejumlah besar data beralih dari layanan Batch ke aplikasi Anda. Batasi berapa banyak item dan informasi apa yang dikembalikan kueri Anda guna meningkatkan performa.

Cuplikan kode Batch .NET API ini mencantumkan semua tugas yang terkait dengan pekerjaan, bersama dengan semua properti dari setiap tugas.

// Get a collection of all of the tasks and all of their properties for job-001
IPagedEnumerable<CloudTask> allTasks =
    batchClient.JobOperations.ListTasks("job-001");

Terapkan tingkat detail ke kueri Anda untuk mencantumkan informasi secara lebih efisien. Berikan objek ODATADetailLevel ke metode JobOperations.ListTasks. Cuplikan ini hanya menampilkan ID, baris perintah, dan properti informasi simpul komputasi dari tugas yang selesai.

// Configure an ODATADetailLevel specifying a subset of tasks and
// their properties to return
ODATADetailLevel detailLevel = new ODATADetailLevel();
detailLevel.FilterClause = "state eq 'completed'";
detailLevel.SelectClause = "id,commandLine,nodeInfo";

// Supply the ODATADetailLevel to the ListTasks method
IPagedEnumerable<CloudTask> completedTasks =
    batchClient.JobOperations.ListTasks("job-001", detailLevel);

Dalam skenario contoh ini, jika ada ribuan tugas dalam pekerjaan, hasil dari kueri kedua biasanya dikembalikan lebih cepat daripada dari kueri pertama. Untuk informasi selengkapnya tentang penggunaan ODATADetailLevel saat Anda mencantumkan item dengan Batch .NET API, lihat bagian Kueri yang efisien di Batch .NET.

Menggunakan string kueri

Anda dapat menggunakan BATCH .NET dan Batch REST API untuk mengurangi berapa banyak item yang dikembalikan kueri, dan berapa banyak informasi yang dikembalikan kueri untuk setiap item. Ada tiga jenis string kueri yang bisa Anda gunakan untuk mempersempit kueri Anda: $filter, $select, dan $expand.

Untuk Batch .NET API, lihat Properti Kelas ODATADetailLevel. Tinjau juga bagian Kueri yang efisien di Batch .NET.

Untuk Batch REST API, lihat Referensi Batch REST API. Temukan referensi Daftar untuk sumber daya yang ingin Anda kueri. Kemudian, tinjau bagian Parameter URI untuk detail tentang $filter, $select, dan $expand. Misalnya, lihat parameter URI untuk Kumpulan - Daftar. Lihat juga cara membuat kueri Batch yang efisien dengan Azure CLI.

Filter

String ekspresi $filter mengurangi jumlah item yang dikembalikan. Misalnya, Anda hanya dapat mencantumkan tugas yang sedang berjalan untuk pekerjaan, atau hanya mencantumkan simpul komputasi yang siap menjalankan tugas.

String ini terdiri dari satu atau lebih ekspresi, dengan ekspresi yang terdiri dari nama properti, operator, dan nilai. Properti yang dapat ditentukan khusus untuk setiap tipe entitas yang Anda kueri, seperti halnya operator yang didukung untuk setiap properti. Beberapa ekspresi dapat digabungkan dengan menggunakan operator logika and dan or.

Contoh ini hanya mencantumkan tugas render yang berjalan: (state eq 'running') and startswith(id, 'renderTask').

Pilih

String ekspresi $select membatasi nilai properti yang dikembalikan untuk setiap item. Anda menentukan daftar nama properti yang dipisahkan koma, dan hanya nilai properti tersebut yang dikembalikan untuk item dalam hasil kueri. Anda dapat menentukan salah satu properti untuk jenis entitas yang Anda kueri.

Contoh ini menetapkan bahwa hanya tiga nilai properti yang harus dikembalikan untuk setiap tugas: id, state, stateTransitionTime.

Perluas

String ekspresi $expand mengurangi jumlah panggilan API yang diperlukan untuk mendapatkan informasi tertentu. Anda dapat menggunakan string ini untuk mendapatkan informasi selengkapnya tentang setiap item dengan satu panggilan API. Metode ini membantu meningkatkan performa dengan mengurangi panggilan API. Gunakan string $expand alih-alih mendapatkan daftar entitas dan meminta informasi tentang setiap item daftar.

Serupa dengan $select, $expand mengontrol apakah data tertentu disertakan dalam hasil kueri daftar. Ketika semua properti diperlukan dan tidak ada string pilihan yang ditentukan, $expand harus digunakan untuk mendapatkan informasi statistik. Jika string pilih digunakan untuk mendapatkan subkumpulan properti, stats dapat ditentukan dalam string pilih, dan $expand tidak perlu ditentukan.

Penggunaan string ini yang didukung termasuk mencantumkan pekerjaan, jadwal pekerjaan, tugas, dan kumpulan. Saat ini, string hanya mendukung informasi statistik.

Contoh ini menetapkan bahwa informasi statistik harus dikembalikan untuk setiap item dalam daftar: stats.

Aturan untuk string filter, pilih, dan perluas

• Pastikan nama properti dalam string filter, pilih, dan perluas muncul seperti yang dilakukan di Batch REST API. Aturan ini berlaku bahkan ketika Anda menggunakan Batch .NET atau salah satu SDK Batch lainnya.
• Semua nama properti peka huruf besar/kecil, tetapi nilai properti tidak peka huruf besar/kecil.
• String tanggal/waktu bisa berupa salah satu dari dua format, dan harus didahului dengan DateTime.
  • Contoh format W3C-DTF: creationTime gt DateTime'2011-05-08T08:49:37Z'
  • Contoh format RFC 1123: creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
• String Boolean berupa true atau false.
• Jika properti atau operator yang invalid ditentukan, galat 400 (Bad Request) akan terjadi.

Kueri efisien dalam Batch .NET

Di Batch .NET API, kelas ODATADetailLevel menyediakan filter, pilih, dan perluas string ke daftar operasi. Kelas ODataDetailLevel ini memiliki tiga properti string publik. Anda dapat menentukan properti ini di konstruktor, atau mengatur properti langsung pada objek. Kemudian, teruskan objek ODataDetailLevel sebagai parameter ke berbagai operasi daftar seperti ListPools, ListJobs, dan ListTasks.

• ODATADetailLevel.FilterClause: Batasi jumlah item yang dikembalikan.
• ODATADetailLevel.SelectClause: Tentukan nilai properti mana yang dikembalikan dengan setiap item.
• ODATADetailLevel.ExpandClause: Ambil data dari setiap item di satu panggilan API alih-alih panggilan berbeda untuk setiap item.

Cuplikan kode berikut menggunakan Batch .NET API untuk mengkueri layanan Batch secara efisien untuk statistik rangkaian dari kumpulan tertentu. Pengguna Batch memiliki kumpulan pengujian dan produksi. Kumpulan ID uji diawali dengan "test", dan kumpulan ID produksi diawali dengan "prod". myBatchClient adalah instans kelas BatchClient yang diinisialisasi dengan benar.

// First we need an ODATADetailLevel instance on which to set the filter, select,
// and expand clause strings
ODATADetailLevel detailLevel = new ODATADetailLevel();

// We want to pull only the "test" pools, so we limit the number of items returned
// by using a FilterClause and specifying that the pool IDs must start with "test"
detailLevel.FilterClause = "startswith(id, 'test')";

// To further limit the data that crosses the wire, configure the SelectClause to
// limit the properties that are returned on each CloudPool object to only
// CloudPool.Id and CloudPool.Statistics
detailLevel.SelectClause = "id, stats";

// Specify the ExpandClause so that the .NET API pulls the statistics for the
// CloudPools in a single underlying REST API call. Note that we use the pool's
// REST API element name "stats" here as opposed to "Statistics" as it appears in
// the .NET API (CloudPool.Statistics)
detailLevel.ExpandClause = "stats";

// Now get our collection of pools, minimizing the amount of data that is returned
// by specifying the detail level that we configured above
List<CloudPool> testPools =
    await myBatchClient.PoolOperations.ListPools(detailLevel).ToListAsync();

Batch REST ke pemetaan .NET API

Nama properti dalam string filter, pilih, dan perluas harus mencerminkan rekanan REST API mereka, baik dalam nama maupun besar/kecil huruf. Tabel di bawah ini menyediakan pemetaan antara rekanan .NET dengan REST API.

Pemetaan untuk string filter

• Metode daftar .NET: Setiap metode .NET API di kolom ini menerima objek ODATADetailLevel sebagai parameter.
• Permintaan daftar REST: Setiap halaman REST API yang tercantum di kolom ini berisi tabel dengan properti dan operasi yang diizinkan dalam string filter. Anda dapat menggunakan nama dan operasi properti ini saat membuat string ODATADetailLevel.FilterClause.

Pemetaan untuk string tertentu

• Jenis Batch .NET: Jenis Batch .NET API.
• Entitas REST API: Setiap halaman di kolom ini berisi satu atau beberapa tabel yang mencantumkan nama properti REST API untuk setiap jenis. Nama properti ini digunakan saat Anda membuat string pilih. Anda menggunakan nama properti yang sama ini saat Anda membuat string ODATADetailLevel.SelectClause.

Contoh: membuat string filter

Untuk membuat string filter untuk ODATADetailLevel.FilterClause, temukan halaman REST API yang sesuai. Properti yang dapat dipilih dan operator yang didukung berada dalam tabel multibaris pertama. Misalnya, untuk mengambil semua tugas yang kode keluarnya bukan nol, centang Buat daftar tugas yang terkait dengan pekerjaan untuk string properti yang berlaku dan operator yang diizinkan:

String filter terkait adalah:

(executionInfo/exitCode lt 0) or (executionInfo/exitCode gt 0)

Contoh: membuat string pilih

Untuk membuat ODATADetailLevel.SelectClause, temukan halaman REST API terkait untuk entitas yang Anda cantumkan. Properti yang dapat dipilih dan operator yang didukung berada dalam tabel multibaris pertama. Misalnya, untuk mengambil hanya ID dan baris perintah untuk setiap tugas dalam daftar, centang Dapatkan informasi tentang tugas:

String pemilih terkait adalah:

id, commandLine

Sampel kode

Kueri daftar yang efisien

Proyek sampel EfficientListQueries menunjukkan seberapa efisien kueri daftar memengaruhi performa aplikasi. Aplikasi konsol C# ini membuat dan menambahkan sejumlah besar tugas ke pekerjaan. Kemudian, aplikasi melakukan beberapa panggilan ke metode JobOperations.ListTasks dan meneruskan objek ODATADetailLevel. Objek ini dikonfigurasi dengan nilai properti yang berbeda untuk memvariasikan jumlah data yang akan ditampilkan. Sampel ini menghasilkan output yang mirip dengan:

Adding 5000 tasks to job jobEffQuery...
5000 tasks added in 00:00:47.3467587, hit ENTER to query tasks...

4943 tasks retrieved in 00:00:04.3408081 (ExpandClause:  | FilterClause: state eq 'active' | SelectClause: id,state)
0 tasks retrieved in 00:00:00.2662920 (ExpandClause:  | FilterClause: state eq 'running' | SelectClause: id,state)
59 tasks retrieved in 00:00:00.3337760 (ExpandClause:  | FilterClause: state eq 'completed' | SelectClause: id,state)
5000 tasks retrieved in 00:00:04.1429881 (ExpandClause:  | FilterClause:  | SelectClause: id,state)
5000 tasks retrieved in 00:00:15.1016127 (ExpandClause:  | FilterClause:  | SelectClause: id,state,environmentSettings)
5000 tasks retrieved in 00:00:17.0548145 (ExpandClause: stats | FilterClause:  | SelectClause: )

Sample complete, hit ENTER to continue...

Contoh menunjukkan Anda bisa sangat menurunkan waktu respons kueri dengan membatasi properti dan jumlah item yang ditampilkan. Anda dapat menemukan ini dan proyek sampel lainnya di repositori azure-batch-samples di GitHub.

Pustaka BatchMetrics

Proyek sampel BatchMetrics berikut menunjukkan cara memantau kemajuan pekerjaan Azure Batch secara efisien menggunakan Batch API.

Sampel ini mencakup proyek pustaka kelas .NET, yang dapat Anda masukkan ke dalam proyek Anda sendiri. Ada juga program baris perintah sederhana untuk melatih dan menunjukkan penggunaan pustaka.

Aplikasi sampel dalam proyek menunjukkan operasi ini:

• Memilih atribut khusus untuk mengunduh hanya properti yang Anda butuhkan
• Memfilter waktu transisi status untuk mengunduh hanya perubahan sejak kueri terakhir

Misalnya, metode berikut muncul di pustaka BatchMetrics. Ini mengembalikan ODATADetailLevel yang menentukan bahwa hanya properti id dan state yang harus diperoleh untuk entitas yang dikueri. Ini juga menentukan bahwa hanya entitas yang statusnya telah berubah sejak parameter DateTime yang ditentukan harus dikembalikan.

internal static ODATADetailLevel OnlyChangedAfter(DateTime time)
{
    return new ODATADetailLevel(
        selectClause: "id, state",
        filterClause: string.Format("stateTransitionTime gt DateTime'{0:o}'", time)
    );
}

Langkah berikutnya

• Maksimalkan penggunaan sumber daya komputasi Azure Batch dengan tugas node bersamaan. Beberapa jenis beban kerja dapat mengambil manfaat dari menjalankan tugas paralel pada simpul komputasi yang lebih besar (tetapi lebih sedikit). Lihat contoh skenario dalam artikel untuk detail tentang skenario seperti itu.
• Memantau solusi Batch dengan menghitung tugas dan simpul menurut status