Connector Trigger for Azure Functions

Azure Functions 提供與各種服務整合的觸發與繫結擴充功能,主要針對 Azure 服務。 連接器擴充功能將這些整合擴展至更廣泛的服務範圍,包括商業系統與資料平台。

例如,使用 Connector Trigger 在 Office 365 Outlook 收到新郵件、SharePoint 中建立檔案,或 Salesforce 中記錄變更時執行函式。 觸發器會從 Azure 連接器命名空間中的受管理連接器接收事件。 欲探索可用的管理連接器,請參閱 連接器參考資料。

有關受管理連接器、何時使用及功能可用性的更多資訊,請參閱「在 Azure Functions 中使用受管理連接器」。

Note

連接器觸發器目前不支援此語言。

交貨模式

受管理連接器支援兩種傳遞模式:

  • 輪詢: Functions 主機會將外部連線至連接器命名空間以接收事件。 在註冊選項中設定 deliveryMode: 'Poll'、 和 供應connectiontriggerConfigName。
  • Webhook: 連接器命名空間會將事件傳送到擴充功能的回呼端點。 當你省略 deliveryMode時,Webhook 是預設的。

兩種模式都支援命名的輔助程式,例如 a connectors.office365.onNewEmail 和通用 connectorTrigger 輔助程式。 如需選擇模式的協助,請參閱 「選擇傳送模式」。

開始

請依照您的投遞模式設定路徑操作:

  1. 安裝 Node.js 套件並設定擴充套件套件。
  2. 建立或重複使用命名空間與連線,並建立輪詢觸發器設定。
  3. 取得輪詢端點。
  4. 設定呼叫者認證、連線存取權,以及本地或已部署的設定。
  5. 請使用下方的輪詢範例,並將其與triggerConfigName數值與您的設定相匹配connection。

輪詢不需要公開回調端點或系統金鑰。 對於 webhook 傳送,目的地函數與回調端點必須在建立觸發器設定前準備好。

交貨模式

受管理連接器支援兩種傳遞模式:

  • 輪詢: Functions 主機會將外部連線至連接器命名空間以接收事件。 設定 ,並 delivery_mode=func.DeliveryMode.POLL供應connection,trigger_config_name且 。@app.connector_trigger
  • Webhook: 連接器命名空間會將事件傳送到擴充功能的回呼端點。 當你省略 delivery_mode 時 @app.connector_trigger,Webhook 是預設的。

如需選擇模式的協助,請參閱 「選擇傳送模式」。

開始

請依照您的投遞模式設定路徑操作:

  1. 安裝 Python 套件並設定擴充套件。
  2. 建立或重複使用命名空間與連線,並建立輪詢觸發器設定。
  3. 取得輪詢端點。
  4. 設定呼叫者認證、連線存取權,以及本地或已部署的設定。
  5. 請使用下方的輪詢範例,並將其與trigger_config_name數值與您的設定相匹配connection。

輪詢不需要公開回調端點或系統金鑰。 對於 webhook 傳送,目的地函數與回調端點必須在建立觸發器設定前準備好。

交貨模式

受管理連接器支援兩種傳遞模式:

  • 輪詢: Functions 主機會將外部連線至連接器命名空間以接收事件。 設定 DeliveryMode = ConnectorTriggerDeliveryMode.Poll,並在 上新增連線設定與觸發器設定 [ConnectorTrigger]。
  • Webhook: 連接器命名空間會將事件傳送到擴充功能的回呼端點。 當你省DeliveryMode[ConnectorTrigger]略屬性時,Webhook 是預設值。

如需選擇模式的協助,請參閱 「選擇傳送模式」。

開始

請依照您的投遞模式設定路徑操作:

  1. 安裝擴充功能。
  2. 建立或重複使用命名空間與連線,並建立輪詢觸發器設定。
  3. 取得輪詢端點。
  4. 設定呼叫者認證、連線存取權,以及本地或已部署的設定。
  5. 請使用下方範例,將其與ConnectionTriggerConfigName數值與您的設定相匹配。

輪詢不需要公開回調端點或系統金鑰。 對於 webhook 傳送,目的地函數與回調端點必須在建立觸發器設定前準備好。

Examples

Office 365 Outlook 與 SharePoint Online 範例使用來自 Azure Connectors SDK 的強型別有效載荷。 對於尚未有強型別有效載荷的連接器操作,請綁定 以 string 接收原始 JSON 有效載荷。 這些範例刻意只記錄基本的有效載荷資訊,以專注於如何定義連接器觸發函式。 用你應用程式的處理邏輯取代日誌。

若要找出哪些連接器操作支援 .NET 強型別的有效載荷,請參閱「操作到 Azure Functions 簽名映射」。

輪詢傳遞模式也支援屬性上的[ConnectorTrigger]可選屬性。 有關描述、支援值與預設值,請參閱輪詢屬性。

Office 365 Outlook

以下範例在新郵件抵達已設定的Office 365 Outlook信箱時執行:

此範例接收最多四個連接器事件的批次,每個事件包含一封電子郵件,並使用 以 ConnectorEvent<T> 存取每個事件的有效載荷與 MessageId。

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;
using Azure.Connectors.Sdk.Office365.Models;

namespace Office365App;

public sealed class O365Functions(ILogger<O365Functions> logger)
{
    [Function("OnNewEmail")]
    public void OnNewEmail(
        [ConnectorTrigger(
            DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
            Connection = "ConnectorNamespace",
            TriggerConfigName = "%OnNewEmailTriggerConfigName%",
            IsBatched = true,
            MaxBatchSize = 4,
            TargetPendingEventThreshold = 16)]
        ConnectorEvent<Office365OnNewEmailTriggerPayload>[] emails)
    {
        foreach (var email in emails)
        {
            var messageCount = email.Data.Body?.Value?.Count ?? 0;
            logger.LogInformation(
                "Poll event {MessageId}: received {MessageCount} new email message(s).",
                email.MessageId,
                messageCount);
        }
    }
}

針對本地開發,請在 Valueslocal.settings.json的章節中包含連線設定與觸發器設定名稱:

{
  "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
  "OnNewEmailTriggerConfigName": "<polling-trigger-config-name>"
}

屬性屬性指向以下設定:

  • Connection = "ConnectorNamespace" 識別設定前綴。 該擴充功能會讀取輪詢端點。ConnectorNamespace__pollingEndpoint 有關如何取得端點以及所需憑證與存取原則的資訊,請參閱 輪詢端點。
  • TriggerConfigName = "%OnNewEmailTriggerConfigName%" 解析設定值 OnNewEmailTriggerConfigName 。 將其值設定為您的連接器命名空間中輪詢觸發器配置的名稱。

前綴與設定名稱僅供說明;若更改,請更新屬性屬性與設定以符合。 對於已部署的功能應用程式,請將相同的設定新增至功能應用程式的應用程式設定,而非 local.settings.json。

該 Office365OnNewEmailTriggerPayload 型別定義於 Azure.Connectors.Sdk.Office365.Models 命名空間中。

完整程式碼範例,包括基礎設施與觸發器註冊,請參見.NET Office 365 Outlook觸發器。

SharePoint 在線

以下範例在已設定的 SharePoint Online 文件庫中建立檔案時執行:

此範例接收一個連接器事件,每個呼叫包含一個檔案(預設值),並用來 ConnectorEvent<T> 存取其有效載荷及 MessageId。

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;
using Azure.Connectors.Sdk.SharePointOnline.Models;

namespace SharePointApp;

public sealed class SharePointFunctions(ILogger<SharePointFunctions> logger)
{
    [Function("OnNewFile")]
    public void OnNewFile(
        [ConnectorTrigger(
            DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
            Connection = "ConnectorNamespace",
            TriggerConfigName = "%OnNewFileTriggerConfigName%")]
        ConnectorEvent<SharePointOnlineOnNewFileItemsTriggerPayload> file)
    {
        var fileCount = file.Data.Body?.Value?.Count ?? 0;
        logger.LogInformation(
            "Poll event {MessageId}: received {FileCount} new SharePoint file(s).",
            file.MessageId,
            fileCount);
    }
}

針對本地開發,請在 local.settings.json物件中包含以下數值Values:

{
  "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
  "OnNewFileTriggerConfigName": "<polling-trigger-config-name>"
}

屬性屬性指向以下設定:

  • Connection = "ConnectorNamespace" 識別設定前綴。 該擴充功能會讀取輪詢端點。ConnectorNamespace__pollingEndpoint 有關如何取得端點以及所需憑證與存取原則的資訊,請參閱 輪詢端點。
  • TriggerConfigName = "%OnNewFileTriggerConfigName%" 解析設定值 OnNewFileTriggerConfigName 。 將其值設定為您的連接器命名空間中 SharePoint 輪詢觸發器設定的名稱。

前綴與設定名稱僅供說明;若更改,請更新屬性屬性與設定以符合。 對於已部署的功能應用程式,請將相同的設定新增至功能應用程式的應用程式設定,而非 local.settings.json。

該 SharePointOnlineOnNewFileItemsTriggerPayload 型別定義於 Azure.Connectors.Sdk.SharePointOnline.Models 命名空間中。

完整程式碼範例,包括基礎設施與觸發器註冊,請參閱 SharePoint Online 對 .NET 的觸發器。

無強型別有效載荷的連接器

有些連接器事件尚未有強型別的 .NET 有效載荷。 當新增訊息至 Microsoft Teams 聊天或頻道時,以下範例會執行。 輪詢用於 ConnectorEvent<string> 接收帶有傳遞元資料的原始 JSON 有效載荷;webhook 傳遞則直接綁定至 string:

此範例會接收每個呼叫(預設)的連接器事件,並用來 ConnectorEvent<string> 存取其 JSON 負載及 MessageId。

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;

namespace TeamsApp;

public sealed class TeamsFunctions(ILogger<TeamsFunctions> logger)
{
    [Function("OnNewTeamsMessage")]
    public void OnNewTeamsMessage(
        [ConnectorTrigger(
            DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
            Connection = "ConnectorNamespace",
            TriggerConfigName = "%OnNewTeamsMessageTriggerConfigName%")]
        ConnectorEvent<string> message)
    {
        logger.LogInformation(
            "Poll event {MessageId}: received a Teams payload of {PayloadLength} characters.",
            message.MessageId,
            message.Data.Length);
    }
}

針對本地開發,請在 local.settings.json物件中包含以下數值Values:

{
  "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
  "OnNewTeamsMessageTriggerConfigName": "<polling-trigger-config-name>"
}

屬性屬性指向以下設定:

  • Connection = "ConnectorNamespace" 識別設定前綴。 該擴充功能會讀取輪詢端點。ConnectorNamespace__pollingEndpoint 有關如何取得端點以及所需憑證與存取原則的資訊,請參閱 輪詢端點。
  • TriggerConfigName = "%OnNewTeamsMessageTriggerConfigName%" 解析設定值 OnNewTeamsMessageTriggerConfigName 。 將其值設定為您的連接器命名空間中 Teams 輪詢觸發器設定的名稱。

前綴與設定名稱僅供說明;若更改,請更新屬性屬性與設定以符合。 對於已部署的功能應用程式,請將相同的設定新增至功能應用程式的應用程式設定,而非 local.settings.json。

完整程式碼範例,包括基礎架構與觸發器註冊,請參閱 .NET 的通用連接器觸發器。

連接器事件對應

操作名稱由管理連接器定義。 你在程式碼中選擇函式名稱。 輪詢與 webhook 範例使用相同的事件、操作與函式名稱:

連接器事件 作業名稱 函式名稱
新Office 365 Outlook電子郵件 OnNewEmailV3 OnNewEmail
新的 SharePoint Online 檔案 GetOnNewFileItems OnNewFile
新的 Microsoft Teams 聊天或頻道訊息 WebhookNewMessageTrigger OnNewTeamsMessage

Webhook 有效載荷可以包含多個項目,視觸發器設定而定。

輪詢傳遞總是啟用 splitOn,因此每個排隊事件包含一個分割項目。 然而,輪詢模式可以透過設定 IsBatched = true來將事件分組為一個函式呼叫。 有關批次設定,請參閱 屬性。

繫結型別

對於 .NET 隔離工作者函數,兩種傳遞模式都支援以下參數類型:

類型 Description
string 接收事件主體為原始 JSON。 當沒有強型別的 SDK 模型可用,或你想自己反序列化 payload 時,才會使用這種類型。
連接器 SDK 模型 將 JSON 事件主體反序列化為從 Azure.Connectors.Sdk的操作專用模型,例如 Office365OnNewEmailTriggerPayload 或 SharePointOnlineOnNewFileItemsTriggerPayload。
JSON-deserializable POCO 利用已設定的工人序列化器,將 JSON 事件主體反序列化為與連接器有效載荷相符形狀的 .NET 類型。
ConnectorEvent<T> 將支援的有效載荷類型包裝在 Data中。 MessageId 包含輪詢的傳遞識別碼,且用於 null Webhook 傳遞。

陣列參數

陣列參數在每種傳遞模式下都有不同的意義。

對於 輪詢, IsBatched 決定函數參數形狀,其中 T 是支援的事件有效載荷類型:

IsBatched 函數參數類型
false (預設) T 或 ConnectorEvent<T>
true T[] 或 ConnectorEvent<T>[],即使當 MaxBatchSize = 1

設定 MaxBatchSize 為 1 到 32 之間的值;若不進行批次,有效批次大小必須為 1。 批次大小計算的是連接器事件,而非事件有效載荷中的項目。 批次處理不會改變每個事件中的有效載荷類型。 SDK payload 的 Body.Value 集合與批次調用所提供的外部事件陣列是分開的。

對於 webhook,請用 T[] 來將單一回呼的 JSON 陣列主體反序列化為一個有效載荷項目陣列。 這不是一堆單獨送達的事件。 Webhook 傳遞每次呼叫處理一次回調; IsBatched 僅適用於輪詢。

Examples

Node.js 連接器擴充功能為本節所示的 Office 365 Outlook、SharePoint Online 及 Microsoft Teams 操作提供類型上下文。 這些範例刻意只記錄基本的有效載荷資訊,以專注於如何定義連接器觸發函式。 用你應用程式的處理邏輯取代日誌。

若要查詢哪些連接器操作支援 JavaScript 和 TypeScript 的強型別負載,請參閱 Node.js 連接器擴充套件參考。

Office 365 Outlook

以下範例在新郵件抵達已設定的Office 365 Outlook信箱時執行:

此範例每次呼叫最多可接收四個連接器事件。 助手會將這些事件的電子郵件作為一個清單提供。

import { InvocationContext } from '@azure/functions';
import {
    connectors,
    EmailTriggerContext,
} from '@azure/functions-extensions-connectors';

connectors.office365.onNewEmail('OnNewEmail', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewEmailTriggerConfigName%',
    cardinality: 'many',
    maxBatchSize: 4,
    targetPendingEventThreshold: 16,
    handler: async (
        context: EmailTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.emails.length} new email message(s).`,
        );
    },
});

該 EmailTriggerContext 型別會將訊息暴露為型別陣 emails 列。

如需更多範例,請參閱 TypeScript 的Office 365 Outlook觸發器。

SharePoint 在線

以下範例在已設定的 SharePoint Online 文件庫中建立檔案時執行:

此範例每次呼叫接收一個連接器事件,為預設值。 該輔助程式會以清單形式提供其檔案屬性記錄。

import { InvocationContext } from '@azure/functions';
import {
    connectors,
    SharepointItemTriggerContext,
} from '@azure/functions-extensions-connectors';

connectors.sharepoint.onNewFileItems('OnSharepointNewFile', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnSharepointNewFileTriggerConfigName%',
    handler: async (
        context: SharepointItemTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.records.length} new SharePoint file(s).`,
        );
    },
});

此 SharepointItemTriggerContext 類型會透過 records 檔案屬性記錄進行操作 GetOnNewFileItems 。 輔助程式保留連接器提供的欄位,但不會將其轉換為固定檔案結構。 如需更多範例,請參閱 TypeScript 的 SharePoint Online 觸發器。

Microsoft 團隊

以下範例在新增訊息至 Microsoft Teams 頻道時執行:

此範例每次呼叫接收一個連接器事件,為預設值。 輔助程式以清單形式提供其訊息有效載荷。

import { InvocationContext } from '@azure/functions';
import {
    ChannelMessageTriggerContext,
    connectors,
} from '@azure/functions-extensions-connectors';

connectors.teams.onNewChannelMessage('OnNewChannelMessage', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewTeamsMessageTriggerConfigName%',
    handler: async (
        context: ChannelMessageTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.messages.length} new Teams message(s).`,
        );
    },
});

該 ChannelMessageTriggerContext 型別會將訊息暴露為型別陣 messages 列。

如需更多範例,請參閱 TypeScript 的 Microsoft Teams 觸發器。

通用連接器有效載荷

當作業沒有命名註冊時,請使用通用輔助工具。 當你的程式碼需要處理原始有效載荷時,可以存取 context.rawPayload 。

此範例每次呼叫接收一個連接器事件,為預設值。 輔助程式會以清單的形式提供其有效載荷項目。

import { InvocationContext } from '@azure/functions';
import {
    connectorTrigger,
    ConnectorTriggerContext,
} from '@azure/functions-extensions-connectors';

connectorTrigger('OnConnectorEvent', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%GenericTriggerConfigName%',
    handler: async (
        context: ConnectorTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(`Received ${context.items.length} payload item(s).`);
    },
});

一般上下文預設其項目類型為 unknown。 在存取操作專屬屬性之前,先驗證項目。 context.rawPayload 在正規化前保留解析後的輸入,包括用於批次輪詢的外部事件陣列。

Examples

Node.js 連接器擴充功能提供本節所示Office 365 Outlook、SharePoint線上及Microsoft Teams操作的連接器專屬上下文。 這些範例刻意只記錄基本的有效載荷資訊,以專注於如何定義連接器觸發函式。 用你應用程式的處理邏輯取代日誌。

若要查詢哪些連接器操作支援 JavaScript 和 TypeScript 的強型別負載,請參閱 Node.js 連接器擴充套件參考。

Office 365 Outlook

以下範例在新郵件抵達已設定的Office 365 Outlook信箱時執行:

此範例每次呼叫最多可接收四個連接器事件。 助手會將這些事件的電子郵件作為一個清單提供。

const {
    connectors,
} = require('@azure/functions-extensions-connectors');

connectors.office365.onNewEmail('OnNewEmail', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewEmailTriggerConfigName%',
    cardinality: 'many',
    maxBatchSize: 4,
    targetPendingEventThreshold: 16,
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.emails.length} new email message(s).`,
        );
    },
});

處理器上下文透過陣列暴露訊息 emails 。

SharePoint 在線

以下範例在已設定的 SharePoint Online 文件庫中建立檔案時執行:

此範例每次呼叫接收一個連接器事件,為預設值。 該輔助程式會以清單形式提供其檔案屬性記錄。

const {
    connectors,
} = require('@azure/functions-extensions-connectors');

connectors.sharepoint.onNewFileItems('OnSharepointNewFile', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnSharepointNewFileTriggerConfigName%',
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.records.length} new SharePoint file(s).`,
        );
    },
});

處理程序上下文會透過recordsGetOnNewFileItems此操作公開檔案屬性記錄。 輔助程式保留連接器提供的欄位,但不會將其轉換為固定檔案結構。

Microsoft 團隊

以下範例在新增訊息至 Microsoft Teams 頻道時執行:

此範例每次呼叫接收一個連接器事件,為預設值。 輔助程式以清單形式提供其訊息有效載荷。

const {
    connectors,
} = require('@azure/functions-extensions-connectors');

connectors.teams.onNewChannelMessage('OnNewChannelMessage', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewTeamsMessageTriggerConfigName%',
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.messages.length} new Teams message(s).`,
        );
    },
});

處理器上下文透過陣列暴露訊息 messages 。

通用連接器有效載荷

當作業沒有命名註冊時,請使用通用輔助工具。 當你的程式碼需要處理原始有效載荷時,可以存取 context.rawPayload 。

此範例每次呼叫接收一個連接器事件,為預設值。 輔助程式會以清單的形式提供其有效載荷項目。

const {
    connectorTrigger,
} = require('@azure/functions-extensions-connectors');

connectorTrigger('OnConnectorEvent', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%GenericTriggerConfigName%',
    handler: async (context, invocationContext) => {
        invocationContext.log(`Received ${context.items.length} payload item(s).`);
    },
});

在存取操作專屬屬性之前,先驗證項目。 context.rawPayload 在正規化前保留解析後的輸入,包括用於批次輪詢的外部事件陣列。

本地輪詢設定

將輪詢端點與觸發器設定名稱新增至 local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
    "OnNewEmailTriggerConfigName": "<outlook-polling-trigger-config-name>",
    "OnSharepointNewFileTriggerConfigName": "<sharepoint-polling-trigger-config-name>",
    "OnNewTeamsMessageTriggerConfigName": "<teams-polling-trigger-config-name>",
    "GenericTriggerConfigName": "<generic-polling-trigger-config-name>"
  }
}

範例的 connection: 'ConnectorNamespace' 值用來識別設定前綴。 每個 triggerConfigName 表達式都會解析到其對應的應用程式設定。 有關已部署的設定與連線權限,請參閱 輪詢驗證。

關於另一個投票登記的範例,請參見 Node.js 投票樣本。

Examples

Office 365 Outlook 與 SharePoint Online 範例使用了 。azurefunctions-extensions-connectors 通用範例接收的是未附 SDK 註解的原始 JSON。 這些範例只記錄基本的有效載荷資訊;以應用程式的處理邏輯取代記錄。

要找出哪些連接器操作支援 Python 強型別負載,請參閱 Python 連接器擴充套件中的「關鍵概念」。

Office 365 Outlook

以下範例在新郵件抵達已設定的Office 365 Outlook信箱時執行:

此範例每次呼叫最多可接收四個連接器事件。 轉換器會將這些事件的電子郵件作為一個清單提供。

import logging

import azure.functions as func
import azurefunctions.extensions.connectors.office365 as office365

app = func.FunctionApp()


@app.function_name(name="OnNewEmail")
@app.connector_trigger(
    arg_name="emails",
    delivery_mode=func.DeliveryMode.POLL,
    connection="ConnectorNamespace",
    trigger_config_name="%OnNewEmailTriggerConfigName%",
    cardinality=func.Cardinality.MANY,
    max_batch_size=4,
    target_pending_event_threshold=16,
)
def on_new_email(
    emails: list[office365.GraphClientReceiveMessage],
) -> None:
    logging.info(
        "Received %s new email message(s).",
        len(emails),
    )

綁定支撐GraphClientReceiveMessage操作。OnNewEmailV3 關於兩種模式的完整程式碼、基礎架構及觸發器註冊,請參閱Python Office 365 Outlook觸發器。

SharePoint 在線

以下範例在已設定的 SharePoint Online 文件庫中建立檔案時執行:

此範例每次呼叫接收一個連接器事件,為預設值。 轉換器會以清單形式提供其檔案屬性紀錄。

import logging

import azure.functions as func
import azurefunctions.extensions.connectors.sharepointonline as sharepoint

app = func.FunctionApp()


@app.function_name(name="OnSharepointNewFile")
@app.connector_trigger(
    arg_name="files",
    delivery_mode=func.DeliveryMode.POLL,
    connection="ConnectorNamespace",
    trigger_config_name="%OnSharepointNewFileTriggerConfigName%",
)
def on_sharepoint_new_file(files: list[sharepoint.Item]) -> None:
    logging.info(
        "Received %s new SharePoint file(s).",
        len(files),
    )

繫結支援Item此GetOnNewFileItems操作,並保留檔案屬性。dynamic_properties 關於兩種模式的完整程式碼、基礎架構及觸發器註冊,請參閱 SharePoint Online 觸發器(Python)。

通用連接器有效載荷

當操作沒有支援的型別轉換器,或你想自行解析 JSON 時,請使用此 azure-functions 函式庫以原始 JSON 字串接收事件。

此範例會接收每個呼叫的一個連接器事件,預設為原始 JSON 字串。

import logging

import azure.functions as func

app = func.FunctionApp()


@app.function_name(name="OnConnectorEvent")
@app.connector_trigger(
    arg_name="payload",
    delivery_mode=func.DeliveryMode.POLL,
    connection="ConnectorNamespace",
    trigger_config_name="%GenericTriggerConfigName%",
)
def on_connector_event(payload: str) -> None:
    logging.info("Received a connector event.")

完整範例請參閱 Python 通用連接器觸發器。

對於本地輪詢,請在下列local.settings.json定義端點與觸發器組態名稱Values:

{
  "IsEncrypted": false,
  "Values": {
    "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
    "OnNewEmailTriggerConfigName": "<outlook-polling-trigger-config-name>",
    "OnSharepointNewFileTriggerConfigName": "<sharepoint-polling-trigger-config-name>",
    "GenericTriggerConfigName": "<generic-polling-trigger-config-name>"
  }
}

範例的 connection="ConnectorNamespace" 值用來識別設定前綴。 每個 trigger_config_name 表達式都會解析到其對應的應用程式設定。 有關已部署的設定與連線權限,請參閱 輪詢驗證。

繫結型別

兩種傳送模式都支援以下註冊與有效載荷形狀:

Registration 處理器輸入
app.connectorTrigger 來自 @azure/functions 接收原始觸發器輸入,且不使用輔助正規化。 TypeScript 輸入類型預設為 unknown;對於批次輪詢,請使用陣列類型,例如 unknown[]。
connectorTrigger 來自 @azure/functions-extensions-connectors 接收帶有正規化 和 、 解析 rawPayload、 及toJSON()序列化的 aConnectorTriggerContext<T>。itemspayload TypeScript 項目類型預設為 unknown。
命名輔助者,例如 connectors.office365.onNewEmail 接收帶有命名陣列的正規化上下文,例如 emails、 、 records或 messages,且該陣列為 items。 TypeScript 會推斷支援的 SDK 項目類型。

輔助程式接受物件輸入或 JSON 字串。 它們會正常化 { body: item } 並 { body: { value: [...] } } 包絡。 在批次輪詢中,他們會將外圍的信封陣列及其有效載荷項目合併成一個 items 陣列,以維持順序。 rawPayload 保留正規化前的解析輸入,包括外部事件陣列。

設定 cardinality: 'many' 啟用呼叫批次處理。 僅使用情境中的陣列或 TypeScript 陣列類型無法啟用批次處理。 maxBatchSize 計數連接器事件,而非正規化陣列中的項目。 每個 webhook 呼叫只處理一個回調,該回調可以包含多個有效載荷項目。

TypeScript 類型描述預期的有效載荷,但不會在執行時驗證或轉換操作特定的欄位。 當 payload 的形狀未知時,請先驗證其屬性。 有關支援的型別註冊與 SDK 負載類型,請參閱 Node.js 連接器擴充參考。

繫結型別

連接器觸發器支援以下 Python 參數類型:

類型 Description
str 接收事件主體為 JSON 字串。
dict 可以當作註解,但原始轉換器不會把 JSON 字串解析成字典。 若要解析原始 JSON,請綁定至 str 並使用 json.loads。
bytes 以原始位元組形式接收事件主體。
typing.List[str] 或 typing.List[bytes] 當輪詢使用 cardinality=func.Cardinality.MANY時,會以清單形式接收分別傳送的連接器事件。 匯入 List 這些 typing 註解。
支援的連接器 SDK 註解 使用註冊的 azurefunctions-extensions-connectors 轉換器將有效載荷反序列化為特定操作的 SDK 模型清單。

對於 SDK 綁定,請註解該參數,標註支援的綁定類型或該類型清單,例如 list[office365.GraphClientReceiveMessage]。 支援的 SDK 綁定會回傳單一事件與批次調用的清單。 對於批次輪詢,轉換器會將傳輸事件及其有效載荷項目合併成一個清單。

在裝飾器中設定 cardinality=func.Cardinality.MANY 以啟用呼叫批次處理。 單靠清單註解並不能啟用批次處理。 批次大小設定計算的是連接器事件,而非事件有效載荷內的項目或回傳清單中的模型數量。

連線存取與回撥授權是分開的。 連接器命名空間會自動處理其對受管理連接器連線的存取。 依照其傳遞方式設定功能應用程式的存取權限。

投票模式

Attributes

當DeliveryMode設定為 ConnectorTriggerDeliveryMode.Poll時,該ConnectorTrigger屬性支援以下屬性:

Property Required 預設值 Description
DeliveryMode 是的,用於民調 ConnectorTriggerDeliveryMode.Webhook 設定為 ConnectorTriggerDeliveryMode.Poll 使用輪詢。
Connection Yes null 識別連接器命名空間輪詢端點及身份設定的設定前綴。 例如, "ConnectorNamespace" 選取 ConnectorNamespace__pollingEndpoint。
TriggerConfigName Yes null 連接器命名空間中輪詢觸發器設定的名稱。 直接輸入名稱,或使用應用程式設定表達式,例如 "%OnNewEmailTriggerConfigName%"。
IsBatched No false 每個呼叫是否接收一批連接器事件。 當 false時,每個召喚會接收一次事件。 設定 true 並使用陣列參數來接收批次。 批次會依照每個監聽器逐批處理。
MaxBatchSize No 1 每個呼叫的最大連接器事件數,範圍為 1 到 32。 若省略或設定為0,則defaultMaxBatchSize使用主機設定,除非 host.json另有設定,否則預設為1。 當 為 時false,有效批次大小必須為 。1IsBatched
MaxConcurrentCalls No 16 每個監聽者在單一實例上可執行的最大同時單事件處理任務,包括準備、呼叫與確認。 必須是非負數。 若省略或設定為0,則defaultMaxConcurrentCalls使用主機設定,除非 host.json另有設定,否則預設為16。 僅在 IsBatched 為 false 時適用。 批次呼叫則是每個監聽器一次處理一個批次。
TargetPendingEventThreshold No 16 針對目標式擴展,每個實例所需待處理連接器事件數量。 必須是非負數。 若省略或設定為0,則defaultTargetPendingEventThreshold使用主機設定,除非 host.json另有設定,否則預設為16。 執行時可以覆寫此縮放目標。 此屬性不會改變批次大小或調用並行性。

關於整個應用程式的預設值,請參閱 輪詢 host.json 設定。 批次大小計算的是連接器事件,而非事件有效載荷中的項目。

民調裝飾師

設定delivery_mode=func.DeliveryMode.POLL@app.connector_trigger並設定輪詢連線與觸發器設定:

Parameter Required 預設值 Description
arg_name Yes None 識別接收有效載荷的函數參數。
delivery_mode 是的,用於民調 func.DeliveryMode.WEBHOOK 設定為 func.DeliveryMode.POLL 使用輪詢。 琴弦"Poll""Webhook"也有支撐。
connection Yes None 識別輪詢端點及身份設定的設定前綴。 例如, "ConnectorNamespace" 選取 ConnectorNamespace__pollingEndpoint。
trigger_config_name Yes None 識別輪詢觸發器的設定。 直接輸入名稱,或使用應用程式設定表達式,例如 "%OnNewEmailTriggerConfigName%"。
cardinality No func.Cardinality.ONE 設定為 func.Cardinality.MANY 或 "many" 以啟用呼叫批次處理。 批次呼叫會依照每個監聽器逐一處理。
max_batch_size No 主機預設值: 1 每個呼叫的最大連接器事件數,範圍為 1 到 32。 若省略或設為 0,則使用 defaultMaxBatchSizehost.json。 若不進行批次處理,有效批次大小必須為 1。
max_concurrent_calls No 主機預設值: 16 每個監聽器在單一實例上可同時處理的單一事件處理任務上限。 若省略或設為 0,則使用 defaultMaxConcurrentCallshost.json。 必須是非負數。 不適用於批次調用。
target_pending_event_threshold No 主機預設值: 16 針對目標式縮放,針對每個實例處理待處理事件。 若省略或設為 0,則使用 defaultTargetPendingEventThresholdhost.json。 必須是非負數。 不會改變批次大小或調用並發性;執行時可以覆寫縮放目標。

關於整個應用程式的預設值,請參閱 輪詢 host.json 設定。 關於參數形狀與 SDK 註解,請參閱 繫結類型。

投票登記選項

設定 deliveryMode: 'Poll' 為命名輔助器、通用 connectorTrigger 輔助器或 app.connectorTrigger,並設定輪詢連線與觸發器設定:

Option Required 預設值 Description
deliveryMode 是的,用於民調 'Webhook' 設定為 'Poll' 使用輪詢。
connection Yes None 識別輪詢端點及身份設定的設定前綴。 例如, 'ConnectorNamespace' 選取 ConnectorNamespace__pollingEndpoint。
triggerConfigName Yes None 識別輪詢觸發器的設定。 直接輸入名稱,或使用應用程式設定表達式,例如 '%OnNewEmailTriggerConfigName%'。
cardinality No 'one' 設定為 以 'many' 啟用呼叫批次處理。 批次呼叫會依照每個監聽器逐一處理。
maxBatchSize No 主機預設值: 1 每個呼叫的最大連接器事件數,範圍為 1 到 32。 若省略或設為 0,則使用 defaultMaxBatchSizehost.json。 若不進行批次處理,有效批次大小必須為 1。
maxConcurrentCalls No 主機預設值: 16 每個監聽器在單一實例上可同時處理的單一事件處理任務上限。 若省略或設為 0,則使用 defaultMaxConcurrentCallshost.json。 必須是非負數。 不適用於批次調用。
targetPendingEventThreshold No 主機預設值: 16 針對目標式縮放,針對每個實例處理待處理事件。 若省略或設為 0,則使用 defaultTargetPendingEventThresholdhost.json。 必須是非負數。 不會改變批次大小或調用並發性;執行時可以覆寫縮放目標。

關於整個應用程式的預設值,請參閱 輪詢 host.json 設定。 有關處理器輸入形狀,請參閱 繫結類型。

輪詢端點

函式的連線設定會選擇輪詢端點的前綴。 例如,前綴 "ConnectorNamespace" 使用 ConnectorNamespace__pollingEndpoint。 請在 Values 本地開發 local.settings.json 或已部署函式應用程式的應用程式設定中定義此設定,如 同輪詢範例所示。

從 連接器命名空間入口擷取輪詢端點,或依照下列方式從觸發器設定的服務產生 pollingEndpoints.receiveUri 端點中導出。 請將佔位符替換為您的資源值。

需要 Azure CLI、jq、sed以及 。

triggerConfigId="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/connectorGateways/<namespace-name>/triggerConfigs/<trigger-config-name>"
triggerConfig=$(az rest --method get \
    --url "${triggerConfigId}?api-version=2026-05-01-preview" \
    --query '{receiveUri:properties.pollingEndpoints.receiveUri,name:name}' \
    --output json)
receiveUri=$(printf '%s' "$triggerConfig" | jq -r '.receiveUri')
pollingEndpoint=$(printf '%s' "$receiveUri" |
    sed -E 's#/(api/)?trigger[Cc]onfigs/[^/]+/receive$##')
triggerConfigName=$(printf '%s' "$triggerConfig" | jq -r '.name')
printf '%s\n' "ConnectorNamespace__pollingEndpoint=$pollingEndpoint" \
    "OnNewEmailTriggerConfigName=$triggerConfigName"

從服務產生的 Receive URI 中推導出以下設定:

服役 pollingEndpoints.receiveUri <Connection>__pollingEndpoint
https://<connector-namespace-host>/api/triggerconfigs/<name>/receive https://<connector-namespace-host>
https://<host>/api/connectorGateways/<id>/triggerconfigs/<name>/receive https://<host>/api/connectorGateways/<id>

保留服務提供的主機與閘道識別碼;不要猜測主機名稱,也不要設定完整的接收 URL、操作路徑、獨立 /api 基底或查詢字串。

擴充功能會使用此端點搭配觸發器設定名稱來建構輪詢操作 URL。 有關呼叫這些 URL 所需的憑證與存取政策,請參閱輪 詢驗證。

輪詢觸發器設定

函式的觸發器配置名稱用來識別要接收事件的配置。

輪詢觸發條件設定值

設定值 Description
連線 授權的管理連接器連接,例如 Office 365 Outlook 或 SharePoint Online。 這與函式的連線設定是分開的,後者用來識別應用程式設定的前綴。
作業名稱 連接器觸發操作,例如 OnNewEmailV3 或 GetOnNewFileItems。
Parameters 操作所需的數值,例如 Outlook 資料夾或 SharePoint 網站與文件庫。
觸發器設定名稱 此輪詢觸發器設定的名稱,由函式直接參考或透過應用程式設定參照。
交貨模式 事件如何透過服務傳遞,無論是輪詢或 Webhook 模式。

建立輪詢觸發器設定

  1. 如果你還沒有連接器命名空間,請 建立一個連接器命名空間。

  2. 前往 連接器命名空間入口網站,然後選擇你的命名空間。

  3. 在命名空間選單中,選擇 觸發器,然後選擇 建立。

  4. 找到你想使用的管理連接器,然後選擇應該觸發該函式的事件。

  5. 在觸發設定頁面,建立連線或選擇現有連線。 建立連線需要與外部服務進行一次性驗證。

  6. 提供活動所需的輸入。 例如,Office 365 Outlook 新郵件事件要求資料夾監控新郵件。

  7. 在目的地類型中,選擇 Azure Functions。

  8. 在傳送模式中,選擇 「輪詢」。

  9. 檢閱設定,然後選取 [建立]。

輪詢驗證

對於輪詢,請授予函式應用程式的管理身份(已部署)或您的開發者身份(本地)連線層級存取政策。 Functions 主機使用此身份的 Microsoft Entra 認證,透過輪詢端點接收並確認事件。 連接器命名空間自身的連線存取會自動處理。

呼叫者的政策授予對受管理連接器連線的存取權, 而非 命名空間本身。 登入或啟用受管理身份並不會自動授予呼叫者此存取權。

與 webhook 傳遞不同,輪詢不需要公開回調 URL 或函式應用程式系統金鑰,因為函式應用程式是從命名空間擷取事件,而非接收回呼。

以下各小節的驗證設定使用與觸發器範例相符的前綴 ConnectorNamespace。 如果您的函式使用不同的連線設定前綴,請改用該前綴。

授權存取政策

使用任一方法授予輪詢呼叫者連線的存取權。 您需要權限才能管理連線上的存取政策。 請使用呼叫者的主體(物件)ID,而非其應用程式(用戶端)ID。

  1. 前往 連接器命名空間入口網站,然後選擇你的命名空間。
  2. 開啟 「連線」,並選擇您輪詢觸發器設定所使用的受管理連接器連線。
  3. 開啟連線的 「存取原則 」索引標籤。
  4. 新增來電者身份的存取政策。 本地開發時,請使用您的開發人員帳戶的物件 ID。 對於已部署的功能應用程式,請使用應用程式所使用的管理身份的主體(物件)ID。
  5. 確認來電者在連線上有存取政策。

地方發展

  1. 以您的開發者身份登入,例如執行 az login。 這是擴充功能用來在本機驗證輪詢請求的 Microsoft Entra 帳戶。
  2. 為該身份在受管理連接器連線上授予存取原則。 僅登入並不會授予連線存取權。
  3. 在 local.settings.json下定義連線設定Values。 省略 ConnectorNamespace__credential 使用開發者憑證。

已部署函式應用程式

  1. 在功能應用程式啟用系統指派的管理識別碼,或為其指派使用者指派的管理識別碼。
  2. 為該身份在受管理連接器連線上授予存取原則。
  3. 在功能應用程式的應用程式設定中設定以下驗證設定:
應用程式設定 Value
ConnectorNamespace__credential managedidentity
ConnectorNamespace__clientId 用於輪詢的使用者指派管理身份的用戶端 ID。 僅在使用使用者指派身份時設定。

或者,將使用者指派身份的資源 ID 設定 ConnectorNamespace__managedIdentityResourceId 為 ,而非設定 ConnectorNamespace__clientId。 對於系統指派的身份,請省略兩個選擇器。

民調用途

Functions 主機會將外發連線至 Connector 命名空間,以輪詢事件並確認成功呼叫。 擴充功能會把事件傳給你的函式;你不需要寫輪詢迴圈。

交付至少一次。 呼叫失敗不會被確認,且在服務管理鎖定到期後,事件仍可重新傳送。 使處理具有冪等性。

若用於 ConnectorEvent<T>.MessageId 重複資料刪除,請將其範圍限定至命名空間與觸發器設定;不要假設訊息 ID 在不同觸發條件間是唯一的。

設定 DeliveryMode = ConnectorTriggerDeliveryMode.Poll 在 [ConnectorTrigger],並提供 Connection 與 TriggerConfigName 屬性。 請參考 民調範例。

關於屬性屬性、支援值與預設值,請參閱 輪詢屬性屬性。

設定 delivery_mode=func.DeliveryMode.POLL 在 @app.connector_trigger,且 供應 connection 與 trigger_config_name。 請參考 民調範例。

除非啟用批次處理,否則主機每次呼叫 cardinality=func.Cardinality.MANY 只會收到一次事件。 對於原始批次,請使用 typing.List[str] 或 typing.List[bytes];支援的 SDK 註解會提供模型清單。 有關選項、支援值與預設值,請參閱 輪詢裝飾器。

在註冊選項中設定 deliveryMode: 'Poll'、 和 供應connectiontriggerConfigName。 請參考 民調範例。

除非啟用批次處理,否則主機每次呼叫 cardinality: 'many' 只會收到一次事件。 命名與通用輔助程式會將所有事件中的有效載荷項目合併到一個情境中。 直接 app.connectorTrigger 處理程式則接收外部事件陣列。 有關選項、支援值與預設值,請參閱 輪詢註冊選項。

調整和並行

Webhook 傳遞

在 webhook 模式下,連接器命名空間會向擴充功能的回調端點發送 HTTP 請求。 連接器觸發器會像 HTTP 觸發器一樣,根據託管方案的 HTTP 擴展行為與限制而調整。 詳細資訊請參閱 Azure Functions 中的事件驅動縮放。

民調交付

在輪詢模式下,連接器觸發器會根據連接器命名空間中觸發器配置的預估事件積壓,使用基於目標的縮放方式。 縮放目標不受每個實例處理的並發性與批次大小影響。 有關縮放方程式、設定設定及調校指引,請參閱 「受管連接器基於目標的縮放」。

Webhook 模式

Registration

對於沒有連接器特定配準的操作,使用通用 connectorTrigger 函數:

import { InvocationContext } from '@azure/functions';
import {
    connectorTrigger,
    ConnectorTriggerContext,
} from '@azure/functions-extensions-connectors';

connectorTrigger('OnConnectorEvent', {
    handler: async (
        context: ConnectorTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(JSON.stringify(context.rawPayload));
    },
});

通用註冊預設項目類型為 unknown。 在存取操作專屬屬性前,先驗證有效載荷。 在 Azure 連接器命名空間的觸發設定中,設定連接器、操作、操作參數、目的函式及回調認證。

Registration

對於沒有連接器特定配準的操作,使用通用 connectorTrigger 函數:

const {
    connectorTrigger,
} = require('@azure/functions-extensions-connectors');

connectorTrigger('OnConnectorEvent', {
    handler: async (context, invocationContext) => {
        invocationContext.log(JSON.stringify(context.rawPayload));
    },
});

通用註冊會正規化回調包絡,但不會驗證操作特定的有效載荷形狀。 在存取操作專屬屬性前,先驗證有效載荷。 在 Azure 連接器命名空間的觸發設定中,設定連接器、操作、操作參數、目的函式及回調認證。

Decorators

對接收事件有效載荷的函式進行應用 connector_trigger :

import azure.functions as func

app = func.FunctionApp()


@app.function_name(name="OnConnectorEvent")
@app.connector_trigger(arg_name="payload")
def on_connector_event(payload: str) -> None:
    # Process the raw JSON payload.
    pass

該 arg_name 值識別接收有效載荷的函數參數。 在 Azure 連接器命名空間的觸發設定中,設定連接器、操作、操作參數、目的函式及回調認證。

Attributes

與輪詢不同,webhook 傳遞不需要在屬性上 [ConnectorTrigger] 附加額外屬性,因為 webhook 是預設的傳遞模式。 你也可以明確設定 DeliveryMode = ConnectorTriggerDeliveryMode.Webhook 。 輪詢專屬屬性不適用於 webhook 傳遞。

Webhook 觸發程序設定

觸發器設定的回呼 URL 會識別目標函式。

Webhook 觸發器設定值

設定值 Description
連線 授權的管理連接器連接,例如 Office 365 Outlook 或 SharePoint Online。
作業名稱 連接器觸發操作,例如 OnNewEmailV3 或 GetOnNewFileItems。
Parameters 操作所需的數值,例如 Outlook 資料夾或 SharePoint 網站與文件庫。
回呼 URL Connector 擴充 webhook 端點用於目的地函式。 請參閱 Webhook 驗證。
函式名稱 你應用程式代碼中註冊的功能名稱。
Authentication 用來呼叫函式應用程式的驗證設定。

functionName回呼 URL 中的查詢字串值必須與已註冊函式名稱相符。 有效的 webhook 函式名稱包含 1 到 128 個字母、數字、底線或連字號。

建立 webhook 觸發器設定

請使用 Azure CLI 或 Connector Namespace 入口建立觸發設定。

設定觸發程序

Azure Connector 命名空間中的觸發設定會將外部服務事件與目的地函式回撥關聯起來。

觸發設定值

設定值 Description
連線 授權的管理連接器連接,例如 Office 365 Outlook 或 SharePoint Online。
作業名稱 連接器觸發操作,例如 OnNewEmailV3 或 GetOnNewFileItems。
Parameters 操作所需的數值,例如 Outlook 資料夾或 SharePoint 網站與文件庫。
回呼 URL Connector 擴充 webhook 端點用於目的地函式。 請參閱 Webhook 驗證。
函式名稱 你應用程式代碼中註冊的功能名稱。
Authentication 用來呼叫函式應用程式的驗證設定。

functionName觸發設定回調 URL 中的查詢字串值必須與註冊函式名稱相符。 有效的函式名稱包含 1 到 128 個字母、數字、底線或連字號。

操作名稱由管理連接器定義。 你在程式碼中選擇函式名稱,觸發設定會將操作映射到該函式。 本文範例使用以下映射:

連接器事件 作業名稱 函式名稱
新Office 365 Outlook電子郵件 OnNewEmailV3 OnNewEmail
新的 SharePoint Online 檔案 GetOnNewFileItems OnSharepointNewFile
新的 Microsoft Teams 頻道訊息 OnNewChannelMessage OnNewChannelMessage
已選連接器事件 觸發器設定中所選擇的操作 OnConnectorEvent
連接器事件 作業名稱 函式名稱
新Office 365 Outlook電子郵件 OnNewEmailV3 OnNewEmail
新的 SharePoint Online 檔案 GetOnNewFileItems OnSharepointNewFile
已選連接器事件 觸發器設定中所選擇的操作 OnConnectorEvent

建立觸發設定

請使用 Azure CLI 或 Connector Namespace 入口建立觸發設定。

在擴充功能接收事件之前,先建立以下資源與設定:

  1. 一個連接器命名空間。
  2. 一個被授權存取外部服務的管理連接器連線。
  3. 一個觸發器配置,用來選擇連接器事件、操作參數及傳遞模式。

對於 webhook 傳遞,觸發器設定也會包含 回調 URL 與 回調驗證。

觸發器配置是連接器命名空間資源,您也可以透過 ARM 或 Bicep 部署。

以下 Azure CLI 範例使用已部署的函式應用程式。 在執行應用程式之前,先部署包含擴充功能和目標函數的應用程式。

以下 Bash 範例使用 Azure CLI 和 jq 來建立Office 365 Outlook的新郵件觸發器。 替換資源和連線的佔位值:

resourceGroup="<RESOURCE_GROUP>"
namespaceName="<CONNECTOR_NAMESPACE>"
functionAppName="<FUNCTION_APP>"
functionName="OnNewEmail"
triggerName="<TRIGGER_NAME>"
connectionName="<CONNECTION_NAME>"
connectorName="office365"
operationName="OnNewEmailV3"
subscriptionId=$(az account show --query id --output tsv)

connectorKey=$(az functionapp keys list \
    --resource-group "$resourceGroup" \
    --name "$functionAppName" \
    --query "systemKeys.connector_extension" \
    --output tsv)

callbackUrl="https://${functionAppName}.azurewebsites.net/runtime/webhooks/connector?functionName=${functionName}"

notificationFile=$(mktemp)
trap 'rm -f "$notificationFile"' EXIT

jq -n \
    --arg callbackUrl "$callbackUrl" \
    --arg connectorKey "$connectorKey" \
    '{
        callbackUrl: $callbackUrl,
        authentication: {
            type: "QueryString",
            name: "code",
            value: $connectorKey
        }
    }' > "$notificationFile"

az connector-namespace trigger create \
    --resource-group "$resourceGroup" \
    --namespace "$namespaceName" \
    --name "$triggerName" \
    --connection-details "{connectionName:${connectionName},connectorName:${connectorName}}" \
    --operation-name "$operationName" \
    --parameters "[{name:folderPath,value:'Inbox'}]" \
    --notification-details "@$notificationFile" \
    --description "${connectorName} ${operationName} -> ${functionName}" \
    --metadata "{destinationType:functionApp,functionAppName:${functionAppName},functionAppResourceGroup:${resourceGroup},functionAppSubscriptionId:${subscriptionId},functionName:${functionName},recurrenceFrequency:Minute,recurrenceInterval:'5'}"

rm -f "$notificationFile"
trap - EXIT

該 --parameters 值是針對連接器操作而定的。 在這個例子中,folderPath選擇要監控的 Outlook 資料夾。 回調網址不包含系統金鑰。 當 Connector 命名空間呼叫函式時,物件 notificationDetails.authentication 會將該金鑰加入查詢字串祕密。

Webhook 驗證

連接器命名空間會將事件傳送到函式應用程式,而非函式應用程式輪詢命名空間。 預設情況下,Functions 主機透過驗證 Connector 擴充功能的系統金鑰(名為 connector_extension)來驗證這些回呼。

連接器命名空間會自動處理對其受管理連接器連線的存取。 與輪詢不同,函式應用程式的身份並不需要連線存取政策來接收 webhook 回呼;系統金鑰授權這些請求給函式應用程式。

Webhook 回呼 URL

已部署的應用程式

使用擴充功能的回呼端點,但不在 URL 中輸入金鑰:

https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>

functionName該值必須與已註冊的函式名稱相符:[Function]C# 中的屬性、@app.function_namePython 中的 decorator,或 Node.js中的觸發器註冊。

對於使用預設驗證的已部署應用程式,請使用 Connector 擴充功能的 connector_extension 系統金鑰,而非單一功能金鑰。 部署帶有擴充功能的功能應用程式後,擷取系統金鑰:

az functionapp keys list \
    --resource-group <RESOURCE_GROUP> \
    --name <FUNCTION_APP_NAME> \
    --query "systemKeys.connector_extension" \
    --output tsv

在觸發器設定中,將金鑰與回調 URL 分開儲存在 notificationDetails.authentication中:

{
  "notificationDetails": {
    "callbackUrl": "https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>",
    "authentication": {
      "type": "QueryString",
      "name": "code",
      "value": "<CONNECTOR_EXTENSION_KEY>"
    }
  }
}

在傳遞事件時,連接器命名空間會將該鍵加入為 code 查詢字串參數。 將金鑰與儲存的回撥網址分開,讓入口網站將其偽裝成秘密。 不要在儲存的回調 URL 中包含該金鑰,也不要將其提交給原始碼控制。

在回呼 URL 中包含金鑰的現有觸發設定仍可正常運作。 當你編輯並儲存現有的觸發設定時,金鑰會移到 notificationDetails.authentication。

系統鍵無法針對每個觸發器進行範圍限制,且需要在函式應用程式與連接器命名空間間協調輪換。 關於沒有共用金鑰的基於身份的回呼,請參閱 內建驗證。

本地 webhook 開發

Webhook 回呼必須從 Connector 命名空間傳送到您正在執行的 Functions 主機。 當您在本地執行時:

  1. 使用 Azure Functions Core Tools 啟動函數應用程式,啟用授權:

    func start --enableAuth
    

    Important

    在透過開發隧道公開你的應用程式時,一定要使用 --enableAuth 。 沒有它,你的函數端點在公開網際網路上完全未經驗證。

  2. 使用 Microsoft 開發隧道將公開 HTTPS 端點轉送至本地 Functions 主機連接埠。 將隧道埠可見性設定為 公開 ,以便連接器命名空間能存取該埠。

  3. 建立包含隧道主機名稱與已註冊函式名稱的回呼 URL,並在 webhook 觸發器設定中使用。 例如,將 7071 埠轉發到函 OnNewFile 式時,會使用類似這樣的 URL 來實現:

    https://<tunnel-id>-7071.usw2.devtunnels.ms/runtime/webhooks/connector?functionName=OnNewFile
    

    對於在 Azurite 中儲存密鑰的本機主機,請使用以下 PowerShell 指令取得其 connector_extension 系統金鑰。 設定$connStr為廣為人知的 Azurite 連接字串:

    $connStr = "<azurite-connection-string>"
    
    # Find the most recent host.json blob
    $blobs = az storage blob list --container-name azure-webjobs-secrets --connection-string $connStr -o json | ConvertFrom-Json
    $blobName = ($blobs | Where-Object { $_.name -match '(^|/)host\.json$' } | Sort-Object { $_.properties.lastModified } | Select-Object -Last 1).name
    
    # Download and parse
    az storage blob download --container-name azure-webjobs-secrets --name $blobName --connection-string $connStr --file host-keys.json --no-progress
    $keys = Get-Content host-keys.json | ConvertFrom-Json
    $connectorKey = ($keys.systemKeys | Where-Object { $_.name -eq "connector_extension" }).value
    Remove-Item -LiteralPath host-keys.json
    

    請使用上述驗證格式,將本機主機connector_extension的系統金鑰分別儲存在 notificationDetails.authentication。QueryString

  4. 測試期間保持主機和隧道運作。 如果隧道主機名稱變更,請更新觸發器設定。

內建驗證

對於沒有共用金鑰的 webhook 回調,請使用 App Service 內建的驗證 (也稱為 Easy Auth),搭配受管理身份。 此配置與函式的程式語言無關。

連接器命名空間會使用其系統指派或使用者指派的管理身份,為每個回調請求一個 Microsoft Entra ID 令牌。 內建驗證會在請求抵達 Functions 主機前驗證令牌與呼叫者的身份。 若要採用不含用戶端密鑰的端對端實作,請參閱 內建驗證範例。

本節涵蓋從命名空間到函式應用程式的驗證。 連接器命名空間會自動處理對其受管理連接器連線的存取。 關於上游服務的驗證,請參閱 Azure 連接器概覽。

函數應用程式設定

Important

此配置要求整個函式應用程式進行驗證,而非僅限 /runtime/webhooks/connector於 ,並限制對命名空間回調身份的存取。 現有需要功能金鑰的 HTTP 函式,除了應用程式層級驗證外,仍需使用這些金鑰。 在將此配置套用於現有應用程式之前,請確保 API 用戶端與健康探測能滿足應用程式層級的驗證與授權政策,以及任何功能層級的金鑰需求。 否則,使用 HTTP 401 或 403 時,請求可能會失敗。 如果應用程式必須接受其他呼叫者,請調整授權政策,而非原封不動地複製此允許清單。 有關政策選項,請參閱設定 Microsoft Entra 授權。

透過功能應用程式的 authsettingsV2 ARM 資源或其在 Bicep 中的等效資源設定內建驗證。 範例使用以下關鍵設定:

Setting Purpose
platform.enabled: true 啟用內建驗證功能。
globalValidation.requireAuthentication: true 在請求到達 Functions 主機之前,必須進行驗證。
globalValidation.unauthenticatedClientAction: Return401 對於未驗證的回調回傳 HTTP 401,而非重新導向至登入頁面。
identityProviders.azureActiveDirectory.enabled: true 啟用 Microsoft Entra 令牌驗證。
registration.clientId 代表該函數應用程式的 Microsoft Entra 應用程式註冊的應用程式(用戶端)ID。
registration.openIdIssuer 你的租戶發行者網址是: https://login.microsoftonline.com/{tenantId}/v2.0。
validation.allowedAudiences Entra 應用程式的用戶端 ID 與識別碼 URI。 憑證必須在聲明中 aud 攜帶允許的受眾。
validation.defaultAuthorizationPolicy.allowedPrincipals.identities 允許呼叫函式應用程式的物件(主體)ID。 範例僅允許命名空間的回調管理身份。 如果您的應用程式有其他來電者,請調整此政策。 有效的令牌若其 oid 聲明不在允許清單中,HTTP 403 會被拒絕。

registration此表中的 and validation 設定位於 identityProviders.azureActiveDirectory。

範例同時為函式應用程式指派使用者指派的管理身份,並將其 與 Entra 應用程式註冊聯合。 內建驗證利用此 聯邦身份認證 取得用戶端聲明,且不儲存用戶端密鑰。 範例將應用程式設定 OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID 設定為函式應用程式識別碼的用戶端 ID,並設定 registration.clientSecretSettingName 為該設定的名稱。

用於聯邦的函式應用程式識別碼與命名空間的回呼識別碼是分開的。 命名空間的身份是由 allowedPrincipals.identities允許的呼叫者。

在設定內建驗證以驗證回調後,請 host.json停用冗餘的系統金鑰簽入功能:

{
  "version": "2.0",
  "extensions": {
    "connector": {
      "system": {
        "webhookAuthorizationLevel": "Anonymous"
      }
    }
  }
}

僅在另一個驗證層在請求到達 Functions 主機前驗證時使用 Anonymous 。 此設定本身不會啟用令牌驗證。

連接器命名空間配置

在連接器命名空間啟用系統指派的管理身份,或將其附加使用者指派的識別碼。 在觸發器配置中 notificationDetails.authentication,設定:

Property Value
type ManagedServiceIdentity
audience Entra 應用程式註冊的用戶端 ID,與功能應用程式所接受的受眾相符。
identity 附加使用者指派的管理身份的資源 ID。 對於系統指派的身份,請省略此屬性。

命名空間會利用該身份取得一個令牌,並將其傳送到回調 Authorization: Bearer <token> 標頭中。 該 token iss 用來識別租戶、 aud 識別目標應用程式,並 oid 識別命名空間的管理身份。

命名空間會自動處理對受管理連接器連線的存取。 此存取與回呼授權是分開的,回呼授權則是透過函式應用程式內建的驗證來設定。

驗證流程與驗證

  1. 連接器命名空間會利用其回調管理身份,為已設定受眾取得一個權杖。
  2. 命名空間會將帶有事件的權杖傳送到擴充功能的 webhook 端點。
  3. 內建驗證會驗證令牌的簽名、到期時間、發行者與受眾,並檢查其 oid 是否符合允許的身份。 遺失或無效的令牌會收到 HTTP 401;來自不在允許清單中的身份的有效令牌會收到 HTTP 403。
  4. 只有授權的請求才會到達 Functions 主機。 在停用冗餘系統金鑰檢查後,擴充功能會呼叫目的地函數,並將事件主體綁定至其參數。

您的函式不需要應用程式程式碼來執行這些存取檢查。

Webhook 的使用

連接器命名空間會將事件傳送到擴充功能的 webhook 端點,在那裡的 functionName query-string 值選取該函數。 擴充功能會將事件主體綁定到你的函數參數;你並未實作 HTTP 處理器。

函式名稱必須與您的 [Function] 屬性名稱相符。 回呼可以包含 x-ms-* 標頭,用來識別觸發器配置、連線、事件類型及關聯 ID,但這些標頭無法透過連接器觸發器提供給您的函式。

使用 [ConnectorTrigger] 時不使用輪詢屬性。 當你省略 DeliveryMode時,Webhook 是預設的。 請參閱 webhook 範例。

您的函式可以使用任何支援的 .NET 綁定類型來接收事件有效載荷。

擴充功能接受 HTTP POST 及 PUT 內容 application/json 類型的請求。 非空請求主體必須包含有效的 JSON。 請求受 Functions 主機請求主體限制及上游服務限制約束;擴充套件並未對負載大小設下獨立上限。

若要設定主機請求主體限制,請將整個 FUNCTIONS_REQUEST_BODY_SIZE_LIMIT 應用程式的設定(以位元組為單位)設定,然後重新啟動主機。 這不是設定, host.json 也不會改變投票連結輸出下載,這些下載會使用 extensions.connector.maxLinkedOutputSizeInBytes。 較大的限制並不保證支援的有效載荷大小;會考慮緩衝區、工作記憶體以及上游限制。

Webhook 的使用

通用輔助程式會收到一個 ConnectorTriggerContext<T>. 其 payload 屬性包含正規化回調包絡、 items 事件項目,並在 rawPayload 正規化前保留解析後的輸入。 連接器專屬的註冊提供命名陣列,例如 emails、 records、 messages或 。

每個呼叫處理一個回調,該回調可以包含多個有效載荷項目。 對於未進行連接器專屬註冊的操作,TypeScript 項目類型預設為 unknown。 在存取操作特定屬性前,先驗證有效載荷。 有關支援的類型註冊,請參閱 Node.js 連接器延伸參考。

Webhook 的使用

觸發器可以將請求實體綁定於 str、 dict或 bytes。 當 azurefunctions-extensions-connectors 註冊函式的 SDK 註解轉換器時,工作者會將請求實體反序列化為支援的操作特定類型。

每個呼叫處理一次回調。 支援的 SDK 綁定以清單形式提供其有效載荷項目;請使用註解,例如 list[office365.GraphClientReceiveMessage]。 有關支援的操作專屬註解,請參閱 操作簽章映射。

擴充功能接受 HTTP POST 及 PUT 內容 application/json 類型的請求。 非空請求主體必須包含有效的 JSON。 請求受 Functions 主機請求主體限制及上游服務限制限制。

後設資料

Connector 觸發器目前不會將回調標頭或其他請求元資料作為綁定資料暴露。 該擴充定義了一個 空的綁定資料合約,因此函式只會接收所選語言支援的綁定型態中的 JSON 請求主體。