Azure Functions 的 Azure 事件中樞 輸出系結

  • 發行項

本文說明如何使用 Azure Functions 的 Azure 事件中樞 系結。 Azure Functions 支援事件中樞的觸發程式和輸出系結。

如需安裝和組態詳細數據的詳細資訊，請參閱概 觀。

使用事件中樞輸出系結將事件寫入事件數據流。 您必須具備事件中樞的傳送權限，才能將事件寫入其中。

在您嘗試實作輸出系結之前，請確定必要的套件參考已就緒。

重要

本文使用索引標籤來支援多個版本的Node.js程序設計模型。 v4 模型已正式推出，旨在為 JavaScript 和 TypeScript 開發人員提供更靈活的直覺式體驗。 如需 v4 模型運作方式的詳細資訊，請參閱 Azure Functions Node.js開發人員指南。 若要深入瞭解 v3 與 v4 之間的差異，請參閱 移轉指南。

Azure Functions 支援兩種適用於 Python 的程式設計模型。 您定義系結的方式取決於您所選擇的程式設計模型。

Python v2 程式設計模型可讓您直接在 Python 函式程式代碼中使用裝飾項目來定義系結。 如需詳細資訊，請參閱 Python 開發人員指南。

本文支援這兩種程序設計模型。

範例

下列範例示範 使用 方法傳回值做為輸出，將訊息字串寫入事件中樞的 C# 函 式：

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

下列範例顯示定時器觸發的 TypeScript 函式 ，可將單一訊息傳送至事件中樞：

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

若要輸出多個訊息，請傳回數位，而不是單一物件。 例如：

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

下列範例顯示定時器觸發的 JavaScript 函式 ，可將單一訊息傳送至事件中樞：

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

若要輸出多個訊息，請傳回數位，而不是單一物件。 例如：

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

完整的 PowerShell 範例擱置中。

下列範例顯示事件中樞觸發程式系結，以及使用系結的 Python 函式。 此函式會將訊息寫入事件中樞。 此範例取決於您使用的是 v1 或 v2 Python 程式設計模型。

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'

以下是傳送多個訊息的 Python 程式代碼：

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

下列範例顯示 Java 函式，此函式會將包含目前時間的訊息寫入事件中樞。

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

在 Java 函式運行時間連結庫中，對 @EventHubOutput 值發佈至事件中樞的參數使用註釋。 參數的類型應該是 OutputBinding<T> ，其中 T 是POJO或任何原生Java類型。

屬性

進程內和隔離的背景工作進程 C# 連結庫都會使用 屬性來設定系結。 C# 文稿會改用function.json組態檔，如 C# 腳本指南中所述。

使用 [EventHubOutputAttribute] 定義事件中樞的輸出系結，其支援下列屬性。

參數 描述
EventHubName 事件中樞的名稱。 當事件中樞名稱也呈現於連接字串時，該值會在執行階段覆寫這個屬性。
[連接] 應用程式設定或設定集合的名稱，指定如何連線到事件中樞。 若要深入了解，請參閱連線。

裝飾項目

僅適用於 Python v2 程式設計模型。

針對使用裝飾項目定義的 Python v2 函式，在上 cosmos_db_trigger具有下列屬性：

屬性 說明
arg_name 函式程式碼中所使用的變數名稱，代表事件。
event_hub_name 事件中樞的名稱。 當事件中樞名稱也呈現於連接字串時，該值會在執行階段覆寫這個屬性。
connection 應用程式設定或設定集合的名稱，指定如何連線到事件中樞。 若要深入了解，請參閱連線。

如需使用 function.json 定義的 Python 函式，請參閱組 態 一節。

註釋

在 Java 函式運行時間連結庫中，對值發佈至事件中樞的參數使用 EventHubOutput 註釋。 註解支援下列設定：

組態

僅適用於 Python v1 程式設計模型。

下表說明您可以在傳遞至 output.eventHub() 方法的物件options上設定的屬性。

屬性 說明
eventHubName 事件中樞的名稱。 當事件中樞名稱也呈現於連接字串時，該值會在執行階段覆寫這個屬性。
connection 應用程式設定或設定集合的名稱，指定如何連線到事件中樞。 若要深入了解，請參閱連線。

下表說明您在 function.json 檔案中設定的系結組態屬性，其與運行時間版本不同。

function.json 屬性 描述
type 必須設定為 eventHub。
direction 必須設定為 out。 當您在 Azure 入口網站中建立繫結時，會自動設定此參數。
name 函式程式碼中所使用的變數名稱，代表事件。
eventHubName Functions 2.x 和更新版本。 事件中樞的名稱。 當事件中樞名稱也呈現於連接字串時，該值會在執行階段覆寫這個屬性。
connection 應用程式設定或設定集合的名稱，指定如何連線到事件中樞。 若要深入了解，請參閱連線。

當您在本機開發時，請在集合中的 local.settings.json 檔案Values中新增應用程式設定。

使用方式

事件中樞輸出系結所支援的參數類型取決於 Functions 運行時間版本、擴充套件版本，以及所使用的 C# 形式。

當您想要函式撰寫單一事件時，事件中樞輸出系結可以系結至下列類型：

類型 描述
string 事件做為字串。 當事件是簡單的文字時，請使用 。
byte[] 事件的位元組。
JSON 可序列化型別 物件，表示 事件。 函式會嘗試將一般舊的CLR物件 （POCO） 類型串行化為 JSON 數據。

當您要函式寫入多個事件時，事件中樞輸出系結可以系結至下列類型：

類型 描述
T[] 其中 T 是其中一個單一事件類型 包含多個事件的陣列。 每個專案都代表一個事件。

針對其他輸出案例，請直接從 Microsoft.Azure.EventHubs 建立和使用類型。

使用 EventHubOutput 註釋，從函式輸出事件中樞訊息有兩個選項：

  • 傳回值：藉由將註釋套用至函式本身，函式的傳回值會保存為事件中樞訊息。

  • 命令式：若要明確設定訊息值，請將批注套用至類型的 OutputBinding<T>特定參數，其中 T 是 POJO 或任何原生 Java 類型。 使用此組態，將值傳遞至 setValue 方法會將值保存為事件中樞訊息。

完整的 PowerShell 範例擱置中。

直接或使用 context.extraOutputs.set()傳回 值，以存取輸出訊息。

從函式輸出事件中樞訊息有兩個選項：

  • 傳回值：將 name 中的屬性設定為 $returnfunction.json。 使用此組態時，函式的傳回值會保存為事件中樞訊息。

  • 命令式：將值傳遞至宣告為 Out 類型的參數的 set 方法。 傳遞至 set 的值會保存為事件中樞訊息。

連線

屬性 connection 是環境組態的參考，指定應用程式應該如何連線到事件中樞。 它可以指定：

如果設定的值既與單一設定完全相符，又是其他設定的前置詞比對，則會使用完全相符專案。

連接字串

按兩下命名空間的 [連線 ion Information] 按鈕，而非事件中樞本身，以取得此 連接字串。 連接字串 必須是事件中樞命名空間，而不是事件中樞本身。

用於觸發程式時，連接字串 至少必須具有「讀取」許可權，才能啟動函式。 當用於輸出系結時，連接字串 必須具有「傳送」許可權，才能將訊息傳送至事件數據流。

此 連接字串 應該儲存在應用程式設定中，其名稱符合系結組態的 屬性所connection指定的值。

身分識別型連線

如果您使用 5.x 版或更高版本的延伸模組，而不是使用具有秘密的 連接字串，您可以讓應用程式使用 Microsoft Entra 身分識別。 若要這樣做，您會在通用前置詞下定義設定，以對應至 connection 觸發程式和系結組態中的 屬性。

在此模式中，延伸模組需要下列屬性：

屬性 環境變數範本 描述 範例值
完整命名空間 <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace 完整事件中樞命名空間。 myeventhubns.servicebus.windows.net

其他屬性可以設定為自定義連線。 請參閱 身分識別型連線的一般屬性。

注意

使用 Azure 應用程式組態或 Key Vault 來提供「受控識別」連線的設定時，設定名稱應使用有效的索引鍵分隔符號，例如：: 或 / 取代 __，以確保正確解析名稱。

例如： <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace 。

主控於 Azure Functions 服務時，以身分識別為基礎的連接會使用受控識別。 雖然可以使用 credential 和 clientID 屬性指定使用者指派的身分識別，但預設會使用系統指派的身分識別。 請注意，不支援使用資源標識符設定使用者指派的身分識別。 在其他內容中執行時，例如本機開發，會改用您的開發人員身分識別，但您可以自定義此身分識別。 請參閱 使用身分識別型連線進行本機開發。

授與權限給身分識別

正在使用的任何身分識別，都必須具有執行預期動作的權限。 對於大部分的 Azure 服務，這表示您必須 使用內建或自定義角色，在 Azure RBAC 中指派角色，以提供這些許可權。

重要

部分權限可能會由所有內容都不需要的目標服務公開。 可以的話，請遵循最低權限原則，只授與身分識別所需的權限。 例如，如果應用程式只需要能夠從數據源讀取，請使用只有讀取許可權的角色。 指派也允許寫入該服務的角色是不適當的，因為這會是讀取作業的過度許可權。 同樣地，您會想要確保角色指派的範圍僅限於需要讀取的資源。

您必須建立角色指派，以在運行時間提供事件中樞的存取權。 角色指派的範圍可以是事件中樞命名空間或事件中樞本身。 擁有者之類的管理角色不足。 下表顯示正常作業中使用事件中樞擴充功能時建議的內建角色。 您的應用程式可能需要根據您撰寫的程式代碼來取得其他許可權。

繫結類型 範例內建角色
觸發程序 Azure 事件中樞 數據接收器，Azure 事件中樞 數據擁有者
輸出繫結 Azure 事件中樞資料傳送者

例外狀況和傳回碼

繫結 參考
事件中樞 操作指南

下一步