Azure İşlevleri için Azure Kuyruk depolama tetikleyicisi

  • Makale
  • Okumak için 13 dakika

Kuyruk depolama tetikleyicisi, iletiler Azure Kuyruk depolamaya eklendikçe bir işlev çalıştırır.

Örnek

Kuyrukta yeni bir öğe alındığında işlev başlatmak için kuyruk tetikleyicisini kullanın. Kuyruk iletisi işleve giriş olarak sağlanır.

C# işlevi aşağıdaki C# modlarından biri kullanılarak oluşturulabilir:

Aşağıdaki örnekte kuyruğu yoklayan myqueue-items ve bir kuyruk öğesi her işlendiğinde günlük yazan bir C# işlevi gösterilmektedir.

public static class QueueFunctions
{
    [FunctionName("QueueTrigger")]
    public static void QueueTrigger(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        ILogger log)
    {
        log.LogInformation($"C# function processed: {myQueueItem}");
    }
}

Aşağıdaki Java örneği, kuyruğa yerleştirilen tetiklenen iletiyi günlüğe kaydeden bir depolama kuyruğu myqueuenametetikleyici işlevini gösterir.

@FunctionName("queueprocessor")
public void run(
    @QueueTrigger(name = "msg",
                queueName = "myqueuename",
                connection = "myconnvarname") String message,
    final ExecutionContext context
) {
    context.getLogger().info(message);
}

Aşağıdaki örnekte function.json dosyasındaki bir kuyruk tetikleyici bağlaması ve bağlamayı kullanan bir JavaScript işlevi gösterilmektedir. İşlev kuyruğu yoklar myqueue-items ve bir kuyruk öğesi her işlendiğinde bir günlük yazar.

function.json dosyası aşağıdadır:

{
    "disabled": false,
    "bindings": [
        {
            "type": "queueTrigger",
            "direction": "in",
            "name": "myQueueItem",
            "queueName": "myqueue-items",
            "connection":"MyStorageConnectionAppSetting"
        }
    ]
}

Yapılandırma bölümünde bu özellikler açıklanır.

Not

ad parametresi, kuyruk öğesi yükünü içeren JavaScript kodunda olduğu gibi context.bindings.<name> yansıtılmıştır. Bu yük, işleve ikinci parametre olarak da geçirilir.

JavaScript kodu şu şekildedir:

module.exports = async function (context, message) {
    context.log('Node.js queue trigger function processed work item', message);
    // OR access using context.bindings.<name>
    // context.log('Node.js queue trigger function processed work item', context.bindings.myQueueItem);
    context.log('expirationTime =', context.bindingData.expirationTime);
    context.log('insertionTime =', context.bindingData.insertionTime);
    context.log('nextVisibleTime =', context.bindingData.nextVisibleTime);
    context.log('id =', context.bindingData.id);
    context.log('popReceipt =', context.bindingData.popReceipt);
    context.log('dequeueCount =', context.bindingData.dequeueCount);
};

Kullanım bölümünde, function.json dosyasındaki name özelliği tarafından adlandırılan açıklanmaktadırmyQueueItem. İleti meta verileri bölümünde gösterilen diğer tüm değişkenler açıklanmaktadır.

Aşağıdaki örnekte, bir işleve tetikleyici aracılığıyla iletilen kuyruk iletisinin nasıl okunduğu gösterilmektedir.

Depolama kuyruğu tetikleyicisi function.json dosyasında tanımlanır ve burada type olarak queueTriggerayarlanır.

{
  "bindings": [
    {
      "name": "QueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Run.ps1 dosyasındaki kod, işlevinizdeki kuyruk iletisini okumanızı sağlayan parametresini olarak $QueueItembildirir.

# Input bindings are passed in via param block.
param([string] $QueueItem, $TriggerMetadata)

# Write out the queue message and metadata to the information log.
Write-Host "PowerShell queue trigger function processed work item: $QueueItem"
Write-Host "Queue item expiration time: $($TriggerMetadata.ExpirationTime)"
Write-Host "Queue item insertion time: $($TriggerMetadata.InsertionTime)"
Write-Host "Queue item next visible time: $($TriggerMetadata.NextVisibleTime)"
Write-Host "ID: $($TriggerMetadata.Id)"
Write-Host "Pop receipt: $($TriggerMetadata.PopReceipt)"
Write-Host "Dequeue count: $($TriggerMetadata.DequeueCount)"

Aşağıdaki örnekte, bir işleve tetikleyici aracılığıyla iletilen kuyruk iletisinin nasıl okunduğu gösterilmektedir.

function.json dosyasında türü olarak ayarlanmış queueTriggerbir Depolama kuyruğu tetikleyicisi tanımlanır.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

_init_.py kodu, işlevinizdeki kuyruk iletisini okumanızı sağlayan parametresini olarak func.QueueMessagebildirir.

import logging
import json

import azure.functions as func

def main(msg: func.QueueMessage):
    logging.info('Python queue trigger function processed a queue item.')

    result = json.dumps({
        'id': msg.id,
        'body': msg.get_body().decode('utf-8'),
        'expiration_time': (msg.expiration_time.isoformat()
                            if msg.expiration_time else None),
        'insertion_time': (msg.insertion_time.isoformat()
                           if msg.insertion_time else None),
        'time_next_visible': (msg.time_next_visible.isoformat()
                              if msg.time_next_visible else None),
        'pop_receipt': msg.pop_receipt,
        'dequeue_count': msg.dequeue_count
    })

    logging.info(result)

Öznitelikler

hem işlem içi hem de yalıtılmış işlem C# kitaplıkları, işlevi tanımlamak için QueueTriggerAttribute kullanır. C# betiği bunun yerine function.json yapılandırma dosyasını kullanır.

C# sınıf kitaplıklarında özniteliğin oluşturucu, aşağıdaki örnekte gösterildiği gibi izlenecek kuyruğun adını alır:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem, 
    ILogger log)
{
    ...
}

Özelliğini, aşağıdaki örnekte gösterildiği gibi kullanılacak depolama hesabı bağlantı dizesini içeren uygulama ayarını belirtecek şekilde ayarlayabilirsiniz Connection :

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("myqueue-items", Connection = "StorageConnectionAppSetting")] string myQueueItem, 
    ILogger log)
{
    ....
}

Ek Açıklamalar

Ek QueueTrigger açıklama işlevi tetikleyen kuyruğa erişmenizi sağlar. Aşağıdaki örnek, kuyruk iletisini parametresi aracılığıyla message işlev için kullanılabilir hale getirir.

package com.function;
import com.microsoft.azure.functions.annotation.*;
import java.util.Queue;
import com.microsoft.azure.functions.*;

public class QueueTriggerDemo {
    @FunctionName("QueueTriggerDemo")
    public void run(
        @QueueTrigger(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") String message,
        final ExecutionContext context
    ) {
        context.getLogger().info("Queue message: " + message);
    }
}
Özellik Açıklama
name İşlev imzasında parametre adını bildirir. İşlev tetiklendiğinde, bu parametrenin değeri kuyruk iletisinin içeriğine sahiptir.
queueName Depolama hesabında kuyruk adını bildirir.
connection Depolama hesabı bağlantı dizesini gösterir.

Yapılandırma

Aşağıdaki tabloda function.json dosyasında ayarladığınız bağlama yapılandırma özellikleri ve QueueTrigger özniteliği açıklanmaktadır.

function.json özelliği Açıklama
Türü olarak ayarlanmalıdır queueTrigger. Tetikleyiciyi Azure portal oluşturduğunuzda bu özellik otomatik olarak ayarlanır.
Yön Yalnızca function.json dosyasında. olarak ayarlanmalıdır in. Tetikleyiciyi Azure portal oluşturduğunuzda bu özellik otomatik olarak ayarlanır.
Adı İşlev kodunda kuyruk öğesi yükünü içeren değişkenin adı.
queueName Yoklama için kuyruğun adı.
bağlantı Azure Kuyruklarına nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. Bkz. Bağlantılar.

Tam örnekler için Örnek bölümüne bakın.

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

Kullanım

Not

İşlevler base64 ile kodlanmış bir dize bekler. Kodlama türündeki tüm ayarlamaların ( verileri base64 kodlamalı dize olarak hazırlamak için) çağrı hizmetinde uygulanması gerekir.

Kuyruk tetikleyicisinin kullanımı uzantı paketi sürümüne ve işlev uygulamanızda kullanılan C# modalitesine bağlıdır ve bu da aşağıdakilerden biri olabilir:

İşlem içi sınıf kitaplığı, İşlevler çalışma zamanıyla aynı işlemde çalıştırılan derlenmiş bir C# işlevidir.

Modun ve sürümün kullanım ayrıntılarını görmek için bir sürüm seçin.

gibi string paramNamebir yöntem parametresi kullanarak ileti verilerine erişin. paramName, QueueTriggerAttribute içinde belirtilen değerdir. Aşağıdaki türlerden herhangi birine bağlanabilirsiniz:

İşlevler çalışma zamanı bir nesneye bağlanırken JSON yükünün seri durumdan çıkararak kodunuzda tanımlanan rastgele bir sınıfın örneğine dönüştürmeyi dener. QueueMessage kullanan örnekler için uzantının GitHub deposuna bakın.

Özniteliği bir Connection özellik alırken depolama hesabı bağlantısı belirtmek için StorageAccountAttribute'u da kullanabilirsiniz. Kitaplıktaki diğer işlevlerden farklı bir depolama hesabı kullanmanız gerektiğinde bunu yapabilirsiniz. Oluşturucu, depolama bağlantı dizesi içeren bir uygulama ayarının adını alır. özniteliği parametre, yöntem veya sınıf düzeyinde uygulanabilir. Aşağıdaki örnekte sınıf düzeyi ve yöntem düzeyi gösterilmektedir:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

Kullanılacak depolama hesabı aşağıdaki sırayla belirlenir:

  • Tetikleyici veya bağlama özniteliğinin Connection özelliği.
  • Tetikleyici StorageAccount veya bağlama özniteliğiyle aynı parametreye uygulanan öznitelik.
  • StorageAccount İşleve uygulanan öznitelik.
  • StorageAccount sınıfına uygulanan öznitelik.
  • uygulama ayarında AzureWebJobsStorage tanımlanan işlev uygulaması için varsayılan depolama hesabı.

QueueTrigger ek açıklaması, işlevi tetikleyen kuyruk iletisine erişmenizi sağlar.

Kuyruk öğesi yükü aracılığıyla kullanılabilir context.bindings.<NAME> ; burada <NAME>function.json dosyasında tanımlanan adla eşleşir. Yük JSON ise, değer bir nesnede seri durumdan çıkarılır.

function.json dosyasında bağlamanın name parametresi tarafından belirlenen adla eşleşen dize parametresi aracılığıyla kuyruk iletisine erişin.

QueueMessage olarak yazılan parametre aracılığıyla kuyruk iletisine erişin.

Meta veri

Kuyruk tetikleyicisi çeşitli meta veri özellikleri sağlar. Bu özellikler, diğer bağlamalardaki bağlama ifadelerinin bir parçası olarak veya kodunuzdaki parametreler olarak kullanılabilir.

Özellikler CloudQueueMessage sınıfının üyeleridir.

Özellik Tür Açıklama
QueueTrigger string Kuyruk yükü (geçerli bir dizeyse). Kuyruk iletisi yükü bir dizeyse, QueueTriggerfunction.json dosyasındaki özelliği tarafından adlandırılan değişkenle aynı değere name sahiptir.
DequeueCount int Bu iletinin kaç kez sıralandığı.
ExpirationTime DateTimeOffset İletinin süresi dolduğunda.
Id string Kuyruk iletisi kimliği.
InsertionTime DateTimeOffset İletinin kuyruğa eklenme zamanı.
NextVisibleTime DateTimeOffset İletinin bir sonraki görünür olacağı zaman.
PopReceipt string İletinin pop makbuzu.

Bağlantılar

connection özelliği, uygulamanın Azure Kuyruklarına nasıl bağlanacaklarını belirten bir ortam yapılandırması başvurusudur. Şunları belirtebilir:

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şmesi ise, tam eşleşme kullanılır.

Bağlantı dizesi

Bağlantı dizesi almak için Depolama hesabı erişim anahtarlarını yönetme bölümünde gösterilen adımları izleyin.

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.

Uygulama ayarı adı "AzureWebJobs" ile başlıyorsa, adın yalnızca kalanını burada belirtebilirsiniz. Örneğin, "MyStorage" olarak ayarlarsanızconnection, İşlevler çalışma zamanı "AzureWebJobsMyStorage" adlı bir uygulama ayarı arar. Boş bırakırsanızconnection, İşlevler çalışma zamanı adlı AzureWebJobsStorageuygulama ayarında varsayılan Depolama bağlantı dizesini kullanı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 Azure Active Directory 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 ek altında ayarları tanımlarsınız.

"AzureWebJobsStorage" olarak ayarlanıyorsanız connection bkz. Kimlikle konak depolamaya bağlanma. Diğer tüm bağlantılar için uzantı aşağıdaki özellikleri gerektirir:

Özellik Ortam değişkeni şablonu Açıklama Örnek değer
Kuyruk Hizmeti URI'si <CONNECTION_NAME_PREFIX>__queueServiceUri1 HTTPS şemasını kullanarak bağlandığınız kuyruk hizmetinin veri düzlemi URI'si. <https:// storage_account_name.queue.core.windows.net>

1<CONNECTION_NAME_PREFIX>__serviceUri diğer ad olarak kullanılabilir. Her iki form da sağlanırsa, queueServiceUri form kullanılır. Genel serviceUri bağlantı yapılandırması bloblar, kuyruklar ve/veya tablolar arasında kullanılacaksa form kullanılamaz.

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

Azure İşlevleri hizmetinde barındırıldığında, kimlik tabanlı bağlantılar yönetilen kimlik kullanır. Sistem tarafından atanan kimlik varsayılan olarak kullanılır, ancak kullanıcı tarafından atanan kimlik ve clientID özellikleriyle credential belirtilebilir. Kullanıcı tarafından atanan kimliği kaynak kimliğiyle yapılandırmanın desteklenmediğini unutmayın. Yerel geliştirme gibi başka 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

Kullanılan kimlik, hedeflenen eylemleri gerçekleştirmek için izinlere sahip olmalıdır. Bu izinleri sağlayan yerleşik veya özel rolleri kullanarak Azure RBAC'de bir rol atamanız gerekir.

Önemli

Bazı izinler hedef hizmet tarafından tüm bağlamlar için gerekli olmayan şekilde gösterilebilir. Mümkün olduğunda, en az ayrıcalık ilkesine bağlı kalarak kimliğe yalnızca gerekli ayrıcalıkları verin. Ö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, söz konusu hizmete yazmaya izin veren bir rol atamak uygun olmaz. Benzer şekilde, rol atamasının kapsamının yalnızca okunması gereken kaynaklar üzerinde olduğundan emin olmak istersiniz.

Çalışma zamanında kuyruğunuza erişim sağlayan bir rol ataması oluşturmanız gerekir. Sahip gibi yönetim rolleri yeterli değildir. Aşağıdaki tabloda, Kuyruk Depolama 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 Kuyruk Veri Okuyucusu Depolama Depolama Kuyruk Veri İletisi İşlemcisi
Çıkış bağlaması Kuyruk Verileri Katkıda Bulunanı,Depolama KuyrukVeri İletisi Göndereni Depolama

Zehirli iletiler

Bir kuyruk tetikleyici işlevi başarısız olduğunda, Azure İşlevleri ilk deneme dahil olmak üzere belirli bir kuyruk iletisi için işlevi en fazla beş kez yeniden dener. Beş denemenin tümü başarısız olursa, işlev çalışma zamanı originalqueuename-poison> adlı< kuyruğa bir ileti ekler. Zehir kuyruğundan gelen iletileri günlüğe kaydederek veya el ile dikkat gerektiğini belirten bir bildirim göndererek işlemek için bir işlev yazabilirsiniz.

Zehirli iletileri el ile işlemek için kuyruk iletisinin dequeueCount öğesini denetleyin.

Kilitle göz atma

Peek-lock düzeni, kuyruk tetikleyicileri için otomatik olarak gerçekleşir. İletiler sorgudan kaldırıldığında görünmez olarak işaretlenir ve Depolama hizmeti tarafından yönetilen bir zaman aşımıyla ilişkilendirilir.

İşlev başlatıldığında, aşağıdaki koşullarda bir iletiyi işlemeye başlar.

  • İşlev başarılı olursa işlev yürütmesi tamamlanır ve ileti silinir.
  • İşlev başarısız olursa ileti görünürlüğü sıfırlanır. Sıfırlandıktan sonra, işlev yeni bir ileti istediğinde ileti yeniden işlenir.
  • Kilitlenme nedeniyle işlev hiçbir zaman tamamlanmazsa, ileti görünürlüğünün süresi dolar ve ileti kuyrukta yeniden görüntülenir.

Tüm görünürlük mekanizmaları İşlevler çalışma zamanı tarafından değil Depolama hizmeti tarafından işlenir.

Yoklama algoritması

Kuyruk tetikleyicisi, boşta kuyruk yoklamasının depolama işlemi maliyetleri üzerindeki etkisini azaltmak için rastgele bir üstel geri alma algoritması uygular.

Algoritma aşağıdaki mantığı kullanır:

  • bir ileti bulunduğunda, çalışma zamanı 100 milisaniye bekler ve sonra başka bir iletiyi denetler
  • İleti bulunamadığında, yeniden denemeden önce yaklaşık 200 milisaniye bekler.
  • Sonraki başarısız kuyruk iletisi alma denemelerinden sonra, bekleme süresi varsayılan olarak bir dakika olan maksimum bekleme süresine ulaşana kadar artmaya devam eder.
  • Maksimum bekleme süresi, host.json dosyasındaki özelliği aracılığıyla maxPollingInterval yapılandırılabilir.

Yerel geliştirme için maksimum yoklama aralığı varsayılan olarak iki saniyedir.

Not

Tüketim planında işlev uygulamalarını barındırırken faturalamayla ilgili olarak, çalışma zamanı tarafından yoklama için harcanan süre için ücret alınmaz.

Eşzamanlılık

Bekleyen birden çok kuyruk iletisi olduğunda, kuyruk tetikleyicisi bir dizi ileti alır ve bunları işlemek için işlev örneklerini eşzamanlı olarak çağırır. Varsayılan olarak toplu iş boyutu 16'dır. İşlenen sayı 8'e indiğinde, çalışma zamanı başka bir toplu iş alır ve bu iletileri işlemeye başlar. Bu nedenle, bir sanal makinede (VM) işlev başına işlenen eşzamanlı ileti sayısı üst sınırı 24'tür. Bu sınır, her VM'de kuyruk tarafından tetiklenen her işlev için ayrı ayrı geçerlidir. İşlev uygulamanızın ölçeği birden çok VM'ye genişletilirse, her VM tetikleyicileri bekler ve işlevleri çalıştırmayı dener. Örneğin, bir işlev uygulamasının ölçeği 3 VM'ye genişletilirse, kuyrukla tetiklenen bir işlevin varsayılan eş zamanlı örnek sayısı üst sınırı 72'dir.

Toplu iş boyutu ve yeni toplu iş alma eşiği host.json dosyasında yapılandırılabilir. Bir işlev uygulamasında kuyrukla tetiklenen işlevler için paralel yürütmeyi en aza indirmek istiyorsanız, toplu iş boyutunu 1 olarak ayarlayabilirsiniz. Bu ayar, işlev uygulamanız tek bir sanal makinede (VM) çalıştığı sürece eşzamanlılığı ortadan kaldırır.

Kuyruk tetikleyicisi, bir işlevin bir kuyruk iletisini aynı anda birden çok kez işlemesini otomatik olarak engeller.

host.json özellikleri

host.json dosyası, kuyruk 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