Pengikatan output Microsoft Azure Service Bus untuk Azure Functions
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 OutputType
output , 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.
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:
- Nama pengaturan aplikasi yang berisi string koneksi
- Nama awalan bersama untuk beberapa pengaturan aplikasi, bersama-sama menentukan koneksi berbasis identitas.
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 |