Azure İşlevleri için Azure Event Hubs tetikleyicisi

  • Makale

Bu makalede, Azure İşlevleri için Azure Event Hubs tetikleyicisi ile çalışma açıklanmaktadır. Azure İşlevleri Event Hubs için tetikleyici ve çıkış bağlamalarını destekler.

Kurulum ve yapılandırma ayrıntıları hakkında bilgi için genel bakışa bakın.

Olay hub'ı olay akışına gönderilen bir olayı yanıtlamak için işlev tetikleyicisini kullanın. Tetikleyiciyi ayarlamak için temel olay hub'ına okuma erişiminiz olmalıdır. İşlev tetiklendiğinde, işleve geçirilen ileti dize olarak yazılır.

Tüketim ve Premium planları için Event Hubs ölçeklendirme kararları Hedef Tabanlı Ölçeklendirme aracılığıyla yapılır. Daha fazla bilgi için bkz . Hedef Tabanlı Ölçeklendirme.

Azure İşlevleri tetikleyicileri kullanarak olay hub'ı olay akışına gönderilen olaylara nasıl yanıt verdiği hakkında bilgi için bkz. Event Hubs'ı Azure'daki sunucusuz işlevlerle tümleştirme.

Önemli

Bu makalede, Node.js programlama modelinin birden çok sürümünü desteklemek için sekmeler kullanılır. Genel kullanıma sunulan v4 modeli, JavaScript ve TypeScript geliştiricileri için daha esnek ve sezgisel bir deneyime sahip olacak şekilde tasarlanmıştır. v4 modelinin nasıl çalıştığı hakkında daha fazla bilgi için Azure İşlevleri Node.js geliştirici kılavuzuna bakın. v3 ile v4 arasındaki farklar hakkında daha fazla bilgi edinmek için geçiş kılavuzuna bakın.

Azure İşlevleri, Python için iki programlama modelini destekler. Bağlamalarınızı tanımlama şekliniz seçtiğiniz programlama modeline bağlıdır.

Python v2 programlama modeli, doğrudan Python işlev kodunuzda dekoratörleri kullanarak bağlamaları tanımlamanıza olanak tanır. Daha fazla bilgi için bkz . Python geliştirici kılavuzu.

Bu makale her iki programlama modelini de destekler.

Örnek

Aşağıdaki örnekte, giriş iletisi dizesinin günlüklere yazıldığı bir olay hub'ı temelinde tetiklenen bir C# işlevi gösterilmektedir:

{
    private readonly ILogger<EventHubsFunction> _logger;

    public EventHubsFunction(ILogger<EventHubsFunction> logger)
    {
        _logger = logger;
    }

    [Function(nameof(EventHubFunction))]
    [FixedDelayRetry(5, "00:00:10")]
    [EventHubOutput("dest", Connection = "EventHubConnection")]
    public string EventHubFunction(
        [EventHubTrigger("src", Connection = "EventHubConnection")] string[] input,
        FunctionContext context)
    {
        _logger.LogInformation("First Event Hubs triggered message: {msg}", input[0]);

        var message = $"Output message created at {DateTime.Now}";
        return message;
    }

Aşağıdaki örnekte Event Hubs tetikleyici TypeScript işlevi gösterilmektedir. İşlev olay meta verilerini okur ve iletiyi günlüğe kaydeder.

import { app, InvocationContext } from '@azure/functions';

export async function eventHubTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Event hub function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
    context.log('Offset =', context.triggerMetadata.offset);
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: eventHubTrigger1,
});

Olayları toplu olarak almak için, aşağıdaki örnekte gösterildiği gibi olarak ayarlayın cardinalitymany.

import { app, InvocationContext } from '@azure/functions';

export async function eventHubTrigger1(messages: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Event hub function processed ${messages.length} messages`);
    for (let i = 0; i < messages.length; i++) {
        context.log('Event hub message:', messages[i]);
        context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
        context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
        context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
    }
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: eventHubTrigger1,
});

Aşağıdaki örnekte Event Hubs tetikleyicisi JavaScript işlevi gösterilmektedir. İşlev olay meta verilerini okur ve iletiyi günlüğe kaydeder.

const { app } = require('@azure/functions');

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: (message, context) => {
        context.log('Event hub function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
        context.log('Offset =', context.triggerMetadata.offset);
    },
});

Olayları toplu olarak almak için, aşağıdaki örnekte gösterildiği gibi olarak ayarlayın cardinalitymany.

const { app } = require('@azure/functions');

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: (messages, context) => {
        context.log(`Event hub function processed ${messages.length} messages`);
        for (let i = 0; i < messages.length; i++) {
            context.log('Event hub message:', messages[i]);
            context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
            context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
            context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
        }
    },
});

PowerShell kodu şu şekildedir:

param($eventHubMessages, $TriggerMetadata)

Write-Host "PowerShell eventhub trigger function called for message array: $eventHubMessages"

$eventHubMessages | ForEach-Object { Write-Host "Processed message: $_" }

Aşağıdaki örnekte Event Hubs tetikleyici bağlaması ve bağlamayı kullanan bir Python işlevi gösterilmektedir. İşlev olay meta verilerini okur ve iletiyi günlüğe kaydeder. Örnek, v1 veya v2 Python programlama modelini kullanıp kullanmadığınıza bağlıdır.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="EventHubTrigger1")
@app.event_hub_message_trigger(arg_name="myhub", 
                               event_hub_name="<EVENT_HUB_NAME>",
                               connection="<CONNECTION_SETTING>") 
def test_function(myhub: func.EventHubEvent):
    logging.info('Python EventHub trigger processed an event: %s',
                myhub.get_body().decode('utf-8'))

Aşağıdaki örnekte Event Hubs tetikleyicisinin ileti gövdesini günlüğe kaydeden bir Event Hubs tetikleyici bağlaması gösterilmektedir.

@FunctionName("ehprocessor")
public void eventHubProcessor(
  @EventHubTrigger(name = "msg",
                  eventHubName = "myeventhubname",
                  connection = "myconnvarname") String message,
       final ExecutionContext context )
       {
          context.getLogger().info(message);
 }

Java işlevleri çalışma zamanı kitaplığındaEventHubTrigger, değeri olay hub'ından gelen parametrelerde ek açıklamayı kullanın. Bu ek açıklamalara sahip parametreler, bir olay geldiğinde işlevin çalışmasına neden olur. Bu ek açıklama kullanılarak yerel Java türleri, POJO'lar veya null atanabilir değerlerle Optional<T>kullanılabilir.

Aşağıdaki örnek, Olay'ın SystemProperties daha fazla iç içe dönük olarak kullanılması ve diğer Bağlama seçeneklerinin kapsamlı kullanımını ve Tarih hiyerarşisi olan iyi biçimlendirilmiş BlobOutput bir yol sağlamayı göstermektedir.

package com.example;
import java.util.Map;
import java.time.ZonedDateTime;

import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

/**
 * Azure Functions with Event Hub trigger.
 * and Blob Output using date in path along with message partition ID
 * and message sequence number from EventHub Trigger Properties
 */
public class EventHubReceiver {

    @FunctionName("EventHubReceiver")
    @StorageAccount("bloboutput")

    public void run(
            @EventHubTrigger(name = "message",
                eventHubName = "%eventhub%",
                consumerGroup = "%consumergroup%",
                connection = "eventhubconnection",
                cardinality = Cardinality.ONE)
            String message,

            final ExecutionContext context,

            @BindingName("Properties") Map<String, Object> properties,
            @BindingName("SystemProperties") Map<String, Object> systemProperties,
            @BindingName("PartitionContext") Map<String, Object> partitionContext,
            @BindingName("EnqueuedTimeUtc") Object enqueuedTimeUtc,

            @BlobOutput(
                name = "outputItem",
                path = "iotevents/{datetime:yy}/{datetime:MM}/{datetime:dd}/{datetime:HH}/" +
                       "{datetime:mm}/{PartitionContext.PartitionId}/{SystemProperties.SequenceNumber}.json")
            OutputBinding<String> outputItem) {

        var et = ZonedDateTime.parse(enqueuedTimeUtc + "Z"); // needed as the UTC time presented does not have a TZ
                                                             // indicator
        context.getLogger().info("Event hub message received: " + message + ", properties: " + properties);
        context.getLogger().info("Properties: " + properties);
        context.getLogger().info("System Properties: " + systemProperties);
        context.getLogger().info("partitionContext: " + partitionContext);
        context.getLogger().info("EnqueuedTimeUtc: " + et);

        outputItem.setValue(message);
    }
}

Özellikler

Hem işlem içi hem de yalıtılmış çalışan işlemi C# kitaplıkları tetikleyiciyi yapılandırmak için özniteliğini kullanır. Bunun yerine C# betiği, C# betik kılavuzunda açıklandığı gibi bir function.json yapılandırma dosyası kullanır.

Aşağıdaki özellikleri destekleyen bir olay hub'ına tetikleyici tanımlamak için öğesini EventHubTriggerAttribute kullanın.

Parametreler Açıklama
EventHubName Olay hub'ının adı. olay hub'ı adı da bağlantı dizesi mevcut olduğunda, bu değer çalışma zamanında bu özelliği geçersiz kılar. Aşağıdakiler gibi uygulama ayarlarından başvurulabilir:%eventHubName%
ConsumerGroup Hub'daki olaylara abone olmak için kullanılan tüketici grubunu ayarlayan isteğe bağlı bir özellik. Atlandığında, $Default tüketici grubu kullanılır.
Bağlantı Event Hubs'a nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. Daha fazla bilgi edinmek için bkz. Bağlan ions.

Dekoratörler

Yalnızca Python v2 programlama modeli için geçerlidir.

Bir dekoratör kullanılarak tanımlanan Python v2 işlevleri için, üzerinde aşağıdaki özellikler:cosmos_db_trigger

Özellik Açıklama
arg_name İşlev kodundaki olay öğesini temsil eden değişkenin adı.
event_hub_name Olay hub'ının adı. olay hub'ı adı da bağlantı dizesi mevcut olduğunda, bu değer çalışma zamanında bu özelliği geçersiz kılar.
connection Event Hubs'a nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. Bkz. Bağlan ions.

function.json kullanılarak tanımlanan Python işlevleri için Yapılandırma bölümüne bakın.

Ek Açıklamalar

Java işlevleri çalışma zamanı kitaplığında, aşağıdaki ayarları destekleyen EventHubTrigger ek açıklamasını kullanın:

Yapılandırma

Yalnızca Python v1 programlama modeli için geçerlidir.

Aşağıdaki tabloda, yöntemine geçirilen app.eventHub() nesnede options ayarlayabileceğiniz özellikler açıklanmaktadır.

Özellik Açıklama
eventHubName Olay hub'ının adı. olay hub'ı adı da bağlantı dizesi mevcut olduğunda, bu değer çalışma zamanında bu özelliği geçersiz kılar. Uygulama ayarları aracılığıyla başvurulabilir%eventHubName%
consumerGroup Hub'daki olaylara abone olmak için kullanılan tüketici grubunu ayarlayan isteğe bağlı bir özellik. Atlanırsa, $Default tüketici grubu kullanılır.
Önem düzeyi many Toplu işlemi etkinleştirmek için olarak ayarlayın. atlanırsa veya olarak oneayarlanırsa işleve tek bir ileti geçirilir.
Bağlantı Event Hubs'a nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. Bkz. Bağlan ions.

Aşağıdaki tabloda, çalışma zamanı sürümüne göre farklılık gösteren function.json dosyasında ayarladığınız tetikleyici yapılandırma özellikleri açıklanmaktadır.

function.json özelliği Açıklama
type olarak ayarlanmalıdır eventHubTrigger. Bu özellik, Tetikleyiciyi Azure portalında oluşturduğunuzda otomatik olarak ayarlanır.
direction olarak ayarlanmalıdır in. Bu özellik, Tetikleyiciyi Azure portalında oluşturduğunuzda otomatik olarak ayarlanır.
Adı İşlev kodundaki olay öğesini temsil eden değişkenin adı.
eventHubName Olay hub'ının adı. olay hub'ı adı da bağlantı dizesi mevcut olduğunda, bu değer çalışma zamanında bu özelliği geçersiz kılar. Uygulama ayarları aracılığıyla başvurulabilir%eventHubName%
consumerGroup Hub'daki olaylara abone olmak için kullanılan tüketici grubunu ayarlayan isteğe bağlı bir özellik. Atlanırsa, $Default tüketici grubu kullanılır.
Önem düzeyi many Toplu işlemi etkinleştirmek için olarak ayarlayın. atlanırsa veya olarak oneayarlanırsa işleve tek bir ileti geçirilir.
Bağlantı Event Hubs'a nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. Bkz. Bağlan ions.

Yerel olarak geliştirme yaparken uygulama ayarlarınızı koleksiyondaki local.settings.json dosyasınaValues ekleyin.

Kullanım

Event Hubs tetikleyicisi ve IoT Hub tetikleyicisi ölçeklendirmesi hakkında daha fazla bilgi edinmek için bkz. olayları Azure İşlevleri ile kullanma.

Event Hubs çıkış bağlaması tarafından desteklenen parametre türü İşlevler çalışma zamanı sürümüne, uzantı paketi sürümüne ve kullanılan C# modalitesine bağlıdır.

İşlevin tek bir olayı işlemesini istediğinizde Event Hubs tetikleyicisi aşağıdaki türlere bağlanabilir:

Type Açıklama
string Dize olarak olay. Olay basit bir metin olduğunda kullanın.
byte[] Olayın baytları.
JSON serileştirilebilir türler Bir olay JSON verileri içerdiğinde İşlevler, JSON verilerinin seri durumdan çıkarılarak düz eski bir CLR nesnesi (POCO) türüne dönüştürülmeye çalışılır.
Azure.Messaging.EventHubs.EventData1 Olay nesnesi.
Event Hubs SDK'larının herhangi bir eski sürümünden geçiş gerçekleştiriyorsanız, bu sürümün EventBody yerine eski Body tür için desteği bıraktığına dikkat edin.

İşlevin bir grup olayı işlemesini istediğinizde Event Hubs tetikleyicisi aşağıdaki türlere bağlanabilir:

Type Açıklama
string[] Toplu işlemden dizeler olarak bir dizi olay. Her girdi bir olayı temsil eder.
EventData[]1 Azure.Messaging.EventHubs.EventData örneği olarak toplu işlemden bir dizi olay. Her girdi bir olayı temsil eder.
T[] burada T JSON seri hale getirilebilir tür1'dir Özel POCO türünün örnekleri olarak toplu işlemden olay dizisi. Her girdi bir olayı temsil eder.

1 Bu türleri kullanmak için Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 veya sonraki sürümlerine ve SDK türü bağlamaları için ortak bağımlılıklara başvurmanız gerekir.

Parametre türü aşağıdakilerden biri olabilir:

  • int, String, byte[] gibi herhangi bir yerel Java türü.
  • İsteğe Bağlı'nın kullanıldığı null atanabilir değerler.
  • Herhangi bir POJO türü.

Daha fazla bilgi edinmek için bkz . EventHubTrigger başvurusu.

Olay meta verileri

Event Hubs tetikleyicisi çeşitli meta veri özellikleri sağlar. Meta veri özellikleri, diğer bağlamalardaki bağlama ifadelerinin bir parçası olarak veya kodunuzdaki parametreler olarak kullanılabilir. Özellikler EventData sınıfından gelir.

Özellik Türü Açıklama
PartitionContext PartitionContext PartitionContext örneği.
EnqueuedTimeUtc DateTime UTC olarak sıralanan saat.
Offset string Verilerin olay hub'ı bölüm akışına göre uzaklığı. Uzaklık, Event Hubs akışındaki bir olayın işaretçisi veya tanımlayıcısıdır. Tanımlayıcı, Event Hubs akışının bir bölümünde benzersizdir.
PartitionKey string Olay verilerinin gönderilmesi gereken bölüm.
Properties IDictionary<String,Object> Olay verilerinin kullanıcı özellikleri.
SequenceNumber Int64 Olayın mantıksal sıra numarası.
SystemProperties IDictionary<String,Object> Olay verileri dahil olmak üzere sistem özellikleri.

Bu makalenin önceki bölümlerinde bu özellikleri kullanan kod örneklerine bakın.

Bağlantılar

connection özelliği, uygulamanın Event Hubs'a nasıl bağlanması gerektiğini belirten bir ortam yapılandırması başvurusudur. Şunları belirtebilir:

  • bağlantı dizesi içeren bir uygulama ayarının adı
  • Birden çok uygulama ayarı için paylaşılan ön ekin adı ve birlikte kimlik tabanlı bağlantı tanımlama.

Yapılandırılan değer hem tek bir ayar için tam eşleşme hem de diğer ayarlar için bir ön ek eşleşmesiyse, tam eşleşme kullanılır.

Connection string

Olay hub'ını değil ad alanının Bağlan Bilgileri düğmesine tıklayarak bu bağlantı dizesi alın. bağlantı dizesi, olay hub'ını değil event Hubs ad alanı için olmalıdır.

Tetikleyiciler için kullanıldığında, bağlantı dizesi işlevi etkinleştirmek için en az "okuma" izinlerine sahip olmalıdır. Çıkış bağlamaları için kullanıldığında, bağlantı dizesi olay akışına ileti göndermek için "gönderme" izinlerine sahip olmalıdır.

Bu bağlantı dizesi, bağlama yapılandırmasının özelliği tarafından connection belirtilen değerle eşleşen bir adla bir uygulama ayarında depolanmalıdır.

Kimlik tabanlı bağlantılar

Uzantının 5.x veya üzeri bir sürümünü kullanıyorsanız, gizli dizi içeren bir bağlantı dizesi kullanmak yerine uygulamanın bir Microsoft Entra kimliği kullanmasını sağlayabilirsiniz. Bunu yapmak için, tetikleyici ve bağlama yapılandırmasındaki özelliğiyle connection eşlenen ortak bir ön ekin altında ayarlar tanımlayabilirsiniz.

Bu modda uzantı aşağıdaki özellikleri gerektirir:

Özellik Ortam değişkeni şablonu Açıklama Örnek değer
Tam Ad Alanı <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Tam Event Hubs ad alanı. myeventhubns.servicebus.windows.net

Bağlantıyı özelleştirmek için ek özellikler ayarlanabilir. Bkz. Kimlik tabanlı bağlantılar için ortak özellikler.

Not

Yönetilen Kimlik bağlantıları için ayarlar sağlamak üzere Azure Uygulaması Yapılandırması veya Key Vault kullanılırken, adların doğru çözümlendiğinden __ emin olmak için adların yerine veya / gibi : geçerli bir anahtar ayırıcı kullanılmalıdır.

Örneğin, <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Azure İşlevleri hizmetinde barındırıldığında, kimlik tabanlı bağlantılar yönetilen kimlik kullanır. Ve özellikleriyle credentialclientID kullanıcı tarafından atanan bir kimlik belirtilse de, sistem tarafından atanan kimlik varsayılan olarak kullanılır. Kullanıcı tarafından atanan kimliği kaynak kimliğiyle yapılandırmanın desteklenmediğini unutmayın. Yerel geliştirme gibi diğer bağlamlarda çalıştırıldığında, bunun yerine geliştirici kimliğiniz kullanılır, ancak bu özelleştirilebilir. Bkz. Kimlik tabanlı bağlantılarla yerel geliştirme.

Kimliğe izin verme

Hangi kimlik kullanılıyorsa, hedeflenen eylemleri gerçekleştirmek için izinlere sahip olmalıdır. Çoğu Azure hizmeti için bu, bu izinleri sağlayan yerleşik veya özel rolleri kullanarak Azure RBAC'de bir rol atamanız gerektiği anlamına gelir.

Önemli

Bazı izinler, tüm bağlamlar için gerekli olmayan hedef hizmet tarafından gösterilebilir. Mümkün olduğunda, kimliğe yalnızca gerekli ayrıcalıkları sağlayarak en az ayrıcalık ilkesine uyun. Örneğin, uygulamanın yalnızca bir veri kaynağından okuyabilmesi gerekiyorsa, yalnızca okuma izni olan bir rol kullanın. Okuma işlemi için aşırı izin olduğundan, bu hizmete yazmaya da izin veren bir rol atamak uygun olmaz. Benzer şekilde, rol atamasının kapsamının yalnızca okunması gereken kaynaklara göre ayarlandığından emin olmak istersiniz.

Çalışma zamanında olay hub'ınıza erişim sağlayan bir rol ataması oluşturmanız gerekir. Rol atamasının kapsamı bir Event Hubs ad alanı veya olay hub'ının kendisi için olabilir. Sahip gibi yönetim rolleri yeterli değildir. Aşağıdaki tabloda, Event Hubs uzantısı normal işlemde kullanılırken önerilen yerleşik roller gösterilmektedir. Uygulamanız, yazdığınız koda göre ek izinler gerektirebilir.

Bağlama türü Örnek yerleşik roller
Tetikleyici Azure Event Hubs Veri Alıcısı, Azure Event Hubs Veri Sahibi
Çıkış bağlaması Azure Event Hubs Veri Göndereni

host.json ayarları

host.json dosyası Event Hubs tetikleyici davranışını denetleen ayarlar içerir. Kullanılabilir ayarlarla ilgili ayrıntılar için host.json ayarları bölümüne bakın.

Sonraki adımlar