Menyimpan data tugas di Azure Storage dengan API layanan Batch

Artikel
06/01/2023

Tugas yang berjalan di Azure Batch dapat menghasilkan data output saat dijalankan. Data output tugas sering kali perlu disimpan untuk diambil oleh tugas lain dalam pekerjaan, aplikasi klien yang menjalankan pekerjaan, atau keduanya. Tugas menulis data output ke sistem file simpul komputasi Azure Batch, tetapi semua data pada simpul hilang saat digambar ulang atau saat simpul meninggalkan kumpulan. Tugas mungkin juga memiliki periode retensi file, setelah itu file yang dibuat oleh tugas akan dihapus. Karena alasan ini, penting untuk mempertahankan output tugas yang nantinya Anda perlukan ke penyimpanan data seperti Azure Storage.

Untuk opsi akun penyimpanan di Azure Batch, lihat Akun Azure Batch dan akun Azure Storage.

API layanan Batch mendukung data output yang bertahan di Azure Storage untuk tugas dan tugas pengelola pekerjaan yang berjalan pada pool dengan Konfigurasi Komputer Virtual. Saat menambahkan tugas, Anda bisa menentukan satu kontainer di Azure Storage sebagai tujuan untuk output tugas. Layanan Batch kemudian akan menulis data output apa pun ke kontainer tersebut saat tugas selesai.

Saat menggunakan API layanan Batch untuk menyimpan output tugas, Anda tidak perlu memodifikasi aplikasi yang digunakan untuk menjalankan tugas itu. Sebaliknya, dengan sedikit modifikasi pada aplikasi klien Anda, Anda dapat menyimpan output tugas dengan kode yang sama yang digunakan untuk membuat tugas tersebut.

Penting

Menyimpan data tugas di Azure Storage dengan API layanan Batch tidak dilakukan pada pool (kumpulan) yang dibuat sebelum 1 Februari 2018.

Kapan saya perlu menggunakan API layanan Batch untuk menyimpan output tugas?

Azure Batch menyediakan lebih dari satu cara untuk menyimpan output tugas. Menggunakan API layanan Batch adalah pendekatan praktis yang paling cocok untuk skenario ini:

Anda ingin menuliskan kode untuk menyimpan output tugas dari dalam aplikasi klien Anda, tanpa mengubah aplikasi yang dijalankan tugas Anda.
Anda ingin menyimpan output dari tugas Batch dan tugas pengelola pekerjaan di pool yang dibuat dengan konfigurasi komputer virtual.
Anda ingin tetap menyimpan output ke kontainer Azure Storage dengan nama arbitrer.
Anda ingin menyimpan output ke kontainer Azure Storage dengan yang dinamai berdasarkan standar Konvensi File Batch.

Jika skenario Anda berbeda dari yang tercantum di atas, Anda mungkin perlu mempertimbangkan pendekatan yang berbeda. Misalnya, API layanan Batch saat ini tidak mendukung output streaming ke Azure Storage saat tugas sedang berjalan. Untuk mengalirkan output, pertimbangkan penggunaan pustaka Konvensi File Batch, tersedia untuk .NET. Untuk bahasa lain, Anda harus menerapkan solusi Anda sendiri. Untuk informasi selengkapnya tentang opsi lainnya, lihat Pertahankan pekerjaan dan output tugas ke Azure Storage.

Membuat kontainer di Azure Storage

Untuk menyimpankan output tugas ke Azure Storage, Anda harus membuat kontainer yang berfungsi sebagai tujuan untuk file output Anda. Buat kontainer sebelum Anda menjalankan tugas Anda, sebaiknya sebelum Anda mengirimkan pekerjaan Anda, dengan menggunakan pustaka klien Azure Storage atau SDK yang sesuai. Untuk informasi selengkapnya tentang API Azure Storage, lihat dokumentasi Azure Storage.

Misalnya, jika Anda menulis aplikasi di C#, gunakan pustaka klien Azure Storage untuk .NET. Contoh berikut menunjukkan cara membuat kontainer:

CloudBlobContainer container = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
await container.CreateIfNotExists();

Menentukan file output untuk output tugas

Untuk menentukan file output untuk tugas, buat kumpulan objek OutputFile dan tetapkan ke properti CloudTask.OutputFiles saat Anda membuat tugas. Anda dapat menggunakan Tanda Tangan Akses Bersama (SAS) atau identitas terkelola untuk mengautentikasi akses ke kontainer.

Menggunakan Tanda Tangan Akses Bersama

Setelah Anda membuat kontainer, dapatkan tanda tangan akses bersama (SAS) dengan akses tulis ke kontainer. SAS menyediakan akses delegasi (penugasan) ke kontainer. SAS memberikan akses dengan sekumpulan izin tertentu untuk selama interval waktu tertentu. Layanan Batch memerlukan SAS dengan izin tulis untuk menulis output tugas ke kontainer. Untuk informasi selengkapnya tentang SAS, lihat Menggunakan tanda tangan akses bersama (SAS) di Azure Storage.

Saat Anda mendapatkan SAS menggunakan API Azure Storage, API mengembalikan string token SAS. String token ini mencakup semua parameter SAS, termasuk izin dan interval tempat SAS menjadi valid. Untuk menggunakan SAS dalam mengakses kontainer di Azure Storage, Anda perlu menambahkan string token SAS ke URI sumber daya. URI sumber daya, bersama dengan token SAS yang ditambahkan, akan memberikan akses tervalidasi ke Azure Storage.

Contoh berikut menunjukkan cara mendapatkan string token SAS tulis-saja untuk kontainer, lalu menambahkan SAS tersebut ke URI kontainer:

string containerSasToken = container.GetSharedAccessSignature(new SharedAccessBlobPolicy()
{
    SharedAccessExpiryTime = DateTimeOffset.UtcNow.AddDays(1),
    Permissions = SharedAccessBlobPermissions.Write
});

string containerSasUrl = container.Uri.AbsoluteUri + containerSasToken;

Contoh kode C# berikut membuat tugas yang menulis angka acak ke file bernama output.txt. Contoh ini membuat file output agar output.txt ditulis ke kontainer. Contoh ini juga membuat file output untuk file log apa pun yang cocok dengan pola file std*.txt (misalnya, stdout.txt dan stderr.txt). URL kontainer akan meminta SAS yang telah dibuat untuk kontainer. Layanan Batch menggunakan SAS untuk mengautentikasi akses ke kontainer.

new CloudTask(taskId, "cmd /v:ON /c \"echo off && set && (FOR /L %i IN (1,1,100000) DO (ECHO !RANDOM!)) > output.txt\"")
{
    OutputFiles = new List<OutputFile>
    {
        new OutputFile(
            filePattern: @"..\std*.txt",
            destination: new OutputFileDestination(
         new OutputFileBlobContainerDestination(
                    containerUrl: containerSasUrl,
                    path: taskId)),
            uploadOptions: new OutputFileUploadOptions(
            uploadCondition: OutputFileUploadCondition.TaskCompletion)),
        new OutputFile(
            filePattern: @"output.txt",
            destination: 
         new OutputFileDestination(new OutputFileBlobContainerDestination(
                    containerUrl: containerSasUrl,
                    path: taskId + @"\output.txt")),
            uploadOptions: new OutputFileUploadOptions(
            uploadCondition: OutputFileUploadCondition.TaskCompletion)),
}

Catatan

Jika menggunakan contoh ini dengan Linux, pastikan Anda mengubah garis miring terbalik menjadi garis miring biasa.

Menggunakan Identitas Terkelola

Alih-alih menghasilkan dan melewati SAS dengan akses tulis ke kontainer ke Batch, identitas terkelola dapat digunakan untuk mengautentikasi dengan Azure Storage. Identitas harus ditetapkan ke Kumpulan Batch, dan juga membuat penetapan peran Storage Blob Data Contributor untuk kontainer untuk ditulis. Layanan Batch kemudian dapat diberi tahu untuk menggunakan identitas terkelola dan bukan SAS untuk mengautentikasi akses ke kontainer.

CloudBlobContainer container = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
await container.CreateIfNotExists();

new CloudTask(taskId, "cmd /v:ON /c \"echo off && set && (FOR /L %i IN (1,1,100000) DO (ECHO !RANDOM!)) > output.txt\"")
{
    OutputFiles = new List<OutputFile>
    {
        new OutputFile(
            filePattern: @"..\std*.txt",
            destination: new OutputFileDestination(
         new OutputFileBlobContainerDestination(
                    containerUrl: container.Uri,
                    path: taskId,
                    identityReference: new ComputeNodeIdentityReference() { ResourceId = "/subscriptions/SUB/resourceGroups/RG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/identity-name"} })),
            uploadOptions: new OutputFileUploadOptions(
            uploadCondition: OutputFileUploadCondition.TaskCompletion))
    }
}

Menentukan pola file untuk pencocokan

Ketika Anda menentukan file output, Anda dapat menggunakan properti OutputFile.FilePattern guna menentukan pola file untuk pencocokan. Pola file mungkin cocok dengan file nol, satu file, atau sekumpulan file yang dibuat oleh tugas.

Properti FilePattern mendukung wildcard sistem file standar seperti * (untuk kecocokan tidak berulang) dan ** (untuk kecocokan berulang). Misalnya, sampel kode di atas menentukan pola file agar cocok dengan std*.txt yang tidak berulang:

filePattern: @"..\std*.txt"

Untuk mengunggah satu file, tentukan pola file tanpa wildcard. Misalnya, sampel kode di atas menentukan pola file agar cocok dengan output.txt:

filePattern: @"output.txt"

Menentukan kondisi unggahan

Properti OutputFileUploadOptions.UploadCondition mengizinkan pengunggahan bersyarat dari file output. Skenario umum adalah mengunggah satu set file jika tugas berhasil, dan sekumpulan file yang berbeda jika gagal. Misalnya, Anda mungkin ingin mengunggah file log verbose hanya saat tugas gagal dan keluar dengan kode keluar nonzero. Demikian pula, Anda mungkin ingin mengunggah file hasil hanya jika tugas berhasil, karena file tersebut mungkin hilang atau tidak lengkap jika tugas gagal.

Sampel kode di atas menetapkan properti UploadCondition ke TaskCompletion. Pengaturan ini menentukan bahwa file tersebut akan diunggah setelah tugas selesai, terlepas dari nilai kode keluarnya.

uploadCondition: OutputFileUploadCondition.TaskCompletion

Untuk pengaturan lainnya, lihat enum OutputFileUploadCondition.

Membedakan file dengan nama yang sama

Tugas-tugas dalam satu pekerjaan bisa menghasilkan file dengan nama yang sama. Misalnya, stdout.txt dan stderr.txt dibuat untuk setiap tugas yang berjalan dalam satu pekerjaan. Karena setiap tugas berjalan dalam konteksnya sendiri, file-file tersebut tidak bertentangan pada sistem file simpul tersebut. Namun, saat mengunggah file dari beberapa tugas ke kontainer bersama, Anda harus membedakan file dengan nama yang sama.

Properti OutputFileBlobContainerDestination.Path menentukan blob tujuan atau direktori virtual untuk file output. Anda dapat menggunakan properti Jalur untuk memberi nama blob atau direktori virtual sedemikian rupa sehingga file output dengan nama sama diberi nama yang unik di Azure Storage. Menggunakan ID tugas di jalur adalah cara yang baik untuk memastikan nama unik dan mengidentifikasi file dengan mudah.

Jika properti FilePattern ditetapkan ke ekspresi wildcard, maka semua file yang cocok dengan pola diunggah ke direktori virtual yang ditentukan oleh properti Jalur. Misalnya, jika kontainer adalah mycontainer, maka ID tugasnya adalah mytask, dan pola file-nya adalah ..\std*.txt, maka URI absolut ke file output di Azure Storage akan mirip dengan:

https://myaccount.blob.core.windows.net/mycontainer/mytask/stderr.txt
https://myaccount.blob.core.windows.net/mycontainer/mytask/stdout.txt

Jika properti FilePattern ditetapkan agar sesuai dengan satu nama file, artinya properti tersebut tidak berisi karakter wildcard, maka nilai properti Jalur menentukan nama blob yang sepenuhnya memenuhi syarat. Jika Anda mengantisipasi konflik penamaan dengan satu file dari beberapa tugas, maka sertakan nama direktori virtual sebagai bagian dari nama file untuk membedakan file tersebut. Misalnya, tetapkan properti Jalur agar menyertakan ID tugas, karakter pembatas (biasanya garis miring), dan nama file:

path: taskId + @"/output.txt"

URI absolut ke file output untuk sekumpulan tugas akan serupa dengan:

https://myaccount.blob.core.windows.net/mycontainer/task1/output.txt
https://myaccount.blob.core.windows.net/mycontainer/task2/output.txt

Untuk informasi selengkapnya tentang direktori virtual di Azure Storage, lihat Mencantumkan blob dalam kontainer.

Banyak File Output

Saat tugas menentukan banyak file output, Anda mungkin mengalami batasan yang diberlakukan oleh AZURE Batch API. Dianjurkan untuk menjaga tugas Anda tetap kecil dan menjaga jumlah file output tetap rendah.

Jika Anda mengalami batasan, pertimbangkan untuk mengurangi jumlah file output dengan menggunakan Pola File atau menggunakan kontainer file seperti tar atau zip untuk mengonsolidasikan file output. Atau, gunakan pemasangan atau pendekatan lain untuk mempertahankan data output (lihat Mempertahankan output pekerjaan dan tugas).

Mendiagnosis kesalahan pengunggahan file

Jika pengunggahan file output ke Azure Storage gagal, tugas akan dipindahkan ke status Selesai dan properti TaskExecutionInformation.FailureInformation diatur. Periksa properti FailureInformation untuk mengetahui kesalahan apa yang terjadi. Misalnya, berikut adalah kesalahan yang terjadi pada unggahan file jika kontainer tidak dapat ditemukan:

Category: UserError
Code: FileUploadContainerNotFound
Message: One of the specified Azure container(s) was not found while attempting to upload an output file

Pada setiap unggahan file, Batch menulis dua file log ke simpul komputasi, fileuploadout.txt dan fileuploaderr.txt. Anda dapat memeriksa file log ini untuk mempelajari lebih lanjut mengenai kegagalan tertentu. Jika unggahan file tidak pernah dijalankan, misalnya karena tugas itu sendiri tidak dapat berjalan, maka file log ini tidak akan ada.

Mendiagnosis performa unggahan file

Progres pengunggahan log file fileuploadout.txt. Anda dapat memeriksa file ini untuk mempelajari selengkapnya tentang lamanya waktu yang diperlukan untuk mengunggah file. Ingat bahwa ada banyak faktor yang memengaruhi performa unggahan, termasuk ukuran node, aktivitas lainnya di node pada saat pengunggahan, apakah kontainer target berada di wilayah yang sama dengan pool Batch, jumlah node yang diunggah ke akun penyimpanan di saat yang sama, dan sebagainya.

Menggunakan API layanan Batch dengan standar Konvensi File Batch

Saat menyimpan output tugas dengan API layanan Batch, Anda dapat memberi nama kontainer tujuan dan blob sesuka Anda. Anda juga dapat memilih nama yang sesuai dengan standar Konvensi File Batch. Standar Konvensi File menentukan nama kontainer dan blob tujuan di Azure Storage untuk file output tertentu berdasarkan nama pekerjaan dan tugas. Jika Anda menggunakan standar File Convention untuk penamaan file output, maka file output Anda tersedia untuk dilihat di portal Azure.

Jika mengembangkannya di C#, Anda dapat menggunakan metode yang dibuat dalam pustaka Konvensi File Batch untuk .NET. Pustaka ini membuat kontainer dan jalur blob dengan nama yang benar untuk Anda. Misalnya, Anda dapat memanggil API untuk mendapatkan nama yang benar untuk kontainer tersebut, berdasarkan nama pekerjaan:

string containerName = job.OutputStorageContainerName();

Anda dapat menggunakan metode CloudJobExtensions.GetOutputStorageContainerUrl untuk mengembalikan URL tanda tangan akses bersama (SAS) yang digunakan untuk menulis di kontainer. Anda kemudian dapat meneruskan SAS ini ke konstruktor OutputFileBlobContainerDestination.

Jika Anda mengembangkan dalam bahasa selain C#, Anda harus menerapkan standar Konvensi File sendiri.

Sampel kode

Proyek sampel PersistOutputs adalah salah satu sampel kode Azure Batch di GitHub. Solusi Visual Studio ini menunjukkan cara menggunakan pustaka klien Batch untuk .NET untuk menyimpan output tugas di penyimpanan yang tahan lama. Untuk menjalankan sampel ini, ikuti langkah-langkah berikut:

Buka proyek di Visual Studio 2019.
Tambahkan kredensial akun Batch dan Storage Anda ke AccountSettings.settings di proyek Azure.Batch.Samples.Common.
Bangun (tetapi jangan menjalankan) solusi. Pulihkan paket NuGet apa pun jika diminta.
Gunakan portal Azure untuk mengunggah paket aplikasi untuk PersistOutputsTask. Sertakan PersistOutputsTask.exe dan rakitan dependennya dalam paket .zip, tetapkan ID aplikasi ke "PersistOutputsTask", dan versi paket aplikasi ke "1.0".
Mulai (jalankan) proyek PersistOutputs.
Saat diminta untuk memilih menggunakan teknologi yang tahan lama untuk menjalankan sampel, masukkan 2 untuk menjalankan sampel menggunakan API layanan Batch untuk menyimpan output tugas.
Jika ingin, jalankan sampel lagi, dengan memasukkan 3untuk menyimpan output dengan API layanan Batch, serta untuk memberi nama kontainer tujuan dan jalur blob sesuai dengan standar Konvensi File.

Langkah berikutnya

Untuk mempelajari selengkapnya tentang menyimpan output tugas dengan pustaka Konvensi File untuk .NET, lihat Menyimpan data tugas dan pekerjaan ke Azure Storage dengan pustaka Konvensi File Batch untuk .NET.
Untuk mempelajari tentang pendekatan lain untuk menyimpan data output di Azure Batch, lihat Menyimpan pekerjaan dan output tugas di Azure Storage.

Share via