Azure İşlevleri için Azure Kuyruk depolama çıkış bağlamaları

  • Makale

Azure İşlevleri bir çıkış bağlaması ayarlayarak yeni Azure Kuyruk depolama iletileri oluşturabilir.

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

Ö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

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

  • Yalıtılmış çalışan modeli: Çalışma zamanından yalıtılmış bir çalışan işleminde çalışan derlenmiş C# işlevi. LTS ve .NET ve .NET Framework dışındaki sürümlerde çalışan C# işlevlerini desteklemek için yalıtılmış çalışan işlemi gereklidir. Yalıtılmış çalışan işlemi işlevleri için uzantılar ad alanlarını kullanır Microsoft.Azure.Functions.Worker.Extensions.* .
  • İşlem içi model: İşlevler çalışma zamanıyla aynı işlemde çalışan derlenmiş C# işlevi. Bu modelin bir varyasyonunda, İşlevler öncelikle C# portalı düzenleme için desteklenen C# betiği kullanılarak çalıştırılabilir. İşlem içi işlevlerin uzantıları ad alanlarını kullanır Microsoft.Azure.WebJobs.Extensions.* .

Önemli

İşlem içi model desteği 10 Kasım 2026'da sona erecektir. Tam destek için uygulamalarınızı yalıtılmış çalışan modeline geçirmenizi kesinlikle öneririz.

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs.ToString()}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

Aşağıdaki örnekte, bir HTTP isteği tarafından tetiklendiğinde için kuyruk iletisi oluşturan bir Java işlevi gösterilmektedir.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "MyStorageConnectionAppSetting")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding<String> result) {
       result.setValue(message + " has been added.");
       return message;
 }

Java işlevleri çalışma zamanı kitaplığında, değeri Kuyruk depolamaya @QueueOutput yazılacak parametrelerde ek açıklamayı kullanın. Parametre türü olmalıdır OutputBinding<T>, burada T POJO'nun herhangi bir yerel Java türüdür.

Aşağıdaki örnekte, alınan her HTTP isteği için bir kuyruk öğesi oluşturan HTTP ile tetiklenen TypeScript işlevi gösterilmektedir.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body);
    return { body: 'Created queue item.' };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: httpTrigger1,
});

Birden çok iletinin çıktısını almak için tek bir nesne yerine bir dizi döndürebilirsiniz. Örneğin:

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

Aşağıdaki örnekte, alınan her HTTP isteği için bir kuyruk öğesi oluşturan HTTP ile tetiklenen JavaScript işlevi gösterilmektedir.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: async (request, context) => {
        const body = await request.text();
        context.extraOutputs.set(queueOutput, body);
        return { body: 'Created queue item.' };
    },
});

Birden çok iletinin çıktısını almak için tek bir nesne yerine bir dizi döndürebilirsiniz. Örneğin:

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

Aşağıdaki kod örnekleri, HTTP ile tetiklenen bir işlevden kuyruk iletisinin nasıl çıkarıldığı gösterilmektedir. ile yapılandırma bölümü typequeue çıkış bağlamasını tanımlar.

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "Msg",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

PowerShell işlevi bu bağlama yapılandırmasını kullanarak Push-OutputBindingbir kuyruk iletisi oluşturabilir. Bu örnekte, bir sorgu dizesinden veya gövde parametresinden bir ileti oluşturulur.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

Aynı anda birden çok ileti göndermek için bir ileti dizisi tanımlayın ve kuyruk çıkış bağlamasına ileti göndermek için kullanın Push-OutputBinding .

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = @("message1", "message2")
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

Aşağıdaki örnek, depolama kuyruklarına tek ve birden çok değerin nasıl çıkış yapılacağını gösterir. function.json için gereken yapılandırma her iki şekilde de aynıdır. Ö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="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)

    msg.set(input_msg)

    logging.info(f'name: {name}')
    return 'OK'

Özellikler

C# kitaplıklarında çıkış bağlamasını tanımlayan öznitelik, C# sınıf kitaplığının çalıştığı moda bağlıdır.

Yalıtılmış bir çalışan işleminde çalışırken, aşağıdaki örnekte gösterildiği gibi kuyruğun adını alan QueueOutputAttribute'u kullanırsınız:

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

Yalıtılmış bir çalışan işleminde çalıştırılırken yalnızca döndürülen değişkenler desteklenir. Çıkış parametreleri kullanılamaz.

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:queue_output

Özellik Açıklama
arg_name İşlev kodundaki kuyruğu temsil eden değişkenin adı.
queue_name Kuyruğun adı.
connection Azure Kuyruklarına 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

QueueOutput ek açıklaması, bir işlevin çıkışı olarak bir ileti yazmanızı sağlar. Aşağıdaki örnekte kuyruk iletisi oluşturan HTTP ile tetiklenen bir işlev gösterilmektedir.

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

public class HttpTriggerQueueOutput {
    @FunctionName("HttpTriggerQueueOutput")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") OutputBinding<String> message,
            final ExecutionContext context) {

        message.setValue(request.getQueryParameters().get("name"));
        return request.createResponseBuilder(HttpStatus.OK).body("Done").build();
    }
}
Ö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ı dizesi gösterir.

QueueOutput ek açıklamasıyla ilişkilendirilmiş parametre OutputBinding <T> örneği olarak yazılır.

Yapılandırma

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

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

Özellik Açıklama
queueName 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ğlan ions.

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

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

function.json özelliği Açıklama
type olarak ayarlanmalıdır queue. Bu özellik, Tetikleyiciyi Azure portalında oluşturduğunuzda otomatik olarak ayarlanır.
direction olarak ayarlanmalıdır out. Bu özellik, Tetikleyiciyi Azure portalında oluşturduğunuzda otomatik olarak ayarlanır.
Adı İşlev kodundaki kuyruğu temsil eden değişkenin adı. İşlev dönüş değerine başvurmak $return için olarak ayarlayın.
queueName 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ğlan ions.

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

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

Kullanım

Kuyruk çıkış bağlamasının 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:

Yalıtılmış çalışan işlem sınıfı kitaplığı derlenmiş C# işlevi çalışma zamanından yalıtılmış bir işlemde çalışır.

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

İşlevin tek bir ileti yazmasını istediğinizde, kuyruk çıkış bağlaması aşağıdaki türlere bağlanabilir:

Type Açıklama
string dize olarak ileti içeriği. İleti basit bir metin olduğunda kullanın.
byte[] İletinin baytları.
JSON serileştirilebilir türler JSON iletisinin içeriğini temsil eden nesne. İşlevler, düz eski bir CLR nesnesi (POCO) türünü JSON verilerine seri hale getirmeye çalışır.

İşlevin birden çok ileti yazmasını istediğinizde, kuyruk çıkış bağlaması aşağıdaki türlere bağlanabilir:

Type Açıklama
T[] burada T tek ileti türlerinden biridir Birden çok ileti için içerik içeren bir dizi. Her girdi bir iletiyi temsil eder.

Diğer çıkış senaryoları için Azure.Depolama'dan türler oluşturun ve kullanın. Doğrudan kuyruklar.

QueueOutput ek açıklamasını kullanarak bir işlevden kuyruğa yazmak için iki seçenek vardır:

  • Dönüş değeri: Ek açıklama işlevin kendisine uygulanarak işlevin dönüş değeri kuyruğa yazılır.

  • Kesinlik: İleti değerini açıkça ayarlamak için ek açıklamayı, pojo veya herhangi bir yerel Java türü olan T türündeki OutputBinding<T>belirli bir parametreye uygulayın. Bu yapılandırmayla, yöntemine setValue bir değer geçirerek değeri kuyruğa yazar.

Değeri doğrudan döndürerek veya kullanarak context.extraOutputs.set()çıkış kuyruğu öğesine erişin. Kuyruk öğesi yükü için bir dize veya JSON serileştirilebilir nesnesi kullanabilirsiniz.

Kuyruk iletisinin çıktısı, bağlamanın parametresi tarafından belirlenen adla eşleşen bağımsız değişkenleri function.json dosyasında geçirdiğiniz name yerde kullanılabilirPush-OutputBinding.

İşlevinizden yapılandırılan kuyruğa yazmak için iki seçenek vardır:

  • Dönüş değeri: function.json özelliğini olarak $returnayarlayınname. Bu yapılandırmayla işlevin dönüş değeri Kuyruk depolama iletisi olarak kalıcı hale getirilir.

  • Kesinlik: Out türü olarak bildirilen parametrenin set yöntemine bir değer geçirin. 'a set geçirilen değer Kuyruk depolama iletisi olarak kalıcıdır.

Bağlantılar

connection özelliği, uygulamanın Azure Kuyruklarına 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

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, "My Depolama" olarak ayarlarsanızconnection, İşlevler çalışma zamanı "AzureWebJobsMy Depolama" adlı bir uygulama ayarı arar. Boş bırakırsanızconnection, İşlevler çalışma zamanı adlı AzureWebJobsStorageuygulama ayarında varsayılan Depolama bağlantı dizesi kullanır.

Kimlik tabanlı bağlantılar

Uzantının 5.x veya üzeri bir sürümünü (non-.NET dil yığınları için paket 3.x veya üzeri) kullanıyorsanız, gizli dizi içeren bir bağlantı dizesi kullanmak yerine uygulamanın bir Microsoft Entra kimliği kullanmasını sağlayabilirsiniz. Kimlik kullanmak için, tetikleyici ve bağlama yapılandırmasındaki özelliğiyle connection eşleyen ortak bir ön ek altında ayarları tanımlarsınız.

"AzureWebJobs Depolama" olarak ayarlanıyorsanız connection bkz. Depolamayı kimlikle barındırmak için Bağlan. 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 diğer ö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. 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 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, Normal işlemde Kuyruk Depolama uzantısı 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, Kuyruk Veri İletisi Göndereni Depolama

Özel durumlar ve dönüş kodları

Bağlama Başvuru
Sıra Kuyruk Hata Kodları
Blob, Tablo, Kuyruk Depolama Hata Kodları
Blob, Tablo, Kuyruk Sorun giderme

Sonraki adımlar