Menggunakan aktivitas kustom dalam alur Azure Data Factory atau Azure Synapse Analytics

Azure Data Factory Azure Synapse Analytics

Kiat

Data Factory di Microsoft Fabric adalah generasi Azure Data Factory berikutnya, dengan arsitektur yang lebih sederhana, AI bawaan, dan fitur baru. Jika Anda baru menggunakan integrasi data, mulailah dengan Fabric Data Factory. Beban kerja ADF yang ada dapat ditingkatkan ke Fabric untuk mengakses kemampuan baru di seluruh ilmu data, analitik real time, dan pelaporan.

Ada dua jenis aktivitas yang dapat Anda gunakan dalam 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 dan Azure Batch.

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 komputer virtual Azure Batch.

Catatan

Kami menyarankan agar Anda menggunakan modul Az PowerShell Azure untuk berinteraksi dengan Azure. Untuk memulai, lihat Install Azure PowerShell. Untuk mempelajari cara bermigrasi ke modul Az PowerShell, lihat Migrasikan Azure PowerShell dari AzureRM ke Az.

Lihat artikel berikut jika Anda baru dengan layanan Azure Batch:

Dasar-dasar Azure Batch sebagai gambaran umum dari layanan Azure Batch.
cmdlet New-AzBatchAccount untuk membuat akun Azure Batch (atau) portal Azure untuk membuat akun Azure Batch menggunakan portal Azure. Lihat artikel Gunakan PowerShell untuk mengelola Akun Azure Batch untuk instruksi terperinci tentang menggunakan cmdlet.
cmdlet New-AzBatchPool untuk membuat kumpulan Azure Batch.

Penting

Saat membuat kumpulan Azure Batch baru, 'VirtualMachineConfiguration' harus digunakan dan BUKAN 'CloudServiceConfiguration'.

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 Settings dan tentukan perintah yang akan dijalankan pada Azure Batch, dan detail lanjutan opsional.

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 informasi lebih lanjut tentang layanan tertaut Azure Batch, lihat artikel layanan tertaut Compute.

Kegiatan Khusus

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 Azure Storage yang digunakan dalam resourceLinkedService. Aktivitas Kustom mengirimkan aplikasi kustom ini untuk dijalankan pada Azure Batch. Anda dapat mengganti perintah ke aplikasi pilihan apa pun yang dapat dijalankan pada Sistem Operasi target simpul kumpulan Azure Batch.

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

Properti	Deskripsi	Wajib
nama	Nama aktivitas di dalam alur	Ya
deskripsi	Teks yang menjelaskan apa yang dikerjakan oleh aktivitas.	Tidak
jenis	Untuk Aktivitas kustom, jenis aktivitasnya adalah Kustom.	Ya
namaLayananTerkait	Layanan Tertaut ke Azure Batch. Untuk mempelajari layanan tertaut ini, lihat artikel Layanan tertaut komputasi.	Ya
perintah	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 menjadi `cmd /c dir`, yang didukung secara bawaan oleh node Windows Batch Pool.	Ya
resourceLinkedService	Layanan Azure Storage Terhubung 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 *
objek referensi	Sekumpulan 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
waktuPenyimpananDalamHari	Waktu penyimpanan untuk file yang dikirimkan untuk aktivitas kustom. Nilai defaultnya adalah 30 hari.	Tidak

* Properti resourceLinkedService dan folderPath harus ditentukan bersama-sama atau dihilangkan bersama-sama.

Catatan

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

Catatan

Saat ini hanya Azure Blob Storage yang didukung untuk resourceLinkedService dalam aktivitas khusus, dan layanan tertaut ini adalah satu-satunya 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 cakupan 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 target di kumpulan Azure Batch 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 dari aplikasi kustom Anda disimpan dalam kontainer adfjobs di layanan yang tertaut dengan Azure Storage yang Anda tentukan saat membuat layanan yang tertaut dengan Azure Batch menggunakan GUID dari 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 Self-Hosted Integration Runtime, informasi sensitif seperti kunci atau kata sandi dienkripsi oleh Self-Hosted Integration Runtime untuk memastikan kredensial tetap berada di lingkungan jaringan privat 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 bertambah dan ketika tugas selesai, VM menjadi tersedia satu per satu dan autoscaling mengurangi jumlah 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 Memperbesar skala simpul komputasi secara otomatis dalam kumpulan Azure Batch untuk informasi lebih lanjut.

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 memakan waktu autoScaleEvaluationInterval + 10 menit.

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

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-07

Menggunakan aktivitas kustom dalam alur Azure Data Factory atau Azure Synapse Analytics

Menambahkan aktivitas kustom ke alur dengan antarmuka pengguna

layanan tertaut Azure Batch

Kegiatan Khusus

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

Saran dan Komentar

Sumber Daya Tambahan: