Bagikan melalui

Pengikatan output Azure Event Hubs untuk Azure Functions

  • Artikel

Artikel ini menjelaskan cara bekerja dengan pengikatan Azure Event Hubs untuk Azure Functions. Azure Functions mendukung pemicu dan pengikatan output untuk Event Hubs.

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

Gunakan pengikatan output Pusat Aktivitas untuk menulis acara ke aliran acara. Anda harus telah mengirimkan izin ke hub peristiwa untuk menuliskan acaranya.

Pastikan referensi paket yang diperlukan ada sebelum Anda mencoba menerapkan pengikatan output.

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

Contoh berikut menunjukkan fungsi C# yang menulis string pesan ke pusat aktivitas, menggunakan nilai pengembalian metode sebagai output:

[Function(nameof(EventHubFunction))]
[FixedDelayRetry(5, "00:00:10")]
[EventHubOutput("dest", Connection = "EventHubConnection")]
public string EventHubFunction(
    [EventHubTrigger("src", Connection = "EventHubConnection")] string[] input,
    FunctionContext context)
{
    _logger.LogInformation("First Event Hubs triggered message: {msg}", input[0]);

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

Contoh berikut menunjukkan fungsi TypeScript yang dipicu timer yang mengirim satu pesan ke pusat aktivitas:

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.eventHub({
        eventHubName: 'myeventhub',
        connection: 'MyEventHubSendAppSetting',
    }),
    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 satu pesan ke pusat aktivitas:

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

const eventHubOutput = output.eventHub({
    eventHubName: 'myeventhub',
    connection: 'MyEventHubSendAppSetting',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: eventHubOutput,
    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 PowerShell lengkap sedang tertunda.

Contoh berikut menunjukkan pengikatan pemicu pusat aktivitas dan fungsi Python yang menggunakan pengikatan. Fungsi ini menulis pesan ke hub acara. 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="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")
def eventhub_output(req: func.HttpRequest, event: func.Out[str]):
    body = req.get_body()
    if body is not None:
        event.set(body.decode('utf-8'))
    else:    
        logging.info('req body is none')
    return 'ok'

Berikut kode Python yang mengirim beberapa pesan:

import logging
import azure.functions as func
from typing import List

app = func.FunctionApp()

@app.function_name(name="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")

def eventhub_output(req: func.HttpRequest, event: func.Out[List[str]]) -> func.HttpResponse:
    my_messages=["message1", "message2","message3"]
    event.set(my_messages)
    return func.HttpResponse(f"Messages sent")

Contoh berikut menunjukkan fungsi Java yang menulis pesan yang berisi waktu saat ini ke hub peristiwa.

@FunctionName("sendTime")
@EventHubOutput(name = "event", eventHubName = "samples-workitems", connection = "AzureEventHubConnection")
public String sendTime(
   @TimerTrigger(name = "sendTimeTrigger", schedule = "0 */5 * * * *") String timerInfo)  {
     return LocalDateTime.now().toString();
 }

Di pustaka runtime fungsi Java, gunakan @EventHubOutput anotasi pada parameter yang nilainya akan diterbitkan ke Azure Event Hubs. Parameter harus berdasarkan jenis OutputBinding<T>, ketika T adalah POJO atau jenis Java asli.

Atribut

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

Gunakan [EventHubOutputAttribute] untuk menentukan pengikatan output ke pusat aktivitas, yang mendukung properti berikut.

Parameter Deskripsi
EventHubName Nama event hub. Ketika nama event hub juga ada dalam string koneksi, nilai tersebut menimpa properti ini di runtime.
Koneksi Nama pengaturan aplikasi atau kumpulan pengaturan yang menentukan cara menyambungkan ke Azure Event Hubs. Untuk mempelajari selengkapnya, lihat Koneksi.

Dekorator

Hanya berlaku untuk model pemrograman Python v2.

Untuk fungsi Python v2 yang ditentukan menggunakan dekorator, properti ini didukung untuk event_hub_output:

Properti Deskripsi
arg_name Nama variabel yang digunakan dalam kode fungsi yang mewakili acara.
event_hub_name dia nama pusat aktivitas. Ketika nama event hub juga ada dalam string koneksi, nilai tersebut menimpa properti ini di runtime.
connection Nama pengaturan aplikasi atau kumpulan pengaturan yang menentukan cara menyambungkan ke Azure Event Hubs. Untuk mempelajari selengkapnya, lihat Koneksi.

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

Anotasi

Di pustaka runtime fungsi Java, gunakan anotasi EventHubOutput pada parameter yang nilainya akan diterbitkan ke Azure Event Hubs. Pengaturan berikut didukung pada anotasi:

Konfigurasi

Hanya berlaku untuk model pemrograman Python v1.

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

Properti Deskripsi
eventHubName Nama event hub. Ketika nama event hub juga ada dalam string koneksi, nilai tersebut menimpa properti ini di runtime.
koneksi Nama pengaturan aplikasi atau kumpulan pengaturan yang menentukan cara menyambungkan ke Azure Event Hubs. Untuk mempelajari selengkapnya, lihat Koneksi.

Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda atur di file function.json, yang dibedakan oleh versi runtime.

Properti function.json Deskripsi
jenis Harus diatur ke eventHub.
arah Harus diatur ke out. Parameter ini diatur secara otomatis saat Anda membuat pengikatan di portal Azure.
nama Nama variabel yang digunakan dalam kode fungsi yang mewakili acara.
eventHubName Functions 2.x dan yang lebih tinggi. Nama event hub. Ketika nama event hub juga ada dalam string koneksi, nilai tersebut menimpa properti ini di runtime.
koneksi Nama pengaturan aplikasi atau kumpulan pengaturan yang menentukan cara menyambungkan ke Azure Event Hubs. Untuk mempelajari selengkapnya, lihat Koneksi.

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

Penggunaan

Jenis parameter yang didukung oleh pengikatan output Azure Event Hubs tergantung pada versi runtime Functions, versi paket ekstensi, dan modalitas C# yang digunakan.

Saat Anda ingin fungsi menulis satu peristiwa, pengikatan output Azure Event Hubs dapat mengikat ke jenis berikut:

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

Saat Anda ingin fungsi menulis beberapa peristiwa, pengikatan output Azure Event Hubs dapat mengikat ke jenis berikut:

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

Untuk skenario output lainnya, buat dan gunakan jenis dari Microsoft.Azure.EventHubs secara langsung.

Ada dua opsi untuk menghasilkan pesan Azure Event Hubs dari fungsi dengan menggunakan anotasi EventHubOutput :

  • Mengembalikan nilai: Dengan menerapkan anotasi ke fungsi itu sendiri, nilai pengembalian fungsi dipertahankan sebagai pesan Azure Event Hubs.

  • Imperatif: Untuk secara eksplisit mengatur nilai pesan, terapkan anotasi ke parameter tertentu dari jenis OutputBinding<T> tersebut, di mana T merupakan POJO atau jenis Java asli. Dengan konfigurasi ini, meneruskan nilai ke setValue metode mempertahankan nilai sebagai pesan Azure Event Hubs.

Contoh PowerShell lengkap sedang tertunda.

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

Ada dua opsi untuk menghasilkan pesan Azure Event Hubs dari fungsi:

  • Nilai hasil : Mengatur properti name di function.json ke $return. Dengan konfigurasi ini, nilai pengembalian fungsi dipertahankan sebagai pesan Azure Event Hubs.

  • Imperatif: Meneruskan nilai ke metode set parameter yang dinyatakan sebagai jenis Keluar. Nilai yang diteruskan ke set dipertahankan sebagai pesan Azure Event Hubs.

Koneksi

Properti connection adalah referensi ke konfigurasi lingkungan yang menentukan bagaimana aplikasi harus terhubung ke Pusat Aktivitas. 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

Dapatkan string koneksi ini dengan mengeklik tombol Informasi Koneksi untuk namespace, bukan pusat aktivitas itu sendiri. String koneksi harus untuk namespace Pusat Aktivitas, bukan pusat aktivitas itu sendiri.

Saat digunakan untuk pemicu, string koneksi harus memiliki setidaknya izin “baca” untuk mengaktifkan fungsi. Saat digunakan untuk binding output, string koneksi harus memiliki izin "kirim" untuk mengirim pesan ke aliran peristiwa.

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

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 Pusat Aktivitas sepenuhnya memenuhi syarat. myeventhubns.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 pusat aktivitas Anda saat runtime. Cakupan penetapan peran dapat untuk namespace Layanan Pusat Aktivitas, atau pusat aktivitas itu sendiri. Peran manajemen seperti Pemilik tidak cukup. Tabel berikut menunjukkan peran bawaan yang direkomendasikan saat menggunakan ekstensi Azure Event Hubs dalam operasi normal. Aplikasi Anda mungkin memerlukan izin tambahan berdasarkan kode yang Anda tulis.

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

Kode pengecualian dan pengembalian

Pengikatan Referensi
Event Hubs Panduan Operasi

Langkah berikutnya