Azure İşlevleri için Azure Service Bus çıkış bağlaması

  • Makale

Kuyruk veya konu iletileri göndermek için Azure Service Bus çıkış bağlamasını kullanın.

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.

Bu kod, öğesini ILoggertanımlar ve başlatır:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

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

Bu örnekte, bir ileti alan ve ikinci kuyruğa yazan bir C# işlevi gösterilir:

[Function(nameof(ServiceBusReceivedMessageFunction))]
[ServiceBusOutput("outputQueue", Connection = "ServiceBusConnection")]
public string ServiceBusReceivedMessageFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection")] ServiceBusReceivedMessage message)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

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

 

Bu örnekte hem HTTP yanıtı göndermek hem de çıkış iletisini yazmak için nesne içeren OutputType bir HTTP tetikleyicisi kullanılır.

[Function("HttpSendMsg")]
public async Task<OutputType> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req, FunctionContext context)
{
   _logger.LogInformation($"C# HTTP trigger function processed a request for {context.InvocationId}.");

   HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
   await response.WriteStringAsync("HTTP response: Message sent");

   return new OutputType()
   {
       OutputEvent = "MyMessage",
       HttpResponse = response
   };
}

Bu kod, üzerinde OutputEventService Bus çıkış bağlama tanımını içeren birden çok çıkış türünü OutputTypetanımlar:

 public class OutputType
{
   [ServiceBusOutput("TopicOrQueueName", Connection = "ServiceBusConnection")]
   public string OutputEvent { get; set; }

   public HttpResponseData HttpResponse { get; set; }
}

Aşağıdaki örnekte, bir HTTP isteği tarafından tetiklendiğinde Service Bus kuyruğuna myqueue ileti gönderen bir Java işlevi gösterilmektedir.

@FunctionName("httpToServiceBusQueue")
@ServiceBusQueueOutput(name = "message", queueName = "myqueue", connection = "AzureServiceBusConnection")
public String pushToQueue(
  @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
  final String message,
  @HttpOutput(name = "response") final OutputBinding<T> result ) {
      result.setValue(message + " has been sent.");
      return message;
 }

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

Java işlevleri bir Service Bus konusuna da yazabilir. Aşağıdaki örnek, çıkış bağlamasının @ServiceBusTopicOutput yapılandırmasını açıklamak için ek açıklamayı kullanır.

@FunctionName("sbtopicsend")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @ServiceBusTopicOutput(name = "message", topicName = "mytopicname", subscriptionName = "mysubscription", connection = "ServiceBusConnection") OutputBinding<String> message,
            final ExecutionContext context) {

        String name = request.getBody().orElse("Azure Functions");

        message.setValue(name);
        return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();

    }

Aşağıdaki örnekte, her 5 dakikada bir kuyruk iletisi gönderen bir zamanlayıcı tarafından tetiklenen TypeScript işlevi gösterilmektedir.

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

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.serviceBusQueue({
        queueName: 'testqueue',
        connection: 'MyServiceBusConnection',
    }),
    handler: timerTrigger1,
});

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

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Aşağıdaki örnekte, her 5 dakikada bir kuyruk iletisi gönderen zamanlayıcı tarafından tetiklenen JavaScript işlevi gösterilmektedir.

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

const serviceBusOutput = output.serviceBusQueue({
    queueName: 'testqueue',
    connection: 'MyServiceBusConnection',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: serviceBusOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

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

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Aşağıdaki örnekte, bir function.json dosyasında service bus çıkış bağlaması ve bağlamayı kullanan bir PowerShell işlevi gösterilmektedir.

function.json dosyasındaki bağlama verileri aşağıdadır:

{
  "bindings": [
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "outputSbMsg",
      "queueName": "outqueue",
      "topicName": "outtopic"
    }
  ]
}

burada, işlevin çıkışı olarak bir ileti oluşturan PowerShell yer alır.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name outputSbMsg -Value @{ 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

Aşağıdaki örnekte, Python'da service bus kuyruğuna nasıl yazabilirsiniz gösterilmektedir. Ö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.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="<CONNECTION_SETTING>",
                              topic_name="<TOPIC_NAME>")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

Özellikler

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

C# sınıf kitaplıklarında, çıkış tarafından yazılan kuyruğu veya konuyu tanımlamak için ServiceBusOutputAttribute'u kullanın.

Aşağıdaki tabloda özniteliğini kullanarak ayarlayabileceğiniz özellikler açıklanmaktadır:

Özellik Açıklama
Entitytype Varlık türünü kuyruğa ileti göndermek veya Topic bir konuya ileti gönderirken olarak Queue ayarlar.
QueueOrTopicName İleti gönderilecek konunun veya kuyruğun adı. Hedef türünü ayarlamak için kullanın EntityType .
Bağlantı Service Bus'a nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. 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:service_bus_topic_output

Özellik Açıklama
arg_name İşlev kodundaki kuyruk veya konu iletisini temsil eden değişkenin adı.
queue_name Kuyruğun adı. Bir konu için değil, yalnızca kuyruk iletileri gönderiliyorsa ayarlayın.
topic_name Konunun adı. Kuyruk için değil, yalnızca konu iletileri gönderiliyorsa ayarlayın.
connection Service Bus'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

ServiceBusQueueOutput ve ServiceBusTopicOutput ek açıklamaları, bir iletiyi işlev çıkışı olarak yazmak için kullanılabilir. Bu ek açıklamalarla süslenen parametre, iletinin türüne karşılık gelen tür olan bir OutputBinding<T> yer T olarak bildirilmelidir.

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

Yapılandırma

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

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

Özellik Açıklama
queueName Kuyruğun adı.
Bağlantı Service Bus'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, yöntemine geçirilen output.serviceBusTopic() nesnede options ayarlayabileceğiniz özellikler açıklanmaktadır.

Özellik Açıklama
topicName Konunun adı.
Bağlantı Service Bus'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.

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

function.json özelliği Açıklama
type "serviceBus" olarak ayarlanmalıdır. Bu özellik, Tetikleyiciyi Azure portalında oluşturduğunuzda otomatik olarak ayarlanır.
direction "Out" olarak ayarlanmalıdır. Bu özellik, Tetikleyiciyi Azure portalında oluşturduğunuzda otomatik olarak ayarlanır.
Adı İşlev kodundaki kuyruk veya konu iletisini temsil eden değişkenin adı. İşlev dönüş değerine başvurmak için "$return" olarak ayarlayın.
queueName Kuyruğun adı. Bir konu için değil, yalnızca kuyruk iletileri gönderiliyorsa ayarlayın.
topicName Konunun adı. Kuyruk için değil, yalnızca konu iletileri gönderiliyorsa ayarlayın.
Bağlantı Service Bus'a nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. Bkz. Bağlan ions.
accessRights (yalnızca v1) bağlantı dizesi erişim hakları. Kullanılabilir değerler ve listendeğerleridirmanage. Varsayılan değer, 'nin Yönet iznine sahip olduğunu connection gösteren değeridirmanage. Yönetme izni olmayan bir bağlantı dizesi kullanıyorsanız, "dinleme" olarak ayarlayınaccessRights. Aksi takdirde, İşlevler çalışma zamanı yönetme hakları gerektiren işlemleri gerçekleştirmeye çalışmayabilir. Service Bus SDK'sının en son sürümü işlemleri yönetmeyi desteklemediğinden, Azure İşlevleri sürüm 2.x ve üzeri sürümlerde bu özellik kullanılamaz.

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

Aşağıdaki çıkış parametresi türleri tüm C# modaliteleri ve uzantı sürümleri tarafından desteklenir:

Type Açıklama
System Yazacak ileti basit bir metin olduğunda kullanın. İşlev çıktığında parametre değeri null olduğunda İşlevler ileti oluşturmaz.
bayt[] İkili veri iletileri yazmak için kullanın. İşlev çıktığında parametre değeri null olduğunda İşlevler ileti oluşturmaz.
Nesne bir ileti JSON içerdiğinde İşlevler nesneyi bir JSON ileti yüküne serileştirir. İşlev çıktığında parametre değeri null olduğunda İşlevler, null nesne içeren bir ileti oluşturur.

Mesajlaşmaya özgü parametre türleri ek ileti meta verileri içerir. Çıkış bağlaması tarafından desteklenen belirli türler İş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 ileti yazmasını istediğinizde, Service Bus çıkış bağlaması aşağıdaki türlere bağlanabilir:

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

İşlevin birden çok ileti yazmasını istediğinizde, Service Bus çı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çeren bir dizi. Her girdi bir iletiyi temsil eder.

Diğer çıkış senaryoları için, doğrudan Azure.Messaging.ServiceBus'tan türler oluşturun ve kullanın.

Azure İşlevleri 1.x'te çalışma zamanı, mevcut değilse ve olarak ayarladıysanız accessRightsmanagekuyruğu oluşturur. Azure İşlevleri sürüm 2.x ve üzeri sürümlerde kuyruk veya konu zaten mevcut olmalıdır; mevcut olmayan bir kuyruk veya konu belirtirseniz işlev başarısız olur.

Yerleşik çıkış bağlaması yerine Azure Service Bus SDK'sını kullanın.

Değeri doğrudan döndürerek veya kullanarak context.extraOutputs.set()çıkış iletisine erişin.

Service Bus çıktısı, function.json dosyasında bağlamanın Push-OutputBinding ad parametresi tarafından belirlenen adla eşleşen bağımsız değişkenleri geçirdiğiniz cmdlet aracılığıyla kullanılabilir.

Yerleşik çıkış bağlaması yerine Azure Service Bus SDK'sını kullanın.

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

Bağlantılar

connection özelliği, uygulamanın Service Bus'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

bağlantı dizesi almak için Yönetim kimlik bilgilerini alma konusunda gösterilen adımları izleyin. bağlantı dizesi, belirli bir kuyruk veya konu başlığıyla sınırlı olmayan bir Service Bus ad alanı için 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.

Uygulama ayarı adı "AzureWebJobs" ile başlıyorsa, adın yalnızca kalanını belirtebilirsiniz. Örneğin, "MyServiceBus" olarak ayarlarsanız connection , İşlevler çalışma zamanı "AzureWebJobsMyServiceBus" adlı bir uygulama ayarı arar. Boş bırakırsanızconnection, İşlevler çalışma zamanı "AzureWebJobsServiceBus" adlı uygulama ayarında varsayılan Service Bus bağlantı dizesi 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 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 Service Bus ad alanı. <>service_bus_namespace.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 konularınıza ve kuyruklarınıza 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 Service Bus 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
Tetikleyici1 Azure Service Bus Veri Alıcısı, Azure Service Bus Veri Sahibi
Çıkış bağlaması Azure Service Bus Veri Göndereni

1 Service Bus konu başlıklarından tetikleme için rol atamasının Service Bus abonelik kaynağı üzerinde etkili bir kapsama sahip olması gerekir. Sadece konu dahil edilirse bir hata oluşur. Azure portal gibi bazı istemciler Service Bus abonelik kaynağını rol atama kapsamı olarak kullanıma sunmaz. Bu gibi durumlarda bunun yerine Azure CLI kullanılabilir. Daha fazla bilgi edinmek için bkz . Azure Service Bus için Azure yerleşik rolleri.

Özel durumlar ve dönüş kodları

Bağlama Başvuru
Service Bus Service Bus Hata Kodları
Service Bus Service Bus Sınırları

Sonraki adımlar