Azure Işlevleri için Azure Event Hubs tetikleyicisi

Makale
05/13/2021
Okumak için 10 dakika

Bu makalede, Azure Işlevleri için azure Event Hubs tetikleyicisiyle nasıl çalışılacağı açıklanmaktadır. Azure Işlevleri Event Hubs için tetikleyiciyi ve Çıkış bağlamalarını destekler.

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

Olay hub'ı olay akışına gönderilen bir olayı yanıtlamak için işlev tetikleyicisi kullanın. Tetikleyiciyi ayarlamak için temel olay hub'ını okuma erişiminizin olması gerekir. İşlev tetiklendiğinde, işleve geçirilen ileti dize olarak yazın.

Ölçeklendirme

Olayla tetiklenen bir işlevin her örneği tek bir EventProcessorHost örneği tarafından de desteklenir. Tetikleyici (Event Hubs) yalnızca bir EventProcessorHost örneğinin verilen bölümde kira alamalarını sağlar.

Örneğin, aşağıdaki gibi bir Olay Hub'ı düşünün:

10 bölüm
Tüm bölümlere eşit olarak dağıtılmış 1.000 olay ve her bölümde 100 ileti

İşlevi ilk kez etkinleştirildiğinde, işlevin yalnızca bir örneği vardır. İlk işlev örneğini çağır Function_0 bakalım. işlevi, Function_0 on bölümde de kiralama tutan tek bir EventProcessorHost örneğine sahiptir. Bu örnek, 0-9 bölümlerinden olayları okuyor. Bu noktadan sonra, aşağıdakilerden biri gerçekleşir:

Yeni işlev örnekleri gerekmez: İşlevler ölçeklendirme mantığının etkili olmadan önce Function_0 1.000 olay da işleyenegeldi. Bu durumda, 1.000 ileti de tarafından Function_0 işlenir.
Ek bir işlev örneği eklenir: İşlevler ölçeklendirme mantığı, işleyenden daha fazla ileti olduğunu belirlerse, yeni bir Function_0 işlev uygulaması örneği ( ) Function_1 oluşturulur. Bu yeni işlev, EventProcessorHost'un ilişkili bir örneğine de sahiptir. Temel alınan Event Hubs, yeni bir konak örneğinin iletileri okumaya çalıştığını algılaya kadar, konak örnekleri genelinde bölümlerin yükünü dengeler. Örneğin, 0-4 bölümlerine ve Function_0 5-9 bölümlerine Function_1 atanabilir.
N işlev örneği daha eklendi: İşlevler ölçeklendirme mantığı hem hem de işleyene kadar daha fazla ileti olduğunu belirlerse, Function_0 yeni işlev uygulaması örnekleri Function_1 Functions_N oluşturulur. Uygulamalar, olay N hub'ı bölümlerinin sayısından büyük olacak şekilde oluşturulur. Örneğimizde, Event Hubs bölümler için yük dengelemesi yeniden oluşturacağız. Bu örnekte... Function_0 Functions_9 .

Ölçeklendirme gerçekleşirken N örnekler, olay hub'ı bölümleri sayısından büyük bir sayıdır. Bu düzen, EventProcessorHost örneklerinin diğer örneklerden kullanılabilir hale geldiklerinden bölümlere kilit almak için kullanılabilir olduğundan emin olmak için kullanılır. Yalnızca işlev örneği yürütülürken kullanılan kaynaklar için ücret ödemezsiniz. Başka bir deyişle, bu fazla sağlama için ücret ödemezsiniz.

Tüm işlev yürütmesi tamamlandığında (hatayla veya hata olmadan), ilgili depolama hesabına denetim noktaları eklenir. Denetim noktası başarılı olduğunda, 1.000 ilanın hepsi bir daha asla alınamayacaktır.

Aşağıdaki örnekte olay hub'ı tetikleyicisi ileti gövdelerini günlüğe kaydeden bir C# işlevi yer alır.

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    log.LogInformation($"C# function triggered to process a message: {myEventHubMessage}");
}

İşlev kodundaki olay meta verilerine erişmek için eventData nesnesine bağlanın (için bir using deyimi Microsoft.Azure.EventHubs gerektirir). Aynı özelliklere erişmek için yöntem imzasını bağlama ifadelerini de kullanabilirsiniz. Aşağıdaki örnek, aynı verileri almak için iki yolu da gösterir:

[FunctionName("EventHubTriggerCSharp")]
public static void Run(
    [EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    ILogger log)
{
    log.LogInformation($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    // Metadata accessed by binding to EventData
    log.LogInformation($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.LogInformation($"Offset={myEventHubMessage.SystemProperties.Offset}");
    // Metadata accessed by using binding expressions in method parameters
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={sequenceNumber}");
    log.LogInformation($"Offset={offset}");
}

Bir toplu iş içinde olayları almak için bir dizi string veya EventData olun.

Not

Bir toplu iş içinde alırken yukarıdaki örnekte olduğu gibi metot parametrelerine bağlanamazsınız ve bunları her DateTime enqueuedTimeUtc nesneden EventData alasınız

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData[] eventHubMessages, ILogger log)
{
    foreach (var message in eventHubMessages)
    {
        log.LogInformation($"C# function triggered to process a message: {Encoding.UTF8.GetString(message.Body)}");
        log.LogInformation($"EnqueuedTimeUtc={message.SystemProperties.EnqueuedTimeUtc}");
    }
}

Aşağıdaki örnekte function.json dosyasındaki olay hub'ı tetikleyici bağlaması ve bağlamayı kullanan bir C# betik işlevi yer amektedir. İşlev, olay hub'ı tetikleyicisi ileti gövdesinde günlüğe kaydeder.

Aşağıdaki örnekler function.json Event Hubs bağlama verilerini gösterir.

Sürüm 2.x ve üzerinde

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Sürüm 1.x

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "path": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

C# betik kodu şu şekildedir:

using System;

public static void Run(string myEventHubMessage, TraceWriter log)
{
    log.Info($"C# function triggered to process a message: {myEventHubMessage}");
}

#r "Microsoft.Azure.EventHubs"

using System.Text;
using System;
using Microsoft.ServiceBus.Messaging;
using Microsoft.Azure.EventHubs;

public static void Run(EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    TraceWriter log)
{
    log.Info($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    log.Info($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.Info($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.Info($"Offset={myEventHubMessage.SystemProperties.Offset}");

    // Metadata accessed by using binding expressions
    log.Info($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.Info($"SequenceNumber={sequenceNumber}");
    log.Info($"Offset={offset}");
}

Bir toplu iş içinde olayları almak için bir dizi string EventData veya olun:

public static void Run(string[] eventHubMessages, TraceWriter log)
{
    foreach (var message in eventHubMessages)
    {
        log.Info($"C# function triggered to process a message: {message}");
    }
}

Aşağıdaki örnekte function.json dosyasındaki olay hub'ı tetikleyici bağlaması ve bağlamayı kullanan bir JavaScript işlevi yer amektedir. İşlev, olay meta verilerini okur ve iletiyi günlüğe kaydeder.

Aşağıdaki örnekler function.json Event Hubs bağlama verilerini gösterir.

Sürüm 2.x ve üzerinde

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Sürüm 1.x

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "path": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

JavaScript kodu şu şekildedir:

module.exports = function (context, myEventHubMessage) {
    context.log('Function triggered to process a message: ', myEventHubMessage);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.bindingData.sequenceNumber);
    context.log('Offset =', context.bindingData.offset);

    context.done();
};

Bir toplu iş içinde olayları almak için, aşağıdaki örneklerde gösterildiği gibi cardinality many function.json dosyasında olarak ayarlayın.

Sürüm 2.x ve üzerinde

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

Sürüm 1.x

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "path": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

JavaScript kodu şu şekildedir:

module.exports = function (context, eventHubMessages) {
    context.log(`JavaScript eventhub trigger function called for message array ${eventHubMessages}`);

    eventHubMessages.forEach((message, index) => {
        context.log(`Processed message ${message}`);
        context.log(`EnqueuedTimeUtc = ${context.bindingData.enqueuedTimeUtcArray[index]}`);
        context.log(`SequenceNumber = ${context.bindingData.sequenceNumberArray[index]}`);
        context.log(`Offset = ${context.bindingData.offsetArray[index]}`);
    });

    context.done();
};

Aşağıdaki örnekte function.json dosyasındaki olay hub'ı tetikleyici bağlaması ve bağlamayı kullanan bir Python işlevi yer amektedir. İşlev, olay meta verilerini okur ve iletiyi günlüğe kaydeder.

Aşağıdaki örnekler function.json Event Hubs bağlama verilerini gösterir.

{
  "type": "eventHubTrigger",
  "name": "event",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Python kodu şu şekildedir:

import logging
import azure.functions as func


def main(event: func.EventHubEvent):
    logging.info(f'Function triggered to process a message: {event.get_body().decode()}')
    logging.info(f'  EnqueuedTimeUtc = {event.enqueued_time}')
    logging.info(f'  SequenceNumber = {event.sequence_number}')
    logging.info(f'  Offset = {event.offset}')

    # Metadata
    for key in event.metadata:
        logging.info(f'Metadata: {key} = {event.metadata[key]}')

Aşağıdaki örnek, Olay Hub'ı tetikleyicisi ileti gövdelerini günlüğe kaydeden bir Olay Hub'ı tetikleyici bağlaması gösterir.

@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ığında,değeri EventHubTrigger Event Hub'dan gelecek parametrelerde ek açıklamasını kullanın. Bu ek açıklamalara sahip parametreler, bir olay geldiğinde işlevin çalışmasına neden olur. Bu ek açıklama yerel Java türleri, POJO'lar veya kullanılarak null değere değiştirilebilir değerlerle Optional<T> kullanılabilir.

Öznitelikler ve ek açıklamalar

C# sınıf kitaplıklarında EventHubTriggerAttribute özniteliğini kullanın.

Özniteliğin oluşturucusu olay hub'larının adını, tüketici grubunun adını ve bağlantı dizesini içeren bir uygulama ayarının adını alır. Bu ayarlar hakkında daha fazla bilgi için tetikleyici yapılandırması bölümüne bakın. Öznitelik örneği şu EventHubTriggerAttribute şekildedir:

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    ...
}

Tam bir örnek için bkz. Tetikleyici - C# örneği.

Yapılandırma

Aşağıdaki tabloda function.json dosyasında ayar istediğiniz bağlama yapılandırma özellikleri ve özniteliği açık EventHubTrigger bulunmaktadır.

function.json özelliği	Öznitelik özelliği	Description
Türü	yok	olarak ayarlanmış olması `eventHubTrigger` gerekir. Bu özellik, tetikleyiciyi Azure portal.
Yön	yok	olarak ayarlanmış olması `in` gerekir. Bu özellik, tetikleyiciyi Azure portal.
Adı	yok	İşlev kodundaki olay öğesini temsil eden değişkenin adı.
Yolu	EventHubName	Yalnızca 1.x işlevleri. Olay hub'larının adı. Bağlantı dizesinde olay hub'ı adı da mevcut olduğunda, bu değer çalışma zamanında bu özelliği geçersiz kılar.
eventHubName	EventHubName	İşlevler 2.x ve üst. Olay hub'larının adı. Bağlantı dizesinde olay hub'ı adı da mevcut olduğunda, bu değer çalışma zamanında bu özelliği geçersiz kılar. Uygulama ayarları aracılığıyla başvurulabilirsiniz `%eventHubName%`
consumerGroup	ConsumerGroup	Hub'daki olaylara abone olmak için kullanılan tüketici grubunu ayaran isteğe bağlı bir özellik. Atlanırsa tüketici `$Default` grubu kullanılır.
Önem düzeyi	yok	C# olmayan tüm diller için kullanılır. Toplu işlemi `many` etkinleştirmek için olarak ayarlayın. Atlanırsa veya olarak `one` ayarlanırsa işleve tek bir ileti geçirilebilir. C# içinde, tetikleyici türü için bir diziye sahip olduğunda bu özellik otomatik olarak atanır.
Bağlantı	Bağlantı	Uygulama ayarı veya uygulama ayarları koleksiyonuna bağlanmayı belirten Event Hubs. Bkz. Bağlantılar.

Yerel olarak geliştirilirken, uygulama ayarları local.settings.jsdosyasınagider.

Bağlantılar

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

Bağlantı dizesi içeren bir uygulama ayarının adı
Birden çok uygulama ayarı için bir paylaşılan ön ek adı, birlikte kimlik tabanlı bir bağlantıyıtanımlar.

Yapılandırılmış değer tek bir ayar için tam eşleşmedir ve diğer ayarlarla ilgili önek eşleşiyorsa, tam eşleşme kullanılır.

Bağlantı dizesi

Olay Hub 'ının kendisi değil, ad alanıIçin bağlantı bilgileri düğmesine tıklayarak bu bağlantı dizesini edinin. Bağlantı dizesi, Olay Hub 'ının değil, bir Event Hubs ad alanı için olmalıdır.

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

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

Kimlik tabanlı bağlantılar

uzantının 5. x veya üzeri sürümünükullanıyorsanız, gizli anahtar içeren bir bağlantı dizesi kullanmak yerine uygulamanın bir Azure Active Directory kimliğikullanmasını sağlayabilirsiniz. Bunu yapmak için, connection tetikleyici ve bağlama yapılandırmasındaki özelliğe eşleyen ortak bir ön ek altında ayarlar tanımlayabilirsiniz.

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

Özellik	Ortam değişkeni şablonu	Description	Örnek değer
Tam nitelikli ad alanı	`<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace`	Tam nitelikli Event Hubs ad alanı.	<event_hubs_namespace>. servicebus.windows.net

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

Azure Işlevleri hizmetinde barındırıldığında, kimlik tabanlı bağlantılar yönetilen bir kimlikkullanır. Sistem tarafından atanan kimlik, ve özellikleriyle kullanıcı tarafından atanan bir kimlik belirtibilse de varsayılan olarak kullanılır credential clientID . Yerel geliştirme gibi diğer bağlamlarda çalıştırıldığında geliştirici kimliğiniz bunun yerine özelleştirilebilir. Bkz. kimlik tabanlı bağlantılarla yerel geliştirme.

Kimliğe izin ver

Kullanılan kimliğin istenen eylemleri gerçekleştirmek için izinleri olması gerekir. Azure RBAC 'de, bu izinleri sağlayan yerleşik veya özel roller kullanarak bir rol atamanızgerekir.

Önemli

Bazı izinler, tüm bağlamlarda gerekli olmayan hedef hizmet tarafından açığa çıkabilir. Mümkün olduğunda, en az ayrıcalık ilkesine bağlı olarak yalnızca kimlik gerekli ayrıcalıkları veriliyor. Örneğin, uygulamanın yalnızca bir veri kaynağından okuyabilmesi gerekiyorsa, yalnızca okuma iznine sahip olan bir rol kullanın. Bu hizmetin yazılmasına izin veren bir rol atamak uygun değildir, çünkü bu, okuma işlemi için aşırı izindir. Benzer şekilde, rol atamasının yalnızca okunması gereken kaynaklar üzerinde kapsam olmasını sağlamak isteyeceksiniz.

Çalışma zamanında Olay Hub 'ınıza erişim sağlayan bir rol ataması oluşturmanız gerekecektir. Rol atamasının kapsamı, Olay Hub 'ının değil, bir Event Hubs ad alanı için olmalıdır. Sahip gibi yönetim rolleri yeterli değildir. Aşağıdaki tabloda, Event Hubs uzantısı normal işleminde 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ğlama	Azure Event Hubs veri gönderici

Kullanım

Varsayılan

Tetikleyici Olay Hub'ı için aşağıdaki parametre türlerini kullanabilirsiniz:

string
byte[]
POCO
EventData- EventData'nın varsayılan özellikleri Microsoft.Azure.EventHubs ad alanı için içinde sağlanır.

Ek türler

Event Hub uzantısının 5.0.0 veya daha yüksek sürümünü kullanan EventData uygulamalar, Microsoft.Azure.EventHubs ad alanı yerine Azure.Messaging.EventHubs türünü kullanır. Bu sürüm, aşağıdaki türler Body için eski tür desteğini bıraktı:

EventBody

Varsayılan

Tetikleyici Olay Hub'ı için aşağıdaki parametre türlerini kullanabilirsiniz:

string
byte[]
POCO
EventData- EventData'nın varsayılan özellikleri Microsoft.Azure.EventHubs ad alanı için içinde sağlanır.

Ek türler

EventBody

Olay meta verileri

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

Özellik	Tür	Description
`PartitionContext`	PartitionContext	`PartitionContext` örneği.
`EnqueuedTimeUtc`	`DateTime`	UTC olarak enqueued saat.
`Offset`	`string`	Verilerin Olay Hub'ı bölüm akışına göre uzaklığı. Uzaklık, akış içindeki bir olayın işaretçisi veya tanımlayıcısı Event Hubs olur. Tanımlayıcı, veri akışının bir Event Hubs benzersizdir.
`PartitionKey`	`string`	Olay verilerini göndermesi gereken bölüm.
`Properties`	`IDictionary<String,Object>`	Olay verisi kullanıcı özellikleri.
`SequenceNumber`	`Int64`	Olayın mantıksal sıra numarası.
`SystemProperties`	`IDictionary<String,Object>`	Olay verileri de dahil olmak üzere sistem özellikleri.

Bu makalenin başlarında bu özellikleri kullanan kod örneklerine bakın.

Ayarlar üzerinde host.js

Dosyadaki host.js , Olay Hub 'ı tetikleme davranışını denetleyen ayarları içerir. Kullanılabilir ayarlarla ilgili ayrıntılar için ayarlarıhost.js bölümüne bakın.

Sonraki adımlar

Olayları bir olay akışına yazma (çıkış bağlama)

Azure Işlevleri için Azure Event Hubs tetikleyicisi

Lütfen deneyiminizi değerlendirin

Ölçeklendirme

Öznitelikler ve ek açıklamalar

Yapılandırma

Bağlantılar

Bağlantı dizesi

Kimlik tabanlı bağlantılar

Kimliğe izin ver

Kullanım

Varsayılan

Ek türler

Olay meta verileri

Ayarlar üzerinde host.js

Sonraki adımlar