共用方式為

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 函式，支援 event_hub_output下列屬性：

屬性 說明
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 是其中一個單一事件類型 包含多個事件的陣列。 每個專案都代表一個事件。

針對其他輸出案例，請直接從 Azure.Messaging.EventHubs 建立及使用 EventHubProducerClient 與其他類型。 如需使用相依性插入從 Azure SDK 建立用戶端類型的範例，請參閱 註冊 Azure 用戶端 。

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

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

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

完整的 PowerShell 範例擱置中。

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

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

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

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

連線

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

如果設定的值與單一設定完全相符，又與其他設定的開頭相符，則會使用完全相符項目。

Connection string

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

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

此 連接字串 應該儲存在應用程式設定中，其名稱符合系結組態的 屬性所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 事件中樞資料傳送者

例外狀況和傳回碼

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

下一步