Bagikan melalui


Pemicu Azure Queue Storage untuk Azure Functions

Pemicu penyimpanan antrean menjalankan fungsi saat pesan ditambahkan ke Azure Queue storage.

Keputusan penskalaan penyimpanan Azure Queue untuk paket Konsumsi dan Premium dilakukan melalui penskalaan berbasis target. Untuk informasi selengkapnya, lihat Penskalaan berbasis target.

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

Gunakan pemicu antrean untuk memulai fungsi saat item baru diterima di antrean. Pesan antrean disediakan sebagai masukan ke fungsi.

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.

Contoh berikut menunjukkan fungsi C# yang memilih antrean input-queue dan menulis log ke antrean output setiap kali item antrean diproses.

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

Contoh Java berikut menunjukkan fungsi pemicu antrean penyimpanan, yang mencatat pesan yang dipicu ditempatkan ke dalam antrean myqueuename.

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

Contoh berikut menunjukkan fungsi TypeScript pemicu antrean. Fungsi ini memilih myqueue-items antrean dan menulis log setiap kali item antrean diproses.

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

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    context.log('Storage queue function processed work item:', queueItem);
    context.log('expirationTime =', context.triggerMetadata.expirationTime);
    context.log('insertionTime =', context.triggerMetadata.insertionTime);
    context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
    context.log('id =', context.triggerMetadata.id);
    context.log('popReceipt =', context.triggerMetadata.popReceipt);
    context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    handler: storageQueueTrigger1,
});

Bagian penggunaan menjelaskan queueItem. Bagian metadata pesan menjelaskan semua variabel lain yang ditampilkan.

Contoh berikut menunjukkan antrean memicu fungsi JavaScript. Fungsi ini memilih myqueue-items antrean dan menulis log setiap kali item antrean diproses.

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

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    handler: (queueItem, context) => {
        context.log('Storage queue function processed work item:', queueItem);
        context.log('expirationTime =', context.triggerMetadata.expirationTime);
        context.log('insertionTime =', context.triggerMetadata.insertionTime);
        context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
        context.log('id =', context.triggerMetadata.id);
        context.log('popReceipt =', context.triggerMetadata.popReceipt);
        context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
    },
});

Bagian penggunaan menjelaskan queueItem. Bagian metadata pesan menjelaskan semua variabel lain yang ditampilkan.

Contoh berikut menunjukkan cara membaca pesan antrean yang diteruskan ke fungsi melalui pemicu.

Pemicu Storage queue didefinisikan dalam file function.json ketika type diatur ke queueTrigger.

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

Kode di file Run.ps1 menyatakan parameter sebagai $QueueItem, yang memungkinkan Anda untuk membaca pesan antrean dalam fungsi Anda.

# 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)"

Contoh berikut menunjukkan cara membaca pesan antrean yang diteruskan ke fungsi melalui pemicu. Contohnya tergantung pada apakah Anda menggunakan model pemrograman Python v1 atau v2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueFunc")
@app.queue_trigger(arg_name="msg", queue_name="inputqueue",
                   connection="storageAccountConnectionString")  # Queue trigger
@app.queue_output(arg_name="outputQueueItem", queue_name="outqueue",
                 connection="storageAccountConnectionString")  # Queue output binding
def test_function(msg: func.QueueMessage,
                  outputQueueItem: func.Out[str]) -> None:
    logging.info('Python queue trigger function processed a queue item: %s',
                 msg.get_body().decode('utf-8'))
    outputQueueItem.set('hello')

Atribut

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

Pada pustaka kelas C#, konstruktor atribut mengambil nama antrean untuk dipantau, seperti yang ditunjukkan dalam contoh berikut:

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

Contoh ini juga menunjukkan pengaturan string koneksi di atribut itu sendiri.

Anotasi

Anotasi QueueTrigger memberi Anda akses ke antrean yang memicu fungsi. Contoh berikut membuat pesan antrean tersedia untuk fungsi melalui parameter message.

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);
    }
}
Properti Deskripsi
name Menyatakan nama parameter dalam tanda tangan fungsi. Ketika fungsi dipicu, nilai parameter ini memiliki isi pesan antrean.
queueName Menyatakan nama antrean di akun penyimpanan.
connection Tunjuk ke string koneksi akun penyimpanan.

Dekorator

Hanya berlaku untuk model pemrograman Python v2.

Untuk fungsi Python v2 yang ditentukan menggunakan dekorator, properti berikut pada queue_trigger dekorator menentukan pemicu Queue Storage:

Properti Deskripsi
arg_name Menyatakan nama parameter dalam tanda tangan fungsi. Ketika fungsi dipicu, nilai parameter ini memiliki isi pesan antrean.
queue_name Menyatakan nama antrean di akun penyimpanan.
connection Tunjuk ke string koneksi akun penyimpanan.

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

Konfigurasi

Hanya berlaku untuk model pemrograman Python v1.

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

Properti Deskripsi
queueName Nama antrean untuk polling.
koneksi Nama pengaturan aplikasi atau koleksi pengaturan yang menentukan cara terhubung ke Azure Queue. Lihat Koneksi.

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

Properti function.json Deskripsi
jenis Harus diatur ke queueTrigger. Properti ini diatur secara otomatis saat Anda membuat pemicu di portal Microsoft Azure.
arah Hanya di file function.json. Harus diatur ke in. Properti ini diatur secara otomatis saat Anda membuat pemicu di portal Microsoft Azure.
nama Nama variabel yang berisi payload item antrean dalam kode fungsi.
queueName Nama antrean untuk polling.
koneksi Nama pengaturan aplikasi atau koleksi pengaturan yang menentukan cara terhubung ke Azure Queue. Lihat Koneksi.

Lihat Bagian contoh untuk contoh lengkapnya.

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

Penggunaan

Catatan

Fungsi mengharapkan string yang dikodekan base64. Setiap penyesuaian pada jenis pengodean (untuk menyiapkan data sebagai string yang dikodekan base64) perlu diimplementasikan dalam layanan panggilan.

Penggunaan pemicu Antrean tergantung pada versi paket ekstensi, dan modalitas C# yang digunakan di aplikasi fungsi Anda, yang dapat menjadi salah satu mode ini:

Pustaka kelas proses pekerja terisolasi yang dikompilasi fungsi C# berjalan dalam proses yang diisolasi dari runtime.

Pilih versi guna melihat detail penggunaan untuk mode dan versi.

Pemicu antrean dapat mengikat ke jenis berikut:

Tipe Deskripsi
string Konten pesan sebagai string. Gunakan saat pesan adalah teks sederhana..
byte[] Byte pesan.
Jenis yang bisa diserialisasikan JSON Saat pesan antrean berisi data JSON, Functions mencoba mendeserialisasi data JSON ke dalam jenis objek CLR (POCO) yang sudah lama.
QueueMessage1 Pesannya.
BinaryData1 Byte pesan.

1 Untuk menggunakan jenis ini, Anda perlu mereferensikan Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues 5.2.0 atau yang lebih baru dan dependensi umum untuk pengikatan jenis SDK.

Anotasi QueueTrigger memberi Anda akses ke pesan antrean yang memicu fungsi.

Akses item antrean sebagai argumen pertama ke fungsi Anda. Jika payload adalah JSON, nilai serinya dibatalkan menjadi objek.

Mengakses pesan antrean melalui parameter string yang cocok dengan nama yang ditunjuk oleh parameter pengikatan name dalam file function.json.

Mengakses pesan antrean melalui parameter yang diketik sebagai QueueMessage.

Metadata

Pemicu antrean menyediakan beberapa properti metadata. Properti ini dapat digunakan sebagai bagian dari ekspresi pengikatan dalam pengikatan lain atau sebagai parameter dalam kode Anda, untuk pekerja bahasa yang menyediakan akses ini ke metadata pesan.

Properti metadata pesan adalah anggota kelas CloudQueueMessage .

Properti metadata pesan dapat diakses dari context.triggerMetadata.

Properti metadata pesan dapat diakses dari parameter yang diteruskan $TriggerMetadata .

Properti Tipe Deskripsi
QueueTrigger string Payload antrean (jika string valid). Jika payload pesan antrean merupakan string, QueueTrigger memiliki nilai yang sama dengan variabel yang dinamai oleh propertiname di function.json.
DequeueCount long Berapa kali pesan ini telah dibatalkan antreannya.
ExpirationTime DateTimeOffset Saat pesan kedaluwarsa.
Id string ID pesan antrean.
InsertionTime DateTimeOffset Waktu pesan ditambahkan ke antrean.
NextVisibleTime DateTimeOffset Waktu pesan berikutnya akan ditampilkan.
PopReceipt string Tanda terima pop pesan.

Properti metadata pesan berikut dapat diakses dari parameter pengikatan yang diteruskan (msg dalam contoh sebelumnya).

Properti Deskripsi
body Antrean payload sebagai string.
dequeue_count Berapa kali pesan ini telah dibatalkan antreannya.
expiration_time Saat pesan kedaluwarsa.
id ID pesan antrean.
insertion_time Waktu pesan ditambahkan ke antrean.
time_next_visible Waktu pesan berikutnya akan ditampilkan.
pop_receipt Tanda terima pop pesan.

Koneksi

Properti connection adalah referensi ke konfigurasi lingkungan yang menentukan bagaimana aplikasi harus terhubung ke Azure Queues. 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 Mengelola kunci akses akun penyimpanan.

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 namanya di sini. Misalnya, jika Anda mengatur connection ke "MyStorage", runtime Functions mencari pengaturan aplikasi yang bernama "AzureWebJobsMyStorage." Jika Anda membiarkan connection kosong, runtime Functions menggunakan string koneksi Storage default dalam pengaturan aplikasi yang bernama AzureWebJobsStorage.

Koneksi berbasis identitas

Jika Anda menggunakan ekstensi versi 5.x atau yang lebih tinggi (bundel 3.x atau lebih tinggi untuk tumpukan bahasa non-.NET), alih-alih menggunakan string koneksi dengan rahasia, Anda dapat meminta aplikasi menggunakan identitas Microsoft Entra. Untuk menggunakan identitas, Anda menentukan pengaturan di bawah awalan umum yang memetakan ke connection properti dalam konfigurasi pemicu dan pengikatan.

Jika Anda mengatur connection ke "AzureWebJobsStorage", lihat Menyambungkan ke penyimpanan host dengan identitas. Untuk semua koneksi lainnya, ekstensi tersebut memerlukan properti berikut:

Properti Templat variabel lingkungan Deskripsi Contoh nilai
URI Layanan Antrean <CONNECTION_NAME_PREFIX>__queueServiceUri1 URI sarana data dari layanan antrean yang Anda sambungkan, menggunakan skema HTTPS. https://<storage_account_name>.queue.core.windows.net

1 <CONNECTION_NAME_PREFIX>__serviceUri dapat digunakan sebagai alias. Jika kedua formulir disediakan, queueServiceUri formulir akan digunakan. Formulir serviceUri tidak dapat digunakan saat konfigurasi koneksi keseluruhan akan digunakan di seluruh blob, antrean, dan/atau tabel.

Properti lain mungkin diatur untuk menyesuaikan koneksi. Lihat Properti umum untuk koneksi berbasis identitas.

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 antrean Anda saat runtime. Peran manajemen seperti Pemilik tidak cukup. Tabel berikut menunjukkan peran bawaan yang direkomendasikan saat menggunakan ekstensi Queue Storage dalam operasi normal. Aplikasi Anda mungkin memerlukan izin tambahan berdasarkan kode yang Anda tulis.

Jenis pengikatan Peran bawaan contoh
Pemicu Pembaca Data Antrean Penyimpanan, Pemroses Pesan Data Antrean Penyimpanan
Pengikatan output Kontributor Data Antrean Penyimpanan, Pengirim Pesan Data Antrean Penyimpanan

Pesan racun

Ketika fungsi pemicu antrean gagal, Azure Functions mencoba kembali fungsi hingga lima kali (termasuk percobaan pertama) untuk pesan antrean tertentu. Jika kelima upaya gagal, runtime fungsi akan menambahkan pesan ke antrean bernama <originalqueuename>-poison. Anda dapat menulis fungsi untuk memproses pesan dari antrean racun dengan mencatatnya atau mengirim pemberitahuan bahwa tindakan manual diperlukan.

Untuk menangani pesan racun secara manual, periksa dequeueCount dari pesan antrean.

Peek lock

Pola peek-lock terjadi secara otomatis untuk pemicu antrean, menggunakan mekanika visibilitas yang disediakan oleh layanan penyimpanan. Saat pesan dihentikan antreannya oleh fungsi yang dipicu, pesan ditandai sebagai tidak terlihat. Eksekusi fungsi yang dipicu antrean dapat memiliki salah satu hasil ini pada pesan dalam antrean:

  • Eksekusi fungsi berhasil diselesaikan dan pesan dihapus dari antrean.
  • Eksekusi fungsi gagal dan host Functions memperbarui visibilitas pesan berdasarkan visibilityTimeout pengaturan dalam file host.json. Batas waktu visibilitas default adalah nol, yang berarti bahwa pesan segera muncul kembali dalam antrean untuk pemrosesan ulang. visibilityTimeout Gunakan pengaturan untuk menunda pemrosesan ulang pesan yang gagal diproses. Pengaturan batas waktu ini berlaku untuk semua fungsi yang dipicu antrean di aplikasi fungsi.
  • Host Functions mengalami crash selama eksekusi fungsi. Ketika peristiwa yang jarang terjadi ini terjadi, host tidak dapat menerapkan ke visibilityTimeout pesan yang sedang diproses. Sebagai gantinya, pesan dibiarkan dengan batas waktu default 10 menit yang ditetapkan oleh layanan penyimpanan. Setelah 10 menit, pesan muncul kembali dalam antrean untuk pemrosesan ulang. Batas waktu default yang ditentukan layanan ini tidak dapat diubah.

Algoritma polling

Pemicu antrean mengimplementasikan algoritma back-off eksponensial acak untuk mengurangi efek polling antrean menganggur pada biaya transaksi penyimpanan.

Algoritma menggunakan logika berikut:

  • Ketika pesan ditemukan, runtime menunggu 100 milidetik lalu memeriksa pesan lain.
  • Ketika tidak ada pesan yang ditemukan, runtime menunggu sekitar 200 milidetik sebelum mencoba lagi.
  • Setelah upaya gagal berikutnya untuk mendapatkan pesan antrean, waktu tunggu terus meningkat sampai mencapai waktu tunggu maksimum default, yaitu satu menit.
  • Waktu tunggu maksimum dapat dikonfigurasi melalui properti maxPollingInterval di file host.json.

Selama pengembangan lokal, interval polling maksimum default menjadi dua detik.

Catatan

Sehubungan dengan penagihan saat menghosting aplikasi fungsi dalam paket Konsumsi, Anda tidak dikenakan biaya untuk waktu yang dihabiskan untuk polling pada saat runtime.

Konkurensi

Ketika beberapa pesan antrean menunggu, pemicu antrean mengambil batch pesan dan memanggil instans fungsi secara bersamaan untuk memprosesnya. Secara default, ukuran batch adalah 16. Ketika nomor yang sedang diproses turun ke 8, runtime mendapatkan batch lain dan mulai memproses pesan tersebut. Jadi, jumlah maksimum pesan serentak yang diproses per fungsi pada satu komputer virtual (VM) adalah 24. Batas ini berlaku secara terpisah untuk setiap fungsi yang dipicu antrean pada setiap VM. Jika aplikasi fungsi Anda menskalakan ke beberapa VM, setiap VM menunggu pemicu dan mencoba menjalankan fungsi. Misalnya, jika aplikasi fungsi menskalakan hingga 3 VM, jumlah maksimum default dari instans bersamaan dari satu fungsi yang dipicu antrean adalah 72.

Ukuran batch dan ambang batas untuk mendapatkan batch baru dapat dikonfigurasi di file host.json. Jika Anda ingin meminimalkan eksekusi paralel untuk fungsi yang dipicu antrean di aplikasi fungsi, atur ukuran batch menjadi 1. Pengaturan ini menghilangkan konkurensi hanya selama aplikasi fungsi Anda berjalan pada satu komputer virtual (VM).

Pemicu antrean secara otomatis mencegah fungsi memproses pesan antrean beberapa kali secara bersamaan.

properti host.json

Terdapat setelan file host.json yang mengontrol perilaku pemicu antrean. Lihat bagian pengaturan host.json untuk detail pengaturan yang tersedia.

Langkah berikutnya