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

Artikel
07/27/2022
12 menit untuk membaca

BERLAKU UNTUK: Azure Data Factory Azure Synapse Analytics

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

Artikel ini menggunakan modul Azure Az PowerShell, yang merupakan modul PowerShell yang direkomendasikan untuk berinteraksi dengan Azure. Untuk mulai menggunakan modul Az PowerShell, lihat Menginstal Azure PowerShell. 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.

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	Diperlukan
nama	Nama aktivitas dalam alur	Ya
deskripsi	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
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 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.

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).

Membandingkan Aktivitas Kustom v2 dan Aktivitas DotNet versi 1 (Kustom)

Di Azure Data Factory versi 1, Anda menerapkan Aktivitas DotNet (Kustom) dengan membuat proyek .NET Class Library dengan kelas yang mengimplementasikan metode Execute dalam antarmuka IDotNetActivity. Layanan Tertaut, Set Data, dan Properti yang Diperluas dalam muatan JSON dari Aktivitas DotNet (Kustom) diteruskan ke metode eksekusi sebagai objek yang diketik dengan kuat. Untuk detail tentang perilaku versi 1, lihat (Kustom) DotNet di versi 1. Karena implementasi ini, kode Aktivitas DotNet versi 1 Anda harus menargetkan .NET Framework 4.5.2. Aktivitas DotNet versi 1 juga harus dieksekusi pada node Azure Batch Pool berbasis Windows.

Di Aktivitas Kustom alur Azure Data Factory V2 dan Synapse, Anda tidak diharuskan untuk mengimplementasikan antarmuka .NET. Anda dapat langsung menjalankan perintah, skrip, dan kode kustom yang dikompilasi sebagai dapat dieksekusi. Untuk mengonfigurasi implementasi ini, Anda menentukan properti Command bersama-sama dengan propertifolderPath. Aktivitas Kustom mengunggah executable dan dependensinya ke folderpath dan menjalankan perintah untuk Anda.

Layanan Tertaut, Himpunan data (didefinisikan dalam referenceObjects), dan Properti yang Diperluas yang ditentukan dalam payload JSON dari Aktivitas Kustom alur Data Factory v2 atau Synapse dapat diakses oleh executable Anda sebagai file JSON. Anda dapat mengakses properti yang diperlukan menggunakan serializer JSON seperti yang ditunjukkan pada SampleApp.exe kode sebelumnya.

Dengan perubahan yang diperkenalkan di Aktivitas Kustom alur Data Factory V2 dan Synapse, Anda dapat menulis logika kode kustom Anda dalam bahasa pilihan Anda dan menjalankannya di Sistem Operasi Windows dan Linux yang didukung oleh Azure Batch.

Tabel berikut menjelaskan perbedaan antara Aktivitas Kustom alur Data Factory V2 dan Synapse dan Aktivitas DotNet versi Data Factory 1 (Kustom):

Perbedaan	Aktivitas Kustom	Aktivitas DotNet versi 1 (Kustom)
Bagaimana logika kustom didefinisikan	Dengan menyediakan executable	Dengan mengimplementasikan DLL .NET
Lingkungan eksekusi logika kustom	\- Windows atau Linux	Windows (.NET Framework 4.5.2)
Mengeksekusi skrip	Mendukung mengeksekusi skrip secara langsung (misalnya "cmd / c gema halo dunia" pada Windows VM)	Membutuhkan implementasi dalam DLL .NET
Set data diperlukan	Opsional	Diperlukan untuk merantai aktivitas dan menyampaikan informasi
Meneruskan informasi dari aktivitas ke logika kustom	Melalui ReferenceObjects (LinkedServices and Datasets) dan ExtendedProperties (properti kustom)	Melalui ExtendedProperties (properti kustom), Input, dan Output Dataset
Mengambil informasi dalam logika kustom	Parses activity.jsmenyala, linkedServices.jsmenyala, dan datasets.jsdisimpan dalam folder yang sama dari executable	Through .NET SDK (.NET Frame 4.5.2)
Pencatatan	Menulis langsung ke STDOUT	Menerapkan Logger dalam DLL .NET

Jika Anda memiliki kode .NET yang ada yang ditulis untuk Aktivitas DotNet versi 1 (Kustom), Anda perlu mengubah kode agar kode tersebut berfungsi dengan versi Aktivitas Kustom saat ini. Perbarui kode Anda dengan mengikuti panduan tingkat tinggi ini:

Ubah project dari Library Kelas .NET menjadi Aplikasi Konsol.
Mulai aplikasi Anda dengan metode Main ini. ExecuteMetode antarmuka IDotNetActivity tidak lagi diperlukan.
Baca danuraikan Layanan, Set Data, dan Aktivitas Tertaut dengan serializer JSON, dan bukan objek yang diketik kuat. Berikan nilai properti yang diperlukan ke logika kode kustom utama Anda. Lihat kode SampleApp.exe sebelumnya sebagai contoh.
Obyek Pencatat tak lagi didukung. Output dari executable Anda dapat dicetak ke konsol dan disimpan ke stdout.txt.
Paket Microsoft.Azure.Management.DataFactories NuGet tidak lagi diperlukan.
Kumpulkan kode Anda, unggah executable dan dependensinya ke Microsoft Azure Storage, dan tentukan jalur di folderPath properti.

Untuk contoh lengkap tentang bagaimana DLL ujung ke ujung dan contoh alur yang dijelaskan dalam artikel Data Factory versi 1 Menggunakan aktivitas khusus dalam alur Azure Data Factory dapat ditulis ulang sebagai Aktivitas Khusus untuk alur Data Factory v2 dan Synapse, lihat Sampel Aktivitas Kustom.

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.

Langkah berikutnya

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