Membuat kueri untuk mencantumkan sumber daya Batch secara efisien

Sebagian besar aplikasi Azure Batch melakukan pemantauan atau operasi lain yang mengkueri layanan Batch. Kueri daftar tersebut sering kali terjadi pada interval yang teratur. Misalnya, sebelum Anda 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 terfilter untuk job Batch, tugas, simpul komputasi, dan sumber daya lainnya dengan pustaka Azure.Compute.Batch.

Catatan

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

Tentukan tingkat detail

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

Cuplikan kode API Azure.Compute.Batch ini mencantumkan setiap tugas yang terkait dengan sebuah job, beserta semua properti dari masing-masing tugas.

// Get a collection of all of the tasks and all of their properties for job-001
AsyncPageable<BatchTask> allTasks = batchClient.GetTasksAsync("job-001");

Terapkan tingkat detail ke kueri Anda untuk mencantumkan informasi secara lebih efisien. Teruskan filter, select, dan expand string ke metode BatchClient.GetTasks . Cuplikan ini hanya mengembalikan ID, baris perintah, dan properti informasi simpul komputasi dari tugas yang telah selesai.

// Specify filter and select strings to return only a subset of tasks and their properties.
AsyncPageable<BatchTask> completedTasks = batchClient.GetTasksAsync(
    jobId: "job-001",
    filter: "state eq 'completed'",
    select: new[] { "id", "commandLine", "nodeInfo" });

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 menggunakan parameter filter, select, dan expand dengan Azure. COMPUTE.Batch API, lihat bagian Kueri efisien di Azure. Compute.Batch.

Penting

Kami sangat menyarankan Agar Anda selalu menyediakan string filter, select, dan (jika sesuai) expand ke panggilan daftar API .NET Anda 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.

Gunakan string kueri

Anda dapat menggunakan Azure. API Compute.Batch dan Batch REST 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 Azure.Compute.Batch API, lihat referensi BatchClient untuk metode list yang parameter filter, select, dan expand-nya ingin Anda gunakan. Tinjau juga bagian Kueri efisien di Azure. Compute.Batch.

Untuk REST API Batch, lihat referensi REST API Batch. Temukan referensi Daftar untuk sumber daya yang ingin Anda kueri. Kemudian, tinjau bagian Parameter URI untuk detail tentang $filter, , $selectdan $expand. Misalnya, lihat parameter URI untuk Pool - List. 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 mereka. Misalnya, saat bekerja dengan kelas .NET BatchTask, Anda harus menentukan state alih-alih State, meskipun properti .NET BatchTask.State. Untuk informasi selengkapnya, lihat pemetaan properti antara .NET dan REST API.

Filter

Ekspresi string $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 beberapa ekspresi, dengan ekspresi yang terdiri dari nama properti, operator, dan nilai. Properti yang dapat ditentukan bersifat khusus untuk setiap jenis entitas yang Anda periksa, demikian juga dengan operator yang didukung untuk setiap properti. Beberapa ekspresi dapat digabungkan dengan menggunakan operator and logis dan or.

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

Pilih

String $select ekspresi 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 properti apa pun untuk jenis entitas yang Anda cari.

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

Perluas

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

Mirip dengan $select, $expand mengontrol berapa banyak data tertentu yang disertakan dalam hasil kueri daftar. Ketika semua properti diperlukan dan tidak ada string pilihan yang ditentukan, $expandharus digunakan untuk mendapatkan informasi statistik. Jika string pilih digunakan untuk mendapatkan subset properti, maka stats dapat ditentukan dalam string pilih, dan $expand tidak perlu ditentukan.

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

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

Aturan untuk filter, pilih, dan perluas string

  • Pastikan nama properti dalam filter, select, dan expand string muncul seperti di Batch REST API. Aturan ini berlaku bahkan ketika Anda menggunakan Azure. Compute.Batch atau salah satu SDK Batch lainnya.
  • Semua nama properti sensitif terhadap huruf besar/kecil, tetapi nilai properti tidak sensitif terhadap huruf besar/kecil.
  • String tanggal/waktu dapat 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 adalah true atau false.
  • Jika properti atau operator yang tidak valid ditentukan, kesalahan 400 (Bad Request) akan dihasilkan.

Kueri yang efisien dalam Azure. Compute.Batch

Di Azure. COMPUTE.Batch API, metode daftar pada BatchClient menerima parameter filter, select, dan expand secara langsung:

  • filter: Batasi jumlah item yang dikembalikan.
  • select: Tentukan nilai properti mana yang dikembalikan dengan setiap item.
  • expand: Ambil data untuk semua item dalam satu panggilan API alih-alih panggilan terpisah untuk setiap item.

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

// Pull only the "test" pools, and limit the data crossing the wire by selecting only
// the Id and Statistics properties. Use expand="stats" so the .NET API pulls the
// statistics for the BatchPools 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 (BatchPool.Statistics).
List<BatchPool> testPools = new List<BatchPool>();
await foreach (BatchPool pool in myBatchClient.GetPoolsAsync(
    filter: "startswith(id, 'test')",
    select: new[] { "id", "stats" },
    expand: new[] { "stats" }))
{
    testPools.Add(pool);
}

Petunjuk

Parameter filter, select, dan expand yang sama juga dapat diteruskan ke metode Get yang sesuai, seperti BatchClient.GetPool, untuk membatasi jumlah data yang dikembalikan.

Pemetaan Batch REST dalam API .NET

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

Pemetaan untuk string filter

  • .NET mencantumkan metode: Masing-masing metode API .NET dalam kolom ini menerima parameter string filter, select, dan expand.
  • 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 filter string.
Metode Daftar di .NET Permintaan daftar REST
BatchAccountResource.GetBatchAccountCertificates Mencantumkan sertifikat dalam akun
BatchClient.GetTaskFiles Mencantumkan file yang terkait dengan tugas
BatchClient.GetJobPreparationAndReleaseTaskStatuses Daftar status persiapan dan pelepasan tugas untuk pekerjaan
BatchClient.GetJobs Mencantumkan pekerjaan di akun
BatchClient.GetNodeFiles Mencantumkan file pada simpul
BatchClient.GetTasks Mencantumkan tugas yang terkait dengan pekerjaan
BatchClient.GetJobSchedules Mencantumkan jadwal pekerjaan di akun
BatchClient.GetJobsFromSchedule Mencantumkan pekerjaan yang terkait dengan jadwal pekerjaan
BatchClient.GetNodes Mencantumkan simpul komputasi dalam kumpulan
BatchClient.GetPools Mencantumkan kumpulan dalam akun

Pemetaan untuk string tertentu

  • Azure. Jenis Compute.Batch: Azure. Jenis API Compute.Batch.
  • Entitas REST API: Setiap halaman di kolom ini berisi satu atau beberapa tabel yang mencantumkan nama properti REST API untuk jenis tersebut. Nama properti ini digunakan saat Anda membuat string pilih . Anda menggunakan nama properti yang sama ini saat membuat select string.
Jenis Azure.Compute.Batch Entitas REST API
BatchJob Mendapatkan informasi tentang pekerjaan
BatchJobSchedule Mendapatkan informasi tentang jadwal pekerjaan
BatchNode Mendapatkan informasi tentang simpul
BatchPool Mendapatkan informasi tentang kumpulan
BatchTask Mendapatkan informasi tentang tugas

Contoh: membuat string filter

Untuk membuat string filter untuk parameter metode filter daftar, temukan halaman REST API yang sesuai. Properti yang dapat dipilih dan operator yang didukung berada di tabel multi-baris pertama. Misalnya, untuk mengambil semua tugas yang kode keluarnya bukan nol, centang Daftar tugas yang terkait dengan pekerjaan untuk string properti yang berlaku dan operator yang diizinkan:

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

String filter terkait adalah:

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

Contoh: membuat string pemilihan

Untuk membuat select string, temukan halaman REST API yang sesuai untuk entitas yang Anda cantumkan. Properti yang dapat dipilih dan operator yang didukung berada di tabel multi-baris pertama. Misalnya, untuk hanya mengambil ID dan baris perintah untuk setiap tugas dalam daftar, centang Dapatkan informasi tentang tugas:

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

String pilih 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 BatchClient.GetTasks dan meneruskan nilai parameter , , filterdan select yang berbeda expanduntuk memvariasikan jumlah data yang akan dikembalikan. 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 dikembalikan. 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 API Batch.

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

Aplikasi sampel dalam proyek menunjukkan operasi ini:

  • Memilih atribut tertentu untuk mengunduh properti yang Anda butuhkan saja
  • Pemfilteran berdasarkan waktu transisi status untuk mengunduh perubahan hanya sejak kueri terakhir

Misalnya, metode berikut muncul di pustaka BatchMetrics. Ini mengembalikan tuple yang berisi string select dan filter yang menentukan bahwa hanya properti id dan state yang harus diambil untuk entitas yang dikueri, dan bahwa hanya entitas yang keadaannya telah berubah sejak parameter DateTime yang ditentukan yang harus dikembalikan.

return (
    Filter: string.Format("stateTransitionTime gt DateTime'{0:o}'", time),
    Select: new[] { "id", "state" });

Langkah selanjutnya

  • Last updated on