Azure Functions 連接器擴充概覽

Azure Functions 提供與各種服務整合的觸發與繫結擴充功能,主要針對 Azure 服務。 連接器擴充功能透過Azure連接器命名空間中的管理連接器擴展這些整合,讓您的函式接收來自 Office 365 Outlook、SharePoint Online、Microsoft Teams 及 Dataverse 等商業系統與資料平台的事件。

有關可用的 Microsoft 及第三方管理連接器,請參閱連接器參考。

Note

管理連接器支援 Linux Function 應用程式在所有區域的 Flex Consumption、Dedicated 及 Elastic Premium 主機方案。 目前 Windows 應用程式的可用性有限。

Flex Consumption 是連接器觸發功能的推薦託管方案。

Note

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

至 使用
在已連線服務中執行一個函式,回應事件 連接器觸發器,由連接器擴充套件提供
從函式程式碼在已連線的服務中執行動作 Azure 連接器 SDK,適用於 .NET、Node.js及 Python

你可以同時使用兩者:連接器觸發器啟動你的函式,SDK 則在連接的服務中執行動作。 如果您只需要執行動作,請在不使用連接器擴充功能的情況下使用 SDK。

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

Azure Functions 中的 Connector Trigger

連接器觸發函數使用以下元件:

Component 責任
連接器命名空間 主機管理連接器連接與觸發設定。
管理型連接器連接 對外部服務進行認證並管理特定服務的連線。
觸發程式設定 選擇連接器事件、操作參數及 傳送模式。
Azure Functions Connector Extension 從連接器命名空間接收事件,呼叫函數,並將事件主體繫結至函數參數。
Azure Connectors SDK (optional) 提供可選的強型別有效載荷模型與用戶端,用於呼叫管理連接器操作,例如發送電子郵件或建立 SharePoint 檔案。

受管理連接器可支援多個事件,且您想監控的每個事件都需要其獨立的觸發器設定。 例如,Office 365 Outlook連接器支援新郵件抵達、電子郵件被標記、行事曆事件建立或行事曆事件被修改等事件。 為每個想用來執行函式的事件建立獨立的觸發器設定。

有關程式碼範例,請參閱 〈連接器觸發器範例 〉以及〈 在程式碼中使用連接器 SDK〉。

選擇投遞方式

管理式連接器支援 Webhook 與輪詢傳遞。 根據您的情境延遲、處理能力、網路與驗證需求,選擇一種模式:

Feature 投票 Webhook
事件傳遞與延遲 Functions 主機透過外寄輪詢請求擷取事件。 事件會等到主辦方為它們投票後再進行。 連接器命名空間會在事件從來源服務擷取時,立即推送事件至函式應用程式的回呼端點,無需等待應用程式輪詢。 這降低了時效性處理的傳遞延遲。
處理能力與下游保護 當處理容量可用時,主機會擷取更多事件。 將應用程式擴展限制與 輪詢並行設定 結合,以限制同時處理並保護下游資料庫或 API。 待處理事件仍會佇列於連接器命名空間,並受其事件保留限制限制。 事件的到來與應用程式的處理能力無關。 當需求超過容量時,擴展限制可能導致回撥被限速或失敗;若交付未能在服務重試限制內成功,事件可能會遺失。
入站網路 不需要任何入站回撥端點。 您可以限制對函式應用程式的入站存取,同時允許對連接器命名空間輪詢端點的外送請求。 連接器命名空間必須能夠存取應用程式的回呼端點。 入站限制必須允許這些請求。
管理式身份驗證 Functions 主機可以使用功能應用程式的系統指派或使用者指派的管理身份來接收並確認事件。 在 受管理連接器連線上授予該身份存取原則。 對於使用 Microsoft Entra ID 驗證的回調,連接器命名空間會使用其受管理身份。 在接收函式應用程式上設定 App Service 內建驗證 ,以驗證令牌。 預設的 webhook 驗證則改用 Connector 擴充系統金鑰。

根據您的主機方案,您可以使用 私有端點或入站存取限制(包括基於 IP 或服務端點的限制)限制函式應用程式的入站存取,而不阻礙輪詢。 應用程式仍必須能向連接器命名空間的輪詢端點發出外發 HTTPS 請求。 另外,函式應用程式所設定的受管理身份必須在受管理連接器連線上擁有存取原則。

事件傳遞模式控制事件如何從連接器命名空間傳送至 Functions 主機, 而非 受管理連接器如何偵測來源服務的變更。

Webhook 傳遞的擴展方式類似 HTTP 觸發器,而輪詢傳遞則採用基於目標的擴展。 輪詢縮放目標與監聽器並發性及批次大小無關。 有關兩種模式的詳細資訊,請參閱 連接器觸發器縮放與並發。 有關輪詢縮放方程式與調整設定,請參閱 「管理連接器基於目標的縮放」。

兩種模式都使用 [ConnectorTrigger] 接收事件本體的函數參數,且可使用相同的有效載荷模型。 有關兩種傳遞模式的範例,請參閱 連接器觸發器範例。

安裝套件

連接器延伸

連接器觸發器支援 .NET 隔離工作者模型。 關於 Azure Functions 執行時版本中支援的 .NET 版本資訊,請參見「依運行時版本分類的語言」。

將 Connector 擴充套件的 1.0.0 或更新版本新增至您的專案。

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Connector

Azure Connectors SDK

如果您的函數只需要對外部服務執行動作,且不需要由事件觸發,請僅使用 Azure 連接器 SDK。 你不需要 Connector 擴充套件。

新增 Azure 連接器 SDK:

dotnet add package Azure.Connectors.Sdk

對於熱門連接器,SDK 提供強型別用戶端,用於從函式調用連接器動作;請參閱 Azure Connectors SDK for .NET API 參考。

安裝擴充功能

請使用 Node.js 24 或更新。 兩種傳遞方式都使用相同命名或通用的觸發器註冊輔助工具。

安裝連接器觸發器所使用的套件:

npm install "@azure/functions@latest" "@azure/functions-extensions-connectors@latest" "@azure/connectors@latest"

這些套件提供以下功能:

在 host.json 檔案中設定擴充套件。 此套件提供兩種傳遞模式的 Connector 主機擴充功能:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  }
}

Azure Connectors SDK

如果您的函數只需要對外部服務執行動作,且不需要由事件觸發,請只安裝 Azure Connectors SDK for Node.js。 你不需要 Connector 觸發套件。

npm install "@azure/connectors@latest"

SDK 提供強型別用戶端,用於從函式中呼叫連接器動作。

有關最新套件版本及完整專案,請參閱 TypeScript 的 Azure Functions 連接器範例。

兩種配送方式都使用裝飾者。@app.connector_trigger 範例請參閱 連接器觸發器範例。

安裝擴充功能

將下列套件新增至 requirements.txt:

azure-functions>=2.4.0
azurefunctions-extensions-connectors>=1.0.0

Note

對於 3.13 之前的 Python 版本,請改用azure-functions>=1.27.0b1。

  • 核心的 azure-functions Python 函式庫提供裝飾工具,並能將原始單一事件綁定至 str or bytes或 ,或輪詢批次綁定至 typing.List[str]typing.List[bytes]或 。
  • azurefunctions-extensions-connectors 套件整合了 Azure Connectors SDK for Python,並註冊了支援的操作專用 SDK 註解轉換器。 例如,emails: list[office365.GraphClientReceiveMessage]其中 是從 azurefunctions.extensions.connectors匯入的,會接收用於Office 365 OutlookOnNewEmailV3操作的office365電子郵件模型物件。

在 host.json 檔案中設定擴充套件。 此套件提供兩種傳遞模式的 Connector 主機擴充功能:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  }
}

Azure Connectors SDK

如果您的函數只需要對外部服務執行動作,且不需要由事件觸發,請僅安裝 Python 的 Azure 連接器 SDK。 你不需要 Connector 觸發套件。

python -m pip install "azure-connectors>=1.0.0"

SDK 提供強型別用戶端,用於從函式中呼叫連接器動作。

有關最新套件版本及完整專案,請參閱 Python 的 Azure Functions 連接器範例。

host.json 設定

當您使用預設檔時,連接器副檔名不需要在 host.json 檔案中設定特定連接器。

以下章節將展示每種傳遞模式的可選設定。

投票模式

在 host.json 檔案中extensions.connector設定可選的輪詢設定。 例如,以下設定將無事件可用時輪詢之間的延遲限制為一秒:

{
  "version": "2.0",
  "extensions": {
    "connector": {
      "maxPollingInterval": "00:00:01"
    }
  }
}
財產 Default Description
defaultMaxBatchSize 1 當函式未指定正向批次大小覆寫時,每次呼叫的最大事件數值。 有效值為 1 到 32。 值大於 1 需要啟用批次處理。
defaultMaxConcurrentCalls 16 每個監聽者在單一實例上可執行的最大同時單事件處理任務,包括準備、呼叫與確認。 必須是正數。 不適用於批次調用。
defaultTargetPendingEventThreshold 16 當執行環境未提供並發目標時,針對目標式擴展,將每個實例的待處理事件定為目標。 必須是正數。 不受批次大小與呼叫並行性影響。
maxPollingInterval "00:00:30" 在沒有可用事件時,輪詢之間的最大延遲。 至少一秒鐘。 它不控制連接器檢查原始服務的頻率。
maxLinkedOutputSizeInBytes 104857600 (100 MiB) 每個連結事件輸出的最大下載位元組數。 必須是正數。 不適用於內嵌民調回應。 這是下載保護欄,並非支援的有效載荷大小保證。

每個函數的正覆寫優先於對應的主機預設值。 執行時可以在不改變批次大小或監聽器並行性的情況下覆寫縮放目標。 批次會依照每個監聽器逐批處理。 關於語言專屬選項,請參閱 輪詢模式。

連結輸出事件由主機下載並正規化為一般有效載荷形狀。 即使綁定啟用批次處理,它們仍會被主機全域限制器逐個事件呼叫。

增加 maxLinkedOutputSizeInBytes 記憶體可能會耗盡主機或工作記憶體。 在提升負載之前,請先驗證您的主機負載大小;預設設定並未設定支援的負載大小限制。

Webhook 模式

預設系統金鑰驗證在 host.json中不需要針對連接器進行特定設定。 如果 App Service 內建驗證驗證回調,您可以設定 extensions.connector.system.webhookAuthorizationLevel 為 以 Anonymous 停用冗餘的系統金鑰檢查。

僅在另一個驗證層在請求到達 Functions 主機前驗證時使用 Anonymous 。 有關設定細節及完整範例,請參閱 內建驗證。

在程式碼中使用連接器 SDK

Connector SDK 允許您的函式將連接器操作作為外發動作呼叫。 用戶端介面在連接器命名空間中使用與觸發器相同的底層受管理連接器,因此單一受管理連接器可以同時為同一服務帳戶提供入站觸發器與出站呼叫。

驗證入站 Webhook 回呼不會授予函式應用程式進行出站 SDK 呼叫的權限。 對於同時呼叫 SDK 的 webhook 觸發函式,請賦予函式應用程式的管理身分(已部署)或開發者身分(本地)對每個呼叫所使用的受管理連接器連線的存取原則。

對於輪詢而言,函式應用程式的管理身份或開發者身份已經需要連線存取政策。 如果 SDK 用戶端使用相同的身份與連線,現有政策也允許 SDK 呼叫;不需要額外的存取政策指派。

輪詢與 webhook 函數都必須將憑證傳入 SDK 用戶端,如下所示。

在 .NET 中,每個連接器會附送一個型別客戶端(例如 Office365Client、Office365UsersClient、TeamsClient),格式為 Azure.Connectors.Sdk.{Service}。 用戶端建構子會取得連線的執行時 URL 和一個憑證。

以下模式取自 端對端電子郵件使用者查詢 Teams 範例:

using Azure.Core;
using Azure.Identity;
using Azure.Connectors.Sdk.Office365;
using Azure.Connectors.Sdk.Office365Users;
using Azure.Connectors.Sdk.Teams;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions
{
    ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID")
});

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services =>
    {
        services.AddSingleton<TokenCredential>(credential);

        services.AddSingleton(sp => new Office365Client(
            new Uri(Environment.GetEnvironmentVariable("OFFICE365_CONNECTION_RUNTIME_URL")!),
            sp.GetRequiredService<TokenCredential>()));

        services.AddSingleton(sp => new Office365UsersClient(
            new Uri(Environment.GetEnvironmentVariable("OFFICE365USERS_CONNECTION_RUNTIME_URL")!),
            sp.GetRequiredService<TokenCredential>()));

        services.AddSingleton(sp => new TeamsClient(
            new Uri(Environment.GetEnvironmentVariable("TEAMS_CONNECTION_RUNTIME_URL")!),
            sp.GetRequiredService<TokenCredential>()));
    })
    .Build();

host.Run();

此範例建立一個 DefaultAzureCredential,註冊為 TokenCredential,並透過 傳遞給每個 SDK 用戶端的建構子 sp.GetRequiredService<TokenCredential>()。 在本機,該憑證可以使用您的開發人員登入;在 Azure,則可以使用函數應用程式的管理身份。 設定 AZURE_CLIENT_ID 為附加於函式應用程式的使用者指派管理身份的用戶端 ID。 對於系統指派的身份或本地開發者登入,請保持未設定。

*_CONNECTION_RUNTIME_URL 設定指向位於連接器命名空間中的各連線執行階段端點。 將用戶端注入函式中,並呼叫具型別的方法,例如 UserProfileAsync、GetEmailsAsync 或 FlagAsync。 你也可以從非連接器觸發器呼叫 SDK 客戶端(例如,發佈到 Teams 的 HTTP 觸發器)。

以下簡明摘錄自「 電子郵件至團隊」範例 ,使用注入 Office365Client 的郵件標記郵件以進行後續追蹤。 從您函式的處理代碼中呼叫此助理,並附上電子郵件的訊息 ID:

using Azure.Connectors.Sdk.Office365;
using Azure.Connectors.Sdk.Office365.Models;

public class ProcessEmail(Office365Client office365Client)
{
    public async Task FlagEmailAsync(string messageId)
    {
        await office365Client.FlagAsync(
            messageId: messageId,
            input: new UpdateEmailFlag { Flag = new { flagStatus = "flagged" } },
            originalMailboxAddress: null,
            cancellationToken: default);
    }
}

在 Python 中,azure-connectors提供如 Office365Client 和 TeamsClient的型別客戶端。 將每個連線的執行時 URL 與憑證傳遞給用戶端建構子。 對於 Microsoft Entra ID 驗證,請使用非同步認證,例如 azure.identity.aio.DefaultAzureCredential。 等待 SDK 操作。

在 Node.js中, @azure/connectors 提供如 Office365Client 和 TeamsClient的型別客戶端。 將每個連線的執行時 URL 及認證(例如 DefaultAzureCredential from @azure/identity)傳入用戶端建構子。 等待 SDK 操作。