Share via

Pengikatan output Microsoft Azure Service Bus untuk Azure Functions

  • Artikel

Gunakan pengikatan output Microsoft Azure Service Bus untuk mengirim pesan antrean atau topik.

Untuk informasi tentang pengaturan dan detail konfigurasi, lihat gambaran umum.

Penting

Artikel ini menggunakan tab untuk mendukung beberapa versi model pemrograman Node.js. Model v4 umumnya tersedia dan dirancang untuk memiliki pengalaman yang lebih fleksibel dan intuitif untuk pengembang JavaScript dan TypeScript. Untuk detail selengkapnya tentang cara kerja model v4, lihat panduan pengembang Node.js Azure Functions. Untuk mempelajari selengkapnya tentang perbedaan antara v3 dan v4, lihat panduan migrasi.

Azure Functions mendukung dua model pemrograman untuk Python. Cara Anda menentukan pengikatan tergantung pada model pemrograman yang Anda pilih.

Model pemrograman Python v2 memungkinkan Anda menentukan pengikatan menggunakan dekorator langsung dalam kode fungsi Python Anda. Untuk informasi selengkapnya, lihat panduan pengembang Python.

Artikel ini mendukung kedua model pemrograman.

Contoh

Fungsi C# dapat dibuat dengan menggunakan salah satu mode C# berikut:

  • Model pekerja terisolasi: Fungsi C# terkompilasi yang berjalan dalam proses pekerja yang terisolasi dari runtime. Proses pekerja terisolasi diperlukan untuk mendukung fungsi C# yang berjalan pada versi LTS dan non-LTS .NET dan .NET Framework. Ekstensi untuk fungsi proses pekerja yang terisolasi menggunakan Microsoft.Azure.Functions.Worker.Extensions.* namespace layanan.
  • Model dalam proses: Fungsi C# yang dikompilasi yang berjalan dalam proses yang sama dengan runtime Functions. Dalam variasi model ini, Functions dapat dijalankan menggunakan scripting C#, yang didukung terutama untuk pengeditan portal C#. Ekstensi untuk fungsi dalam proses menggunakan Microsoft.Azure.WebJobs.Extensions.* namespace layanan.

Penting

Dukungan akan berakhir untuk model dalam proses pada 10 November 2026. Kami sangat menyarankan Agar Anda memigrasikan aplikasi Anda ke model pekerja yang terisolasi untuk dukungan penuh.

Kode ini mendefinisikan dan menginisialisasi ILogger:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

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

Contoh ini menunjukkan fungsi C# yang menerima pesan dan menulisnya ke antrean kedua:

[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;
}

 

Contoh ini menggunakan pemicu HTTP dengan OutputType objek untuk mengirim respons HTTP dan menulis pesan output.

[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
   };
}

Kode ini mendefinisikan beberapa jenis OutputTypeoutput , yang mencakup definisi pengikatan output Bus Layanan pada OutputEvent:

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

   public HttpResponseData HttpResponse { get; set; }
}

Contoh berikut menunjukkan fungsi Java yang mengirim pesan ke antrean Microsoft Azure Service Bus myqueue saat dipicu oleh permintaan HTTP.

@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;
 }

Dalam pustaka runtime fungsi Java, gunakan anotasi @QueueOutput pada parameter fungsi yang nilainya akan ditulis ke antrean Microsoft Azure Service Bus. Jenis parameter harus OutputBinding<T>, yaitu T adalah jenis Java asli dari POJO.

Fungsi Java juga dapat menulis ke topik Microsoft Azure Service Bus. Contoh berikut menggunakan anotasi @ServiceBusTopicOutput untuk menjelaskan konfigurasi untuk pengikatan output.

@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();

    }

Contoh berikut menunjukkan fungsi TypeScript yang dipicu timer yang mengirim pesan antrean setiap 5 menit.

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,
});

Untuk menghasilkan beberapa pesan, kembalikan array alih-alih satu objek. Contohnya:

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

Contoh berikut menunjukkan fungsi JavaScript yang dipicu timer yang mengirim pesan antrean setiap 5 menit.

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}`;
    },
});

Untuk menghasilkan beberapa pesan, kembalikan array alih-alih satu objek. Contohnya:

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

Contoh berikut menunjukkan pengikatan pemicu Microsoft Azure Service Bus dalam file function.json dan fungsi PowerShell yang menggunakan pengikatan.

Berikut data pengikatan dalam file function.json:

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

Berikut adalah PowerShell yang membuat pesan sebagai output fungsi.

param($QueueItem, $TriggerMetadata) 

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

Contoh berikut menunjukkan cara menulis ke antrean Microsoft Azure Service Bus dengan Python. Contohnya tergantung pada apakah Anda menggunakan model pemrograman Python v1 atau v2.

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'

Atribut

Pustaka C# proses dalam proses dan terisolasi menggunakan atribut untuk menentukan pengikatan output. Skrip C# sebagai gantinya menggunakan file konfigurasi function.json seperti yang dijelaskan dalam panduan pembuatan skrip C#.

Di pustaka kelas C#, gunakan ServiceBusOutputAttribute untuk menentukan antrean atau topik yang ditulis oleh output.

Tabel berikut menjelaskan properti yang bisa Anda atur menggunakan atribut tersebut:

Properti Deskripsi
EntityType Mengatur jenis entitas sebagai Queue untuk mengirim pesan ke antrean atau Topic saat mengirim pesan ke topik.
QueueOrTopicName Nama topik atau antrean untuk mengirim pesan. Gunakan EntityType untuk mengatur jenis tujuan.
Koneksi Nama pengaturan aplikasi atau koleksi pengaturan yang menentukan cara terhubung ke Azure Service Bus. Lihat Koneksi.

Dekorator

Hanya berlaku untuk model pemrograman Python v2.

Untuk fungsi Python v2 yang ditentukan menggunakan dekorator, properti berikut pada service_bus_topic_output:

Properti Deskripsi
arg_name Nama variabel yang mewakili antrean atau pesan topik dalam kode fungsi.
queue_name Nama antrean. Atur hanya jika mengirim pesan antrean, bukan untuk topik.
topic_name Nama topik. Atur hanya jika mengirim pesan topik, bukan untuk antrean.
connection Nama pengaturan aplikasi atau koleksi pengaturan yang menentukan cara terhubung ke Azure Service Bus. Lihat Koneksi.

Untuk fungsi Python yang ditentukan dengan menggunakan function.json, lihat bagian Konfigurasi .

Anotasi

Anotasi ServiceBusQueueOutput dan ServiceBusTopicOutput tersedia untuk menulis pesan sebagai output fungsi. Parameter yang didekorasi dengan anotasi ini harus dinyatakan sebagai OutputBinding<T> di mana T adalah jenis yang sesuai dengan jenis pesan.

Ketika Anda mengembangkan secara lokal, tambahkan pengaturan aplikasi di file local.settings.json dalam koleksi Values.

Konfigurasi

Hanya berlaku untuk model pemrograman Python v1.

Tabel berikut menjelaskan properti yang bisa Anda atur pada objek yang options diteruskan ke output.serviceBusQueue() metode .

Properti Deskripsi
queueName Nama antrean.
koneksi Nama pengaturan aplikasi atau koleksi pengaturan yang menentukan cara terhubung ke Azure Service Bus. Lihat Koneksi.

Tabel berikut menjelaskan properti yang bisa Anda atur pada objek yang options diteruskan ke output.serviceBusTopic() metode .

Properti Deskripsi
topicName Nama topik.
koneksi Nama pengaturan aplikasi atau koleksi pengaturan yang menentukan cara terhubung ke Azure Service Bus. Lihat Koneksi.

Ketika Anda mengembangkan secara lokal, tambahkan pengaturan aplikasi di file local.settings.json dalam koleksi Values.

Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda tetapkan di file function.json dan ServiceBus atributnya.

Properti function.json Deskripsi
jenis Harus diatur ke "serviceBus". Properti ini diatur secara otomatis saat Anda membuat pemicu di portal Microsoft Azure.
arah Harus diatur ke "out". Properti ini diatur secara otomatis saat Anda membuat pemicu di portal Microsoft Azure.
nama Nama variabel yang mewakili antrean atau pesan topik dalam kode fungsi. Atur ke "$return" untuk mereferensikan nilai pengembalian fungsi.
queueName Nama antrean. Atur hanya jika mengirim pesan antrean, bukan untuk topik.
topicName Nama topik. Atur hanya jika mengirim pesan topik, bukan untuk antrean.
koneksi Nama pengaturan aplikasi atau koleksi pengaturan yang menentukan cara terhubung ke Azure Service Bus. Lihat Koneksi.
accessRights (hanya v1) Hak akses untuk string koneksi. Nilai yang tersedia adalah manage dan listen. Defaultnya adalah manage, yang menunjukkan bahwa connection memiliki izin Kelola. Jika Anda menggunakan string koneksi yang tidak memiliki izin Kelola, atur accessRights ke "dengarkan". Jika tidak, runtime Azure Functions mungkin gagal melakukan operasi yang memerlukan hak kelola. Di Azure Functions versi 2.x dan yang lebih tinggi, properti ini tidak tersedia karena versi terbaru Bus Layanan SDK tidak mendukung operasi kelola.

Ketika Anda mengembangkan secara lokal, tambahkan pengaturan aplikasi di file local.settings.json dalam koleksi Values.

Lihat Bagian contoh untuk contoh lengkapnya.

Penggunaan

Jenis parameter output berikut didukung oleh semua modalitas C# dan versi ekstensi:

Tipe Deskripsi
System.String Gunakan saat menulis pesan teks sederhana. Jika nilai parameter null ketika fungsi keluar, Azure Functions tidak membuat pesan.
byte[] Gunakan untuk menulis pesan data biner. Jika nilai parameter null ketika fungsi keluar, Azure Functions tidak membuat pesan.
Objek Saat pesan berisi JSON, Functions menserialisasikan objek tersebut ke dalam payload pesan JSON. Jika nilai parameter null ketika fungsi keluar, Azure Functions membuat pesan dengan objek null.

Jenis parameter khusus olahpesan berisi metadata pesan tambahan. Jenis tertentu yang didukung oleh pengikatan output tergantung pada versi runtime Functions, versi paket ekstensi, dan modalitas C# yang digunakan.

Saat Anda ingin fungsi menulis satu pesan, pengikatan output Bus Layanan dapat mengikat ke jenis berikut:

Tipe Deskripsi
string Pesan sebagai string. Gunakan saat pesan adalah teks sederhana.
byte[] Byte pesan.
Jenis yang bisa diserialisasikan JSON Objek yang mewakili pesan. Fungsi mencoba menserialisasikan jenis objek CLR (POCO) lama biasa ke dalam data JSON.

Saat Anda ingin fungsi menulis beberapa pesan, pengikatan output Bus Layanan dapat mengikat ke jenis berikut:

Tipe Deskripsi
T[] di mana T adalah salah satu jenis pesan tunggal Array yang berisi beberapa pesan. Setiap entri mewakili satu pesan.

Untuk skenario output lainnya, buat dan gunakan jenis dari Azure.Messaging.ServiceBus secara langsung.

Di Azure Functions 1.x, runtime membuat antrean jika tidak ada dan Anda telah mengatur accessRights ke manage. Di Azure Functions versi 2.x dan yang lebih tinggi, antrean atau topik harus sudah ada; jika Anda menentukan antrean atau topik yang tidak ada, fungsi gagal.

Gunakan Microsoft Azure Service Bus SDK daripada pengikatan output bawaan.

Akses pesan output dengan mengembalikan nilai secara langsung atau menggunakan context.extraOutputs.set().

Keluaran ke Microsoft Azure Service Bus tersedia melalui cmdlet Push-OutputBinding tempat Anda meneruskan argumen yang cocok dengan nama yang ditentukan oleh parameter nama pengikatan dalam file function.json.

Gunakan Microsoft Azure Service Bus SDK daripada pengikatan output bawaan.

Untuk contoh lengkapnya, lihat bagian contoh.

Koneksi

Properti connection adalah referensi ke konfigurasi lingkungan yang menentukan bagaimana aplikasi seharusnya tersambung ke Bus Layanan. Ini mungkin menentukan:

Jika nilai yang dikonfigurasi adalah kecocokan persis untuk pengaturan tunggal dan kecocokan awalan untuk pengaturan lainnya, kecocokan persis akan digunakan.

String koneksi

Untuk mendapatkan string koneksi, ikuti langkah-langkah yang ditunjukkan di Dapatkan Informasi masuk manajemen. String koneksi harus untuk namespace Bus Layanan, tidak terbatas pada antrean atau topik tertentu.

String koneksi ini harus disimpan dalam pengaturan aplikasi dengan nama yang cocok dengan nilai yang ditentukan oleh properti connection konfigurasi pengikatan.

Jika nama pengaturan aplikasi dimulai dengan "AzureWebJobs", Anda hanya dapat menentukan sisa nama. Misalnya, jika Anda mengatur connection ke "MyServiceBus", runtime Azure Functions mencari pengaturan aplikasi yang bernama "AzureWebJobsMyServiceBus". Jika Anda membiarkan connection kosong, runtime Azure Functions menggunakan string koneksi Microsoft Azure Service Bus default di pengaturan aplikasi yang diberi nama "AzureWebJobsServiceBus".

Koneksi berbasis identitas

Jika Anda menggunakan ekstensi versi 5.x atau yang lebih tinggi, alih-alih menggunakan string koneksi dengan rahasia, Anda dapat meminta aplikasi menggunakan identitas Microsoft Entra. Untuk melakukan ini, Anda harus menentukan pengaturan di bawah awalan umum yang memetakan ke properti connection dalam konfigurasi pemicu dan pengikatan.

Dalam mode ini, ekstensi tersebut memerlukan properti berikut:

Properti Templat variabel lingkungan Deskripsi Contoh nilai
Namespace yang Sepenuhnya Memenuhi Syarat <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Namespace layanan Bus Layanan yang sepenuhnya memenuhi syarat. <service_bus_namespace>.servicebus.windows.net

Properti tambahan dapat diatur untuk menyesuaikan koneksi. Lihat Properti umum untuk koneksi berbasis identitas.

Catatan

Saat menggunakan Azure App Configuration atau Key Vault guna menyediakan pengaturan untuk koneksi Identitas Terkelola, nama pengaturan harus menggunakan pemisah kunci yang valid seperti : atau / sebagai ganti __ untuk memastikan nama diselesaikan dengan benar.

Contohnya,<CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Saat dihosting di layanan Azure Functions, koneksi berbasis identitas menggunakan identitas terkelola. Identitas yang ditetapkan sistem digunakan secara default, meskipun identitas yang ditetapkan pengguna dapat ditentukan dengan credential dan clientID properti. Perhatikan bahwa mengonfigurasi identitas yang ditetapkan oleh pengguna dengan ID sumber daya tidak didukung. Saat dijalankan dalam konteks lain, seperti pengembangan lokal, identitas pengembang Anda digunakan sebagai gantinya, meskipun ini dapat dikustomisasi. Lihat Pengembangan lokal dengan koneksi berbasis identitas.

Memberikan izin kepada identitas

Identitas apa pun yang digunakan harus memiliki izin untuk melakukan tindakan yang dimaksudkan. Untuk sebagian besar layanan Azure, ini berarti Anda perlu menetapkan peran di Azure RBAC, menggunakan peran bawaan atau kustom yang menyediakan izin tersebut.

Penting

Beberapa izin mungkin diekspos oleh layanan target yang tidak diperlukan untuk semua konteks. Jika memungkinkan, patuhi prinsip hak istimewa paling rendah, dengan memberikan identitas hanya hak istimewa yang diperlukan. Misalnya, jika aplikasi hanya perlu dapat membaca dari sumber data, gunakan peran yang hanya memiliki izin untuk membaca. Tidak pantas untuk menetapkan peran yang juga memungkinkan menulis ke layanan itu, karena ini akan menjadi izin yang berlebihan untuk operasi baca. Demikian pula, Anda ingin memastikan penetapan peran hanya mencakup sumber daya yang perlu dibaca.

Anda akan perlu membuat penetapan peran yang menyediakan akses ke topik dan antrean Anda saat runtime. Peran manajemen seperti Pemilik tidak cukup. Tabel berikut menunjukkan peran bawaan yang direkomendasikan saat menggunakan ekstensi Bus Layanan dalam operasi normal. Aplikasi Anda mungkin memerlukan izin tambahan berdasarkan kode yang Anda tulis.

Jenis pengikatan Peran bawaan contoh
Pemicu 1 Penerima Data Azure Service Bus, Pemilik Data Azure Service Bus
Pengikatan output Azure Service Bus Data Sender

1 Untuk memicu dari topik Bus Layanan, penetapan peran harus memiliki cakupan yang efektif atas sumber daya langganan Bus Layanan. Jika hanya topik yang disertakan, kesalahan akan terjadi. Beberapa klien, seperti portal Azure, tidak mengekspos sumber daya langganan Bus Layanan sebagai cakupan untuk penetapan peran. Dalam kasus seperti itu, Azure CLI dapat digunakan sebagai gantinya. Untuk mempelajari selengkapnya, lihat Peran bawaan Azure untuk Azure Service Bus.

Kode pengecualian dan pengembalian

Pengikatan Referensi
Service Bus Kode Kesalahan Microsoft Azure Service Bus
Service Bus Batas Microsoft Azure Service Bus

Langkah berikutnya