Mempertahankan data tugas ke Azure Storage dengan API layanan Batch

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 dari simpul komputasi Batch, tetapi semua data pada simpul akan hilang ketika di-image ulang atau ketika simpul keluar dari kumpulan. Tugas mungkin juga memiliki periode retensi file, setelah file yang dibuat oleh tugas dihapus. Untuk alasan ini, penting untuk mempertahankan output tugas yang akan Anda perlukan nanti ke penyimpanan data seperti Azure Storage.

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

API layanan Batch mendukung menyimpan data keluaran ke Azure Storage untuk tugas dan tugas manajer pekerjaan yang berjalan pada kumpulan dengan Konfigurasi Mesin Virtual. Saat menambahkan tugas, Anda dapat menentukan kontainer di Azure Storage sebagai tujuan untuk output tugas. Layanan Batch kemudian menulis data output apa pun ke kontainer tersebut ketika tugas selesai.

Saat menggunakan API layanan Batch untuk mempertahankan output tugas, Anda tidak perlu mengubah aplikasi yang dijalankan tugas. Sebagai gantinya, dengan beberapa modifikasi pada aplikasi klien, Anda dapat mempertahankan output tugas dari dalam kode yang sama yang membuat tugas.

Penting

Menyimpan data tugas ke Azure Storage dengan API layanan Batch tidak berfungsi untuk pool yang dibuat sebelum 1 Februari 2018.

Kapan saya menggunakan API layanan Batch untuk mempertahankan output tugas?

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

  • Anda ingin menulis kode untuk mempertahankan output tugas dari dalam aplikasi klien Anda, tanpa memodifikasi aplikasi yang dijalankan tugas Anda.
  • Anda ingin menyimpan output dari tugas Batch dan pengelola tugas di kumpulan yang dibuat dengan konfigurasi mesin virtual.
  • Anda ingin menyimpan output ke kontainer Azure Storage dengan nama sembarang.
  • Anda ingin menyimpan output ke kontainer Azure Storage yang dinamai sesuai 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 data keluaran, pertimbangkan untuk menggunakan library Batch File Conventions yang tersedia untuk .NET. Untuk bahasa lain, Anda harus menerapkan solusi Anda sendiri. Untuk informasi selengkapnya tentang opsi lain, lihat Mempertahankan output pekerjaan dan tugas ke Azure Storage.

Membuat kontainer di Azure Storage

Untuk mempertahankan output tugas ke Azure Storage, Anda harus membuat kontainer yang berfungsi sebagai tujuan untuk file output Anda. Buat kontainer sebelum Anda menjalankan tugas, 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 Anda di C#, gunakan pustaka klien Azure Storage untuk .NET. Contoh berikut menunjukkan cara membuat kontainer:

BlobContainerClient container = storageAccount.GetBlobContainerClient(containerName);
await container.CreateIfNotExistsAsync();

Tentukan berkas keluaran untuk tugas

Untuk menentukan file output untuk tugas, buat kumpulan objek OutputFile dan tetapkan ke properti BatchTaskCreateOptions.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 yang didelegasikan ke kontainer. SAS memberikan akses dengan sekumpulan izin tertentu dan 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 di mana SAS valid. Untuk menggunakan SAS untuk mengakses kontainer di Azure Storage, Anda perlu menambahkan string token SAS ke URI sumber daya. URI sumber daya, bersama dengan token SAS yang ditambahkan, menyediakan akses terautentikasi ke Azure Storage.

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

BlobSasBuilder sasBuilder = new BlobSasBuilder(BlobContainerSasPermissions.Write, DateTimeOffset.UtcNow.AddDays(1))
{
    BlobContainerName = container.Name,
    Resource = "c"
};

Uri containerSasUrl = container.GenerateSasUri(sasBuilder);

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

BatchTaskCreateOptions task = new BatchTaskCreateOptions(taskId,
    "cmd /v:ON /c \"echo off && set && (FOR /L %i IN (1,1,100000) DO (ECHO !RANDOM!)) > output.txt\"")
{
    OutputFiles =
    {
        new OutputFile(
            filePattern: @"..\std*.txt",
            destination: new OutputFileDestination()
            {
                Container = new OutputFileBlobContainerDestination(containerSasUri) { Path = taskId }
            },
            uploadOptions: new OutputFileUploadConfig(OutputFileUploadCondition.TaskCompletion)),
        new OutputFile(
            filePattern: @"output.txt",
            destination: new OutputFileDestination()
            {
                Container = new OutputFileBlobContainerDestination(containerSasUri) { Path = taskId + @"\output.txt" }
            },
            uploadOptions: new OutputFileUploadConfig(OutputFileUploadCondition.TaskCompletion)),
    }
};

Nota

Jika menggunakan contoh ini dengan Linux, pastikan untuk mengubah garis miring terbalik menjadi garis miring maju.

Menggunakan Identitas Terkelola

Alih-alih menghasilkan dan meneruskan 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 memiliki Storage Blob Data Contributor penetapan peran untuk kontainer yang akan ditulis. Layanan Batch kemudian dapat diberitahu untuk menggunakan identitas terkelola alih-alih SAS untuk mengautentikasi akses ke kontainer.

BatchTaskCreateOptions task = new BatchTaskCreateOptions(taskId,
    "cmd /v:ON /c \"echo off && set && (FOR /L %i IN (1,1,100000) DO (ECHO !RANDOM!)) > output.txt\"")
{
    OutputFiles =
    {
        new OutputFile(
            filePattern: @"..\std*.txt",
            destination: new OutputFileDestination()
            {
                Container = new OutputFileBlobContainerDestination(containerUri)
                {
                    Path = taskId,
                    IdentityReference = new BatchNodeIdentityReference()
                    {
                        ResourceId = new ResourceIdentifier(identityResourceId)
                    }
                }
            },
            uploadOptions: new OutputFileUploadConfig(OutputFileUploadCondition.TaskCompletion)),
    }
};

Tentukan pola file untuk pencocokan

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

Properti FilePattern mendukung wildcard sistem file standar seperti * (untuk kecocokan non-rekursif) dan ** (untuk kecocokan rekursif). Misalnya, sampel kode di atas menentukan pola file agar cocok std*.txt secara non-rekursif:

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

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

filePattern: @"output.txt"

Tentukan kondisi unggahan

Properti OutputFileUploadConfig.UploadCondition mengizinkan pengunggahan bersyarat file output. Skenario umum adalah mengunggah satu set file jika tugas berhasil, dan serangkaian file yang berbeda jika gagal. Misalnya, Anda mungkin ingin mengunggah file log terperinci hanya ketika tugas gagal dan keluar dengan kode keluar bukan nol. 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 mengatur properti UploadCondition ke TaskCompletion. Pengaturan ini menentukan bahwa file akan diunggah setelah tugas selesai, terlepas dari nilai kode keluar.

uploadCondition: OutputFileUploadCondition.TaskCompletion

Untuk pengaturan lain, lihat enum OutputFileUploadCondition .

Buat berbeda file dengan nama yang sama

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

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

Jika properti FilePattern diatur ke ekspresi wildcard, maka semua file yang cocok dengan pola tersebut diunggah ke direktori virtual yang ditentukan oleh properti Path. Misalnya, jika kontainer adalah mycontainer, ID tugas adalah mytask, dan pola file 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 diatur untuk mencocokkan satu nama file, artinya tidak berisi karakter kartubebas, 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, atur properti Jalur untuk menyertakan ID tugas, karakter pemisah (biasanya garis miring), dan nama file:

path: taskId + @"/output.txt"

URI absolut ke file output untuk serangkaian tugas akan mirip 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).

Menganalisis kesalahan unggahan berkas

Jika mengunggah file output ke Azure Storage gagal, maka tugas berpindah ke status Completed dan properti BatchTaskExecutionInfo.FailureInfo diatur. Periksa properti FailureInformation untuk menentukan 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. Dalam kasus di mana unggahan file tidak pernah dicoba, misalnya karena tugas itu sendiri tidak dapat dijalankan, maka file log ini tidak akan ada.

Mendiagnosis performa unggahan file

File fileuploadout.txt mencatat kemajuan unggahan. Anda dapat memeriksa file ini untuk mempelajari lebih lanjut tentang berapa lama unggahan file Anda berlangsung. Perlu diingat bahwa ada banyak faktor yang berkontribusi untuk mengunggah performa, termasuk ukuran simpul, aktivitas lain pada node pada saat pengunggahan, apakah kontainer target berada di wilayah yang sama dengan kumpulan Batch, berapa banyak simpul yang diunggah ke akun penyimpanan pada saat yang sama, dan sebagainya.

Gunakan API layanan Batch dengan standar Konvensi File Batch

Saat Anda mempertahankan output tugas dengan API layanan Batch, Anda dapat memberi nama kontainer tujuan dan blob sesuka Anda. Anda juga dapat memilih untuk memberi nama 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 Konvensi File untuk penamaan file output, maka file output Anda tersedia untuk dilihat di portal Microsoft Azure.

Jika Anda mengembangkan di C#, Anda dapat menggunakan metode yang disertakan 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, berdasarkan nama pekerjaan:

// Convention used by Azure.Batch.Conventions.Files: "job-{jobId}".
string containerName = $"job-{jobId.ToLowerInvariant()}";

Anda dapat menggunakan metode CloudJobExtensions.GetOutputStorageContainerUrl untuk mengembalikan URL tanda tangan akses bersama (SAS) yang digunakan untuk menulis ke 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 mempertahankan output tugas ke penyimpanan yang tahan lama. Untuk menjalankan sampel, ikuti langkah-langkah berikut:

  1. Buka proyek di Visual Studio 2019.
  2. Tambahkan kredensial akun Batch dan Storage Anda ke AccountSettings.settings di proyek Microsoft.Azure.Batch.Samples.Common.
  3. Bangun (tetapi jangan jalankan) solusinya. Pulihkan paket NuGet apa pun jika diminta.
  4. Gunakan portal Microsoft Azure untuk mengunggah paket aplikasi untuk PersistOutputsTask. PersistOutputsTask.exe Sertakan dan rakitan dependennya dalam paket .zip, atur ID aplikasi ke "PersistOutputsTask", dan versi paket aplikasi ke "1.0".
  5. Mulai (jalankan) proyek PersistOutputs .
  6. Ketika diminta untuk memilih teknologi persistensi yang akan digunakan untuk menjalankan sampel, masukkan 2 untuk menjalankan sampel menggunakan API layanan Batch untuk mempertahankan output tugas.
  7. Jika diinginkan, jalankan sampel lagi, masukkan 3 untuk mempertahankan output dengan API layanan Batch, dan juga untuk memberi nama kontainer tujuan dan jalur blob sesuai dengan standar Konvensi File.

Langkah berikutnya

  • Last updated on