Gunakan aktivitas kustom di Azure Data Factory atau alur Azure Synapse Analytics

Artikel
12/09/2023

BERLAKU UNTUK:Azure Data Factory Azure Synapse Analytics

Tip

Cobalah Data Factory di Microsoft Fabric, solusi analitik all-in-one untuk perusahaan. Microsoft Fabric mencakup semuanya mulai dari pergerakan data hingga ilmu data, analitik real time, kecerdasan bisnis, dan pelaporan. Pelajari cara memulai uji coba baru secara gratis!

Ada dua jenis aktivitas yang bisa Anda gunakan di alur Azure Data Factory atau Synapse.

Aktivitas Pergerakan Data untuk memindahkan data antara penyimpanan data sumber dan sink yang didukung.
Aktivitas transformasi data untuk mengubah data menggunakan layanan komputasi seperti Azure HDInsight, Azure Batch, dan ML Studio (klasik).

Untuk memindahkan data ke/dari penyimpanan data yang tidak didukung oleh layanan, atau untuk mengubah/memproses data dengan cara yang tidak didukung oleh layanan, Anda dapat membuat Aktivitas khusus dengan data Anda sendiri logika gerakan atau transformasi dan menggunakan aktivitas dalam alur. Aktivitas kustom menjalankan logika kode yang disesuaikan pada kumpulan mesin virtual Azure Batch.

Catatan

Sebaiknya Anda menggunakan modul Azure Az PowerShell untuk berinteraksi dengan Azure. Lihat Menginstal Azure PowerShell untuk memulai. Untuk mempelajari cara bermigrasi ke modul Az PowerShell, lihat Memigrasikan Azure PowerShell dari AzureRM ke Az.

Lihat artikel berikut ini jika Anda baru menggunakan layanan Azure Batch:

Dasar-dasar Azure Batch untuk gambaran umum layanan Azure Batch.
Cmdlet New-AzBatchAccount untuk membuat akun Azure Batch (atau) portal Microsoft Azure untuk membuat akun Azure Batch menggunakan portal Microsoft Azure. Lihat artikel Menggunakan PowerShell untuk mengelola Akun Azure Batch untuk instruksi mendetail tentang penggunaan cmdlet.
Cmdlet New-AzBatchPool untuk membuat kumpulan Azure Batch.

Penting

Saat membuat kumpulan Azure Batch baru, 'VirtualMachineConfiguration' harus digunakan dan BUKAN 'CloudServiceConfiguration'. Untuk detail selengkapnya lihat panduan migrasi Azure Batch Pool.

Menambahkan aktivitas kustom ke alur dengan antarmuka pengguna

Untuk menggunakan aktivitas Kustom dalam alur, selesaikan langkah-langkah berikut:

Cari Kustom di panel Aktivitas alur, dan seret aktivitas Kustom ke kanvas alur.
Pilih aktivitas Kustom baru di kanvas jika belum dipilih.
Pilih tab Azure Batch untuk memilih atau membuat layanan tertaut Azure Batch baru yang akan menjalankan aktivitas kustom.
Pilih tab Pengaturan dan tentukan perintah yang akan dijalankan pada Azure Batch, dan detail lanjutan opsional.

Membuat layanan tertaut Azure Batch

JSON berikut mendefinisikan contoh layanan tertaut Azure Batch. Untuk detailnya, lihat Lingkungan komputasi yang didukung

{
    "name": "AzureBatchLinkedService",
    "properties": {
        "type": "AzureBatch",
        "typeProperties": {
            "accountName": "batchaccount",
            "accessKey": {
                "type": "SecureString",
                "value": "access key"
            },
            "batchUri": "https://batchaccount.region.batch.azure.com",
            "poolName": "poolname",
            "linkedServiceName": {
                "referenceName": "StorageLinkedService",
                "type": "LinkedServiceReference"
            }
        }
    }
}

Untuk mempelajari selengkapnya tentang layanan tertaut Azure Batch, lihat artikel Layanan komputasi yang ditautkan.

Aktivitas Kustom

Cuplikan JSON berikut mendefinisikan alur dengan Aktivitas Kustom sederhana. Definisi aktivitas memiliki referensi ke layanan tertaut Azure Batch.

{
  "name": "MyCustomActivityPipeline",
  "properties": {
    "description": "Custom activity sample",
    "activities": [{
      "type": "Custom",
      "name": "MyCustomActivity",
      "linkedServiceName": {
        "referenceName": "AzureBatchLinkedService",
        "type": "LinkedServiceReference"
      },
      "typeProperties": {
        "command": "helloworld.exe",
        "folderPath": "customactv2/helloworld",
        "resourceLinkedService": {
          "referenceName": "StorageLinkedService",
          "type": "LinkedServiceReference"
        }
      }
    }]
  }
}

Dalam sampel ini, helloworld.exe adalah aplikasi kustom yang disimpan di folder customactv2/helloworld dari akun Microsoft Azure Storage yang digunakan dalam resourceLinkedService. Aktivitas Kustom mengirimkan aplikasi kustom ini untuk dieksekusi pada Azure Batch. Anda dapat mengganti perintah ke aplikasi pilihan apa pun yang dapat dieksekusi pada Sistem Operasi target node Azure Batch Pool.

Tabel berikut ini menjelaskan nama dan deskripsi properti yang spesifik untuk aktivitas ini.

Properti	Deskripsi	Wajib
nama	Nama aktivitas di dalam alur	Ya
description	Teks yang menjelaskan apa yang dilakukan aktivitas.	Tidak
jenis	Untuk Aktivitas kustom, jenis aktivitasnya adalah Kustom.	Ya
linkedServiceName	Layanan Tertaut ke Azure Batch. Untuk mempelajari layanan tertaut ini, lihat artikel Layanan tertaut komputasi.	Ya
command	Perintah aplikasi kustom yang akan dieksekusi. Jika aplikasi sudah tersedia di Azure Batch Pool Node, resourceLinkedService dan folderPath dapat dilewati. Misalnya, Anda dapat menentukan perintah untuk menjadi `cmd /c dir`, yang secara asli didukung oleh node Pool Batch Windows.	Ya
resourceLinkedService	Layanan Tertaut Microsoft Azure Storage ke Akun penyimpanan tempat aplikasi kustom disimpan	Tidak *
folderPath	Jalur ke folder aplikasi kustom dan semua dependensinya Jika Anda memiliki dependensi yang disimpan dalam subfolder - yaitu, dalam struktur folder hierarkis di bawah folderPath - struktur folder saat ini diratakan ketika file disalin ke Azure Batch. Artinya, semua file disalin ke dalam satu folder tanpa subfolder. Untuk mengatasi perilaku ini, pertimbangkan untuk memadatkan file, menyalin file yang dikompresi, lalu membuka zip dengan kode kustom di lokasi yang diinginkan.	Tidak *
referenceObjects	Array Layanan Tertaut dan Kumpulan Data yang sudah ada. Layanan Tertaut dan Kumpulan Data yang direferensikan diteruskan ke aplikasi khusus dalam format JSON sehingga kode khusus Anda dapat mereferensikan sumber daya layanan	Tidak
extendedProperties	Properti yang ditentukan pengguna yang dapat diteruskan ke aplikasi kustom dalam format JSON sehingga kode kustom dapat mereferensikan properti tambahan	Tidak
retentionTimeInDays	Waktu penyimpanan untuk file yang dikirimkan untuk aktivitas kustom. Nilai defaultnya adalah 30 hari.	Tidak

* Properti resourceLinkedService dan folderPath keduanya harus ditentukan atau dihilangkan.

Catatan

Jika Anda melewati layanan yang ditautkan sebagai referenceObjects dalam Aktivitas Kustom, ini adalah praktik keamanan yang baik untuk meneruskan layanan tertaut dengan Azure Key Vault yang aktif (karena tidak berisi string aman) dan mengambil kredensial menggunakan nama rahasia langsung dari Key Vault dari kode. Anda dapat menemukan contoh di sini yang mereferensikan layanan tertaut yang diaktifkan AKV, mengambil kredensial dari Key Vault, lalu mengakses penyimpanan dalam kode.

Catatan

Saat ini hanya penyimpanan Azure Blob yang didukung untuk resourceLinkedService dalam aktivitas kustom, dan ini adalah satu-satunya layanan tertaut yang dibuat secara default dan tidak ada opsi untuk memilih konektor lain seperti ADLS Gen2.

Izin aktivitas kustom

Aktivitas kustom mengatur akun pengguna otomatis Azure Batch ke Akses non-admin dengan lingkup tugas (spesifikasi pengguna otomatis default). Anda tidak bisa mengubah tingkat izin akun pengguna otomatis. Untuk informasi selengkapnya, lihat Menjalankan tugas di bawah akun pengguna di Batch | Akun pengguna otomatis.

Menjalankan perintah

Anda dapat langsung menjalankan perintah menggunakan Aktivitas Kustom. Contoh berikut menjalankan perintah "echo hello world" pada node Azure Batch Pool target dan mencetak output ke stdout.

{
  "name": "MyCustomActivity",
  "properties": {
    "description": "Custom activity sample",
    "activities": [{
      "type": "Custom",
      "name": "MyCustomActivity",
      "linkedServiceName": {
        "referenceName": "AzureBatchLinkedService",
        "type": "LinkedServiceReference"
      },
      "typeProperties": {
        "command": "cmd /c echo hello world"
      }
    }]
  }
}

Melewati objek dan properti

Contoh ini menunjukkan bagaimana Anda bisa menggunakan referenceObjects dan extendedProperties untuk meneruskan objek dan properti yang ditentukan pengguna dari layanan ke aplikasi kustom Anda.

{
  "name": "MyCustomActivityPipeline",
  "properties": {
    "description": "Custom activity sample",
    "activities": [{
      "type": "Custom",
      "name": "MyCustomActivity",
      "linkedServiceName": {
        "referenceName": "AzureBatchLinkedService",
        "type": "LinkedServiceReference"
      },
      "typeProperties": {
        "command": "SampleApp.exe",
        "folderPath": "customactv2/SampleApp",
        "resourceLinkedService": {
          "referenceName": "StorageLinkedService",
          "type": "LinkedServiceReference"
        },
        "referenceObjects": {
          "linkedServices": [{
            "referenceName": "AzureBatchLinkedService",
            "type": "LinkedServiceReference"
          }]
        },
        "extendedProperties": {          
          "connectionString": {
            "type": "SecureString",
            "value": "aSampleSecureString"
          },
          "PropertyBagPropertyName1": "PropertyBagValue1",
          "propertyBagPropertyName2": "PropertyBagValue2",
          "dateTime1": "2015-04-12T12:13:14Z"
        }
      }
    }]
  }
}

Ketika aktivitas dijalankan, referenceObjects dan extendedProperties disimpan dalam file berikut yang disebarkan ke folder eksekusi yang sama dari SampleApp.exe:

activity.json

Menyimpan extendedProperties dan properti aktivitas kustom.
linkedServices.json

Menyimpan larik Layanan Tertaut yang ditentukan dalam properti referenceObjects.
datasets.json

Menyimpan larik Set Data yang ditentukan dalam properti referenceObjects.

Contoh kode berikut menunjukkan bagaimana SampleApp.exe dapat mengakses informasi yang diperlukan dari file JSON:

using Newtonsoft.Json;
using System;
using System.IO;

namespace SampleApp
{
    class Program
    {
        static void Main(string[] args)
        {
            //From Extend Properties
            dynamic activity = JsonConvert.DeserializeObject(File.ReadAllText("activity.json"));
            Console.WriteLine(activity.typeProperties.extendedProperties.connectionString.value);

            // From LinkedServices
            dynamic linkedServices = JsonConvert.DeserializeObject(File.ReadAllText("linkedServices.json"));
            Console.WriteLine(linkedServices[0].properties.typeProperties.accountName);
        }
    }
}

Ambil keluaran eksekusi

Anda bisa memulai eksekusi alur menggunakan perintah PowerShell berikut:

$runId = Invoke-AzDataFactoryV2Pipeline -DataFactoryName $dataFactoryName -ResourceGroupName $resourceGroupName -PipelineName $pipelineName

Saat alur berjalan, Anda dapat memeriksa output eksekusi menggunakan perintah berikut:

while ($True) {
    $result = Get-AzDataFactoryV2ActivityRun -DataFactoryName $dataFactoryName -ResourceGroupName $resourceGroupName -PipelineRunId $runId -RunStartedAfter (Get-Date).AddMinutes(-30) -RunStartedBefore (Get-Date).AddMinutes(30)

    if(!$result) {
        Write-Host "Waiting for pipeline to start..." -foregroundcolor "Yellow"
    }
    elseif (($result | Where-Object { $_.Status -eq "InProgress" } | Measure-Object).count -ne 0) {
        Write-Host "Pipeline run status: In Progress" -foregroundcolor "Yellow"
    }
    else {
        Write-Host "Pipeline '"$pipelineName"' run finished. Result:" -foregroundcolor "Yellow"
        $result
        break
    }
    ($result | Format-List | Out-String)
    Start-Sleep -Seconds 15
}

Write-Host "Activity `Output` section:" -foregroundcolor "Yellow"
$result.Output -join "`r`n"

Write-Host "Activity `Error` section:" -foregroundcolor "Yellow"
$result.Error -join "`r`n"

Stdout dan stderr aplikasi kustom disimpan ke kontainer adfjobs di Azure Storage Linked Service yang Anda tentukan saat membuat Azure Batch Linked Service dengan GUID tugas. Anda bisa mendapatkan jalur terperinci dari output Activity Run seperti yang ditunjukkan pada cuplikan berikut:

Pipeline ' MyCustomActivity' run finished. Result:

ResourceGroupName : resourcegroupname
DataFactoryName   : datafactoryname
ActivityName      : MyCustomActivity
PipelineRunId     : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
PipelineName      : MyCustomActivity
Input             : {command}
Output            : {exitcode, outputs, effectiveIntegrationRuntime}
LinkedServiceName :
ActivityRunStart  : 10/5/2017 3:33:06 PM
ActivityRunEnd    : 10/5/2017 3:33:28 PM
DurationInMs      : 21203
Status            : Succeeded
Error             : {errorCode, message, failureType, target}

Activity Output section:
"exitcode": 0
"outputs": [
  "https://<container>.blob.core.windows.net/adfjobs/<GUID>/output/stdout.txt",
  "https://<container>.blob.core.windows.net/adfjobs/<GUID>/output/stderr.txt"
]
"effectiveIntegrationRuntime": "DefaultIntegrationRuntime (East US)"
Activity Error section:
"errorCode": ""
"message": ""
"failureType": ""
"target": "MyCustomActivity"

Jika ingin menggunakan konten stdout.txt dalam aktivitas hilir, Anda bisa mendapatkan jalur ke file stdout.txt dalam ekspresi "@activity('MyCustomActivity').output.outputs[0]".

Penting

Perangkat activity.json, linkedServices.json, dan datasets.json disimpan di folder runtime Tugas batch. Untuk contoh ini, activity.json, linkedServices.json, dan datasets.json disimpan di jalur https://adfv2storage.blob.core.windows.net/adfjobs/<GUID>/runtime/. Jika diperlukan, Anda perlu membersihkannya secara terpisah.
Untuk Layanan Tertaut yang menggunakan Runtime Integrasi Self-Hosted, informasi sensitif seperti kunci atau kata sandi dienkripsi oleh Runtime Integrasi Self-Hosted untuk memastikan kredensial tetap berada di lingkungan jaringan pribadi yang ditentukan pelanggan. Beberapa bidang sensitif bisa hilang ketika direferensikan oleh kode aplikasi kustom dengan cara ini. Gunakan SecureString di extendedProperties alih-alih menggunakan referensi Layanan Tertaut jika diperlukan.

Meneruskan output ke aktivitas lain

Anda dapat mengirim nilai kustom dari kode Anda dalam Aktivitas Kustom kembali ke layanan. Anda dapat melakukannya dengan menulisnya ke dalam outputs.json dari aplikasi. Layanan menyalin konten outputs.json dan menambahkannya ke Output Aktivitas sebagai nilai properti customOutput. (Batas ukuran adalah 2MB.) Jika Anda ingin mengonsumsi konten outputs.json dalam kegiatan hilir, Anda bisa mendapatkan nilainya dengan menggunakan ekspresi @activity('<MyCustomActivity>').output.customOutput.

Ambil output SecureString

Nilai properti sensitif yang ditetapkan sebagai jenis SecureString, seperti yang ditunjukkan dalam beberapa contoh dalam artikel ini, disembunyikan di tab Pemantauan di antarmuka pengguna. Namun, dalam eksekusi alur aktual, properti SecureString diserialisasikan sebagai JSON dalam file activity.json sebagai teks biasa. Contohnya:

"extendedProperties": {
  "connectionString": {
    "type": "SecureString",
    "value": "aSampleSecureString"
  }
}

Serialisasi ini tidak benar-benar aman, dan tidak dimaksudkan untuk aman. Niat adalah petunjuk ke layanan untuk menutupi nilai di tab Pemantauan.

Untuk mengakses properti jenis SecureString dari aktivitas kustom, baca file activity.json, yang ditempatkan di folder yang sama dengan .EXE Anda, hapus serialisasi JSON, lalu akses properti JSON (extendedProperties => [propertyName] => nilai).

Penskalaan otomatis Azure Batch

Anda juga dapat membuat kumpulan Azure Batch dengan fitur autoscale. Misalnya, Anda dapat membuat kumpulan batch Azure dengan 0 VM khusus dan rumus skala otomatis berdasarkan jumlah tugas yang tertunda.

Contoh rumus di sini mencapai perilaku berikut: Ketika kumpulan awalnya dibuat, itu dimulai dengan 1 VM. Metrik $PendingTasks menentukan jumlah tugas dalam status berjalan dan aktif (mengantri). Rumus menghitung jumlah rata-rata tugas yang menunggu dalam 180 detik terakhir dan menetapkan TargetDedicated yang sesuai. Ini memastikan TargetDedicated tidak pernah melampaui 25 VM. Jadi, ketika tugas baru dikirimkan, kumpulan secara otomatis tumbuh dan ketika tugas selesai, VM menjadi gratis satu per satu dan autoscaling menyusutkan VM tersebut. Anda dapat menyesuaikan startingNumberOfVMs dan maxNumberofVMs dengan kebutuhan Anda.

Rumus skala otomatis:

startingNumberOfVMs = 1;
maxNumberofVMs = 25;
pendingTaskSamplePercent = $PendingTasks.GetSamplePercent(180 * TimeInterval_Second);
pendingTaskSamples = pendingTaskSamplePercent < 70 ? startingNumberOfVMs : avg($PendingTasks.GetSample(180 * TimeInterval_Second));
$TargetDedicated=min(maxNumberofVMs,pendingTaskSamples);

Lihat Menskalakan node komputasi secara otomatis di kumpulan Azure Batch untuk detailnya.

Jika kumpulan menggunakan autoScaleEvaluationIntervaldefault, layanan Batch bisa memakan waktu 15-30 menit untuk menyiapkan VM sebelum menjalankan aktivitas kustom. Jika kumpulan menggunakan autoScaleEvaluationInterval yang berbeda, layanan Batch dapat mengambil autoScaleEvaluationInterval + 10 menit.

Lihat artikel berikut yang menjelaskan cara mentransformasikan data dengan cara lain:

Gunakan aktivitas kustom di Azure Data Factory atau alur Azure Synapse Analytics

Menambahkan aktivitas kustom ke alur dengan antarmuka pengguna

Membuat layanan tertaut Azure Batch

Aktivitas Kustom

Izin aktivitas kustom

Menjalankan perintah

Melewati objek dan properti

Ambil keluaran eksekusi

Meneruskan output ke aktivitas lain

Ambil output SecureString

Penskalaan otomatis Azure Batch

Konten terkait

Sumber Daya Tambahan: