Azure Data Factory veya Azure Synapse Analytics işlem hattında özel etkinlikleri kullanma

Makale
12/09/2023

UYGULANANLAR: Azure Data Factory Azure Synapse Analytics

Bahşiş

Kuruluşlar için hepsi bir arada analiz çözümü olan Microsoft Fabric'te Data Factory'yi deneyin. Microsoft Fabric , veri taşımadan veri bilimine, gerçek zamanlı analize, iş zekasına ve raporlamaya kadar her şeyi kapsar. Yeni bir deneme sürümünü ücretsiz olarak başlatmayı öğrenin!

Azure Data Factory veya Synapse işlem hattında kullanabileceğiniz iki tür etkinlik vardır.

Verileri desteklenen kaynak ve havuz veri depoları arasında taşımak için veri taşıma etkinlikleri.
Azure HDInsight ve Azure Batch gibi işlem hizmetlerini kullanarak verileri dönüştürmeye yönelik veri dönüştürme etkinlikleri .

Hizmetin desteklemediği bir veri deposuna/deposundan veri taşımak veya verileri hizmet tarafından desteklenmeyen bir şekilde dönüştürmek/işlemek için kendi veri taşıma veya dönüştürme mantığınızla Özel etkinlik oluşturabilir ve etkinliği işlem hattında kullanabilirsiniz. Özel etkinlik, özelleştirilmiş kod mantığınızı sanal makinelerden oluşan bir Azure Batch havuzunda çalıştırır.

Dekont

Azure ile etkileşim kurmak için Azure Az PowerShell modülünü kullanmanızı öneririz. Başlamak için bkz. Azure PowerShell'i yükleme. Az PowerShell modülüne nasıl geçeceğinizi öğrenmek için bkz. Azure PowerShell’i AzureRM’den Az’ye geçirme.

Azure Batch hizmetinde yeniyseniz aşağıdaki makalelere bakın:

Azure Batch hizmetine genel bakış için Azure Batch ile ilgili temel bilgiler .
New-AzBatchAccount cmdlet'i, Azure portalını kullanarak Azure Batch hesabı oluşturmak üzere bir Azure Batch hesabı (veya) Azure portalı oluşturmak için kullanılır. Cmdlet'ini kullanma hakkında ayrıntılı yönergeler için Bkz . Azure Batch Hesabını yönetmek için PowerShell kullanma makalesi.
Azure Batch havuzu oluşturmak için New-AzBatchPool cmdlet'i.

Önemli

Yeni bir Azure Batch havuzu oluştururken 'VirtualMachineConfiguration' kullanılmalıdır ve 'CloudServiceConfiguration' kullanılmamalıdır. Daha fazla ayrıntı için Bkz . Azure Batch Havuzu geçiş kılavuzu.

Kullanıcı arabirimiyle işlem hattına özel etkinlikler ekleme

İşlem hattında Özel etkinlik kullanmak için aşağıdaki adımları tamamlayın:

İşlem hattı Etkinlikleri bölmesinde Özel'i arayın ve özel etkinliği işlem hattı tuvaline sürükleyin.
Henüz seçili değilse tuvaldeki yeni Özel etkinliği seçin.
Özel etkinliği yürütecek yeni bir Azure Batch bağlı hizmeti seçmek veya oluşturmak için Azure Batch sekmesini seçin.
Ayarlar sekmesini seçin ve Azure Batch'te yürütülecek komutu ve isteğe bağlı gelişmiş ayrıntıları belirtin.

Azure Batch bağlı hizmeti

Aşağıdaki JSON örnek bir Azure Batch bağlı hizmetini tanımlar. Ayrıntılar için bkz . Desteklenen işlem ortamları

{
    "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"
            }
        }
    }
}

Azure Batch bağlı hizmeti hakkında daha fazla bilgi edinmek için bağlı hizmetleri hesaplama makalesine bakın.

Özel etkinlik

Aşağıdaki JSON kod parçacığı, basit bir Özel Etkinlik ile bir işlem hattı tanımlar. Etkinlik tanımının Azure Batch bağlı hizmetine bir başvurusu vardır.

{
  "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"
        }
      }
    }]
  }
}

Bu örnekte helloworld.exe, resourceLinkedService içinde kullanılan Azure Depolama hesabının customactv2/helloworld klasöründe depolanan özel bir uygulamadır. Özel etkinliği bu özel uygulamayı Azure Batch'te yürütülmek üzere gönderir. komutunu, Azure Batch Havuzu düğümlerinin hedef İşlem Sisteminde yürütülebilecek tercih edilen herhangi bir uygulamayla değiştirebilirsiniz.

Aşağıdaki tabloda, bu etkinliğe özgü özelliklerin adları ve açıklamaları açıklanmaktadır.

Özellik	Açıklama	Gerekli
name	İşlem hattındaki etkinliğin adı	Evet
açıklama	Etkinliğin ne yaptığını açıklayan metin.	No
type	Özel etkinlik için etkinlik türü Özel'dir.	Evet
linkedServiceName	Azure Batch'e Bağlı Hizmet. Bu bağlı hizmet hakkında bilgi edinmek için bkz . Bağlı hizmetleri hesaplama makalesi.	Evet
komut	Yürütülecek özel uygulamanın komutu. Uygulama Azure Batch Havuzu Düğümünde zaten kullanılabiliyorsa resourceLinkedService ve folderPath atlanabilir. Örneğin, windows Batch Pool düğümü tarafından yerel olarak desteklenen komutu olarak `cmd /c dir`belirtebilirsiniz.	Evet
resourceLinkedService	Özel uygulamanın depolandığı Depolama hesabına Azure Depolama Bağlı Hizmeti	No*
folderPath	Özel uygulamanın klasörünün yolu ve tüm bağımlılıkları Alt klasörlerde depolanan bağımlılıklarınız varsa (yani folderPath altındaki hiyerarşik bir klasör yapısında) dosyalar Azure Batch'e kopyalandığında klasör yapısı şu anda düzleştirilmiştir. Diğer bir ifadeyle, tüm dosyalar alt klasörü olmayan tek bir klasöre kopyalanır. Bu davranışa geçici bir çözüm olarak, dosyaları sıkıştırmayı, sıkıştırılmış dosyayı kopyalamayı ve ardından istenen konumda özel kodla sıkıştırmayı göz önünde bulundurun.	No*
referenceObjects	Mevcut Bağlı Hizmetler ve Veri Kümeleri dizisi. Başvuruda bulunan Bağlı Hizmetler ve Veri Kümeleri JSON biçiminde özel uygulamaya geçirilir, böylece özel kodunuz hizmetin kaynaklarına başvurabilir	No
extendedProperties	Özel kodunuzun ek özelliklere başvurabilmesi için özel uygulamaya JSON biçiminde geçirilebilen kullanıcı tanımlı özellikler	No
retentionTimeInDays	Özel etkinlik için gönderilen dosyaların bekletme süresi. Varsayılan değer 30 gündür.	No

* ve özellikleri resourceLinkedServicefolderPath belirtilmeli veya her ikisi de atlanmalıdır.

Dekont

Bağlı hizmetleri Özel Etkinlik'te referenceObjects olarak geçiriyorsanız, Azure Key Vault özellikli bir bağlı hizmeti (güvenli dize içermediğinden) geçirmek ve koddan doğrudan Key Vault'tan gizli dizi adı kullanarak kimlik bilgilerini getirmek iyi bir güvenlik uygulamasıdır. Burada AKV özellikli bağlı hizmete başvuran, Key Vault'tan kimlik bilgilerini alan ve ardından koddaki depolama alanına erişen bir örnek bulabilirsiniz.

Dekont

Şu anda özel etkinlikte resourceLinkedService için yalnızca Azure Blob depolama desteklenir ve varsayılan olarak oluşturulan tek bağlı hizmettir ve ADLS 2. Nesil gibi diğer bağlayıcıları seçme seçeneği yoktur.

Özel etkinlik izinleri

Özel etkinlik, Azure Batch otomatik kullanıcı hesabını görev kapsamıyla yönetici olmayan erişim (varsayılan otomatik kullanıcı belirtimi) olarak ayarlar. Otomatik kullanıcı hesabının izin düzeyini değiştiremezsiniz. Daha fazla bilgi için bkz . Batch'te kullanıcı hesapları altında görevleri çalıştırma | Otomatik kullanıcı hesapları.

Komutları yürütme

Özel Etkinlik'i kullanarak doğrudan bir komut yürütebilirsiniz. Aşağıdaki örnek, hedef Azure Batch Havuzu düğümlerinde "echo hello world" komutunu çalıştırır ve çıkışı stdout'a yazdırır.

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

Nesneleri ve özellikleri geçirme

Bu örnek, hizmetten özel uygulamanıza nesneleri ve kullanıcı tanımlı özellikleri geçirmek için referenceObjects ve extendedProperties özelliklerini nasıl kullanabileceğinizi gösterir.

{
  "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"
        }
      }
    }]
  }
}

Etkinlik yürütülürken referenceObjects ve extendedProperties, SampleApp.exe dosyasının aynı yürütme klasörüne dağıtılan aşağıdaki dosyalarda depolanır:

activity.json

Özel etkinliğin extendedProperties ve özelliklerini depolar.
linkedServices.json

referenceObjects özelliğinde tanımlanan Bağlı Hizmetler dizisini depolar.
datasets.json

referenceObjects özelliğinde tanımlanan veri kümeleri dizisini depolar.

Aşağıdaki örnek kod, SampleApp.exe dosyasının JSON dosyalarından gerekli bilgilere nasıl erişebileceğini gösterir:

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);
        }
    }
}

Yürütme çıkışlarını alma

Aşağıdaki PowerShell komutunu kullanarak bir işlem hattı çalıştırması başlatabilirsiniz:

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

İşlem hattı çalışırken, aşağıdaki komutları kullanarak yürütme çıkışını de kontrol edebilirsiniz:

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"

Özel uygulamanızın stdout ve stderr'ı, görevin GUID'siyle Azure Batch Bağlı Hizmeti oluştururken tanımladığınız Azure Depolama Bağlı Hizmeti'ndeki adfjobs kapsayıcısına kaydedilir. Aşağıdaki kod parçacığında gösterildiği gibi Etkinlik Çalıştırması çıkışından ayrıntılı yolu alabilirsiniz:

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"

Aşağı akış etkinliklerinde stdout.txt dosyasının içeriğini kullanmak isterseniz, "@activity('MyCustomActivity').output.outputs[0]" ifadesinde stdout.txt dosyasının yolunu alabilirsiniz.

Önemli

activity.json, linkedServices.json ve datasets.json, Batch görevinin çalışma zamanı klasöründe depolanır. Bu örnekte activity.json, linkedServices.json ve datasets.json yolu içinde https://adfv2storage.blob.core.windows.net/adfjobs/<GUID>/runtime/ depolanır. Gerekirse, bunları ayrı ayrı temizlemeniz gerekir.
Şirket İçinde Barındırılan Tümleştirme Çalışma Zamanı'nı kullanan Bağlı Hizmetler için anahtarlar veya parolalar gibi hassas bilgiler, kimlik bilgilerinin müşteri tanımlı özel ağ ortamında kalmasını sağlamak için Şirket İçinde Barındırılan Tümleştirme Çalışma Zamanı tarafından şifrelenir. Özel uygulama kodunuz tarafından bu şekilde başvurulduğunda bazı hassas alanlar eksik olabilir. Gerekirse Bağlı Hizmet başvurusunu kullanmak yerine extendedProperties içinde SecureString kullanın.

Çıkışları başka bir etkinliğe geçirme

Özel Etkinlikteki kodunuzdaki özel değerleri hizmete geri gönderebilirsiniz. Bunu, uygulamanızdan içine yazarak outputs.json yapabilirsiniz. Hizmet içeriğini outputs.json kopyalar ve özelliğin değeri olarak Etkinlik Çıkışına customOutput ekler. (Boyut sınırı 2 MB'tır.) öğesinin içeriğini outputs.json aşağı akış etkinliklerinde kullanmak istiyorsanız, ifadesini @activity('<MyCustomActivity>').output.customOutputkullanarak değerini alabilirsiniz.

SecureString çıkışlarını alma

Bu makaledeki örneklerden bazılarında gösterildiği gibi SecureString türü olarak belirlenen hassas özellik değerleri, kullanıcı arabirimindeki İzleme sekmesinde maskelenir. Ancak gerçek işlem hattı yürütmesinde SecureString özelliği, dosya içinde activity.json düz metin olarak JSON olarak serileştirilir. Örneğin:

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

Bu serileştirme gerçekten güvenli değildir ve güvenli olması amaçlanmamıştır. Amaç, hizmetin İzleme sekmesindeki değeri maskelemeye yönelik bir ipucudur.

Özel bir etkinlikten SecureString türündeki özelliklere erişmek için, .EXE'nizle aynı klasöre yerleştirilen dosyayı okuyunactivity.json, JSON'un serisini kaldırın ve ardından JSON özelliğine erişin (extendedProperties => [propertyName] => value).

Azure Batch'in otomatik ölçeklendirmesi

Otomatik ölçeklendirme özelliğine sahip bir Azure Batch havuzu da oluşturabilirsiniz. Örneğin, bekleyen görevlerin sayısına göre 0 ayrılmış VM ve otomatik ölçeklendirme formülü içeren bir Azure toplu iş havuzu oluşturabilirsiniz.

Buradaki örnek formül şu davranışa ulaşır: Havuz ilk oluşturulduğunda 1 VM ile başlar. $PendingTasks ölçüm, çalışma + etkin (kuyruğa alınmış) durumdaki görev sayısını tanımlar. Formül, son 180 saniye içinde bekleyen görevlerin ortalama sayısını bulur ve TargetDedicated'ı buna göre ayarlar. TargetDedicated'ın hiçbir zaman 25 VM'nin ötesine geçmemesini sağlar. Bu nedenle, yeni görevler gönderildikçe havuz otomatik olarak büyür ve görevler tamamlandıkça VM'ler birer birer serbest hale gelir ve otomatik ölçeklendirme bu VM'leri küçültür. startingNumberOfVMs ve maxNumberofVMs gereksinimlerinize göre ayarlanabilir.

Otomatik ölçeklendirme formülü:

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

Ayrıntılar için bkz . Azure Batch havuzunda işlem düğümlerini otomatik olarak ölçeklendirme.

Havuz varsayılan autoScaleEvaluationInterval kullanıyorsa, Batch hizmetinin özel etkinliği çalıştırmadan önce VM'yi hazırlaması 15-30 dakika sürebilir. Havuz farklı bir autoScaleEvaluationInterval kullanıyorsa Batch hizmeti otomatikScaleEvaluationInterval + 10 dakika sürebilir.

Verileri başka şekillerde dönüştürmeyi açıklayan aşağıdaki makalelere bakın:

Azure Data Factory veya Azure Synapse Analytics işlem hattında özel etkinlikleri kullanma

Kullanıcı arabirimiyle işlem hattına özel etkinlikler ekleme

Azure Batch bağlı hizmeti

Özel etkinlik

Özel etkinlik izinleri

Komutları yürütme

Nesneleri ve özellikleri geçirme

Yürütme çıkışlarını alma

Çıkışları başka bir etkinliğe geçirme

SecureString çıkışlarını alma

Azure Batch'in otomatik ölçeklendirmesi

İlgili içerik

Ek kaynaklar