Buat kueri untuk mencantumkan sumber daya Batch secara efisien

  • Artikel

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.

Catatan

Layanan Batch menyediakan dukungan API untuk skenario umum menghitung tugas dalam pekerjaan, dan menghitung simpul komputasi di kumpulan Batch. Anda bisa memanggil operasi Dapatkan Jumlah Tugas dan Jumlah Node Kumpulan Daftar alih-alih menggunakan kueri daftar. Namun, operasi yang lebih efisien ini menampilkan informasi yang lebih terbatas yang mungkin tidak terbaru. Untuk informasi selengkapnya, lihat Menghitung tugas dan komputasi simpul menurut status.

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.

Penting

Kami sangat menyarankan agar Anda selalu menyediakan objek ODATADetailLevel ke daftar panggilan .NET API untuk efisiensi dan performa maksimum aplikasi Anda. Dengan menentukan tingkat detail, Anda dapat membantu menurunkan waktu respons layanan Batch, meningkatkan pemanfaatan jaringan, dan meminimalkan penggunaan memori oleh aplikasi klien.

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.

Catatan

Saat membuat salah satu dari tiga jenis string kueri, Anda harus memastikan bahwa nama properti dan kasus cocok dengan rekan elemen REST API-nya. Misalnya, saat bekerja dengan kelas .NET CloudTask, Anda harus menentukan status alih-alih Status, meski properti .NET adalah CloudTask.State. Untuk informasi selengkapnya, lihat pemetaan properti antara .NET dan REST API.

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. Jika semua properti diperlukan dan tidak ada string pilihan yang ditentukan, $expandharus 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.

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

Tip

Instans ODATADetailLevel yang dikonfigurasi dengan klausa Pilih dan Perluas juga dapat diteruskan ke metode Dapatkan yang sesuai, seperti PoolOperations.GetPool, untuk membatasi jumlah data yang dikembalikan.

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.
Metode daftar .NET Permintaan daftar REST
CertificateOperations.ListCertificates Mencantumkan sertifikat di akun
CloudTask.ListNodeFiles Mencantumkan file yang terkait dengan tugas
JobOperations.ListJobPreparationAndReleaseTaskStatus Mencantumkan status tugas persiapan pekerjaan dan pelepasan pekerjaan untuk suatu pekerjaan
JobOperations.ListJobs Mencantumkan pekerjaan di akun
JobOperations.ListNodeFiles Mencantumkan file di simpul
JobOperations.ListTasks Mencantumkan tugas yang terkait dengan pekerjaan
JobScheduleOperations.ListJobSchedules Mencantumkan jadwal pekerjaan di akun
JobScheduleOperations.ListJobs Mencantumkan pekerjaan yang terkait dengan jadwal pekerjaan
PoolOperations.ListComputeNodes Mencantumkan simpul komputasi di kumpulan
PoolOperations.ListPools Mencantumkan kumpulan di akun

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.
Jenis Batch .NET Entitas REST API
Sertifikat Mendapatkan informasi tentang sertifikat
CloudJob Mendapatkan informasi tentang pekerjaan
CloudJobSchedule Mendapatkan informasi tentang jadwal pekerjaan
ComputeNode Mendapatkan informasi tentang simpul
CloudPool Mendapatkan informasi tentang kumpulan
CloudTask Mendapatkan informasi tentang tugas

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:

Properti Operasi yang diizinkan Jenis
executionInfo/exitCode eq, ge, gt, le , lt Int

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:

Properti Jenis Catatan
id String The ID of the task.
commandLine String The command line of the task.

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