Azure Functions 開發人員指南

在 Azure Functions 中,不論您使用何種語言或繫結,特定函式都會共用一些核心技術概念和元件。 閱讀指定語言或繫結特有的詳細資料之前,請務必詳閱這份適用於所有語言或繫結的概觀。

本文假設您已閱讀過 Azure Functions 開發人員概觀

函式程式碼

「函數」 是 Azure Functions 中的主要概念。 函式包含兩個重要的部分,一個部分是可用各種語言撰寫的程式碼,另一則是一些組態,亦即 function.json 檔案。 對於已編譯的語言,系統會自動從您程式碼中的註解產生此組態檔。 對於指令碼語言,您必須自行提供組態檔。

function.json 檔案會定義函式的觸發程序、繫結和其他組態設定。 每個函式會有一個且只能有一個觸發程序。 執行階段使用此組態檔來判斷要監視的事件,以及如何傳入資料並從函式執行傳回資料。 以下是範例 function.json 檔案。

{
    "disabled":false,
    "bindings":[
        // ... bindings here
        {
            "type": "bindingType",
            "direction": "in",
            "name": "myParamName",
            // ... more depending on binding
        }
    ]
}

如需詳細資訊,請參閱 Azure Functions 觸發程式和系結概念。

bindings 屬性可讓您設定觸發程序和繫結。 每個繫結都共用一些共用設定,以及特定類別的繫結特有的一些設定。 每個繫結都需要下列設定︰

屬性 類型 註解
類型 系結的名稱。

例如: queueTrigger
string
direction in, out string 表示繫結用於將資料接收到函數,還是從函數傳送資料。
NAME 函數識別碼。

例如: myQueue
string 用於函式中所繫結資料的名稱。 在 C# 中,這是引數名稱;在 JavaScript 中,這是索引鍵/值清單中的索引鍵。

函數應用程式

函數應用程式在 Azure 中提供您的函式可在其中執行的執行內容。 因此,它是您的函式部署和管理的單位。 函式應用程式是由一或多個個別函式所組成,這些函式可一起管理、部署與調整。 函數應用程式中的所有函式都會共用相同的定價方案、部署方法和執行階段版本。 請將函式應用程式視為用來組織及集體管理函式的方式。 若要深入瞭解,請參閱 如何管理函數應用程式

注意

函式應用程式中的所有函式都必須以相同的語言撰寫。 在舊版的 Azure Functions 執行階段中,這不是必要的。

資料夾結構

特定函式應用程式中所有函式的程式碼都位於包含主機設定檔的根專案資料夾中。 host.json 檔案包含執行階段特有的組態,且位於函式應用程式的根資料夾中。 bin 資料夾包含函式應用程式需要的封裝和其他程式庫檔案。 函數應用程式所需的特定資料夾結構取決於語言:

在 2.x 版和更高版本的 Functions 執行階段中,函式應用程式中所有的應用程式必須共用相同的語言堆疊。

以上是 Function 應用程式的預設 (且建議的) 資料夾結構。 如果您想要變更函式程式碼的檔案位置,請修改 function.json 檔案的 scriptFile 區段。 我們也建議您使用套件部署來將您的專案部署到 Azure 中的函數應用程式中。 您也可以使用諸如持續整合與部署和 Azure DevOps 之類的現有工具。

注意

如果手動部署封裝,請務必將您的 host.json 檔案和函式資料夾直接部署至 wwwroot 資料夾。 您的部署中請勿包含 wwwroot 資料夾。 否則,您會得到 wwwroot\wwwroot 資料夾。

使用本機工具與發佈

您可以使用各種工具來製作及發佈函數應用程式,包括 Visual StudioVisual Studio CodeIntelliJEclipseAzure Functions Core Tools。 如需詳細資訊,請參閱如何在本機撰寫 Azure Functions 程式碼並進行測試

如何在 Azure 入口網站中編輯函式

Azure 入口網站內建的函式編輯器可讓您更新您直接內嵌的程式碼和 function.json 檔案。 這僅建議用於概念的小型變更或證明 - 最佳作用是使用如 VS Code 等本機開發工具。

平行執行

發生速度比單一執行緒函數執行階段快的多個觸發事件可以處理它們時,執行階段可能會平行多次叫用函數。 如果函式應用程式使用取用主控方案,則函式應用程式可以自動相應放大。 不論應用程式是在取用主控方案還是一般 App Service 主控方案上執行,函式應用程式的每個執行個體可能都會使用多個執行緒平行處理並行函式引動。 每個函式應用程式執行個體中的並行函式叫用次數上限,根據使用的觸發程序類型及函式應用程式內其他函式所使用的資源而有所不同。

Functions 執行階段版本設定

您可以使用 FUNCTIONS_EXTENSION_VERSION 應用程式設定來設定 Functions 執行階段的版本。 例如,值 "~ 3" 表示您的函數應用程式會使用3.x 作為其主要版本。 函數應用程式會在發行時升級為每個新的次要版本。 如需詳細資訊 (包括如何檢視函式應用程式的完全版本),請參閱如何設定 Azure Functions 的執行階段目標版本

儲存機制

Azure Functions 的程式碼是開放原始碼,儲存於 GitHub 儲存機制中︰

繫結

以下是所有已支援繫結的表格。

此表顯示主要版本的 Azure Functions 執行階段中所支援的繫結:

類型 1.x 2.x 和更新版本1 觸發程序 輸入 輸出
Blob 儲存體
Azure Cosmos DB
Dapr3
Event Grid
事件中樞
HTTP 和 Webhook
IoT 中心
Kafka2
Mobile Apps
通知中樞
佇列儲存體
RabbitMQ2
SendGrid
服務匯流排
SignalR
表格儲存體
計時器
Twilio

1 從 2.x 版執行階段開始,必須註冊 HTTP 和計時器以外的所有繫結。 請參閱註冊繫結延伸模組

2 觸發程序在取用方案中不受支援。 需要執行階段驅動的觸發程序

3 僅在 Kubernetes、IoT Edge 和其他自我裝載模式中受到支援。

遇到繫結發生錯誤的問題嗎? 請檢閱 Azure Functions 繫結錯誤碼文件。

連接

您的函式專案會依名稱參考其設定提供者的連接資訊。 它不會直接接受連線詳細資料,讓它們可以跨環境進行變更。 例如,觸發程序定義可能包含 connection 屬性。 這可能會參考連接字串,但您無法直接在中設定連接字串 function.json 。 相反地,您會將設定 connection 為包含連接字串的環境變數名稱。

預設設定提供者會使用環境變數。 這些可能會由應用程式設定在 Azure Functions 服務中執行,或在本機開發時從本機設定檔案進行設定。

連接值

當連接名稱解析為單一精確值時,執行時間會將值識別為 連接字串,通常會包含秘密。 連接字串的詳細資料是由您要連接的服務所定義。

不過,連接名稱也可以參考多個設定專案的集合。 您可以使用以雙底線結尾的共用前置詞,將環境變數視為集合 __ 。 接著,您可以藉由將連接名稱設定為此前置詞來參考群組。

例如, connection Azure Blob 觸發程序定義的屬性可能是 Storage1 。 只要沒有以其名稱設定的單一字串值 Storage1Storage1__serviceUri 就會用於 serviceUri 連接的屬性。 每個服務的連接屬性都不同。 請參閱使用連接的擴充功能檔。

設定以身分識別為基礎的連接

Azure Functions 中的某些連接設定為使用身分識別,而不是秘密。 支援取決於使用連接的擴充功能。 在某些情況下,即使您所連接的服務支援以身分識別為基礎的連接,函式中仍可能需要連接字串。

所有方案中的下列觸發程式和系結延伸模組都支援以身分識別為基礎的連接:

注意

Durable Functions 不支援以身分識別為基礎的連接。

擴充功能名稱 延伸模組版本
Azure Blob 第5.0.0 版-Beta1 或更新版本
Azure 佇列 第5.0.0 版-Beta1 或更新版本
Azure 事件中樞 第5.0.0 版-Beta1 或更新版本
Azure 服務匯流排 第5.0.0 版-Beta2 或更新版本

函數執行時間 () 所使用的儲存體連接, AzureWebJobsStorage 也可以使用以身分識別為基礎的連接進行設定。 請參閱下方 的身分識別連線到主機儲存體

在 Azure Functions 服務中裝載時,以身分識別為基礎的連接會使用 受控識別。 預設會使用系統指派的身分識別,雖然您可以使用和屬性指定使用者指派的身分識別 credential clientID 。 當您在其他內容(例如本機開發)中執行時,會改用您的開發人員身分識別,雖然可以使用替代的連接參數來自訂此識別碼。

授與身分識別的許可權

無論使用何種身分識別,都必須擁有執行所需動作的許可權。 這通常是藉由在 Azure RBAC 中指派角色,或在存取原則中指定身分識別來完成,端視您所連接的服務而定。 請參閱每個延伸模組的檔,以瞭解所需的許可權,以及如何設定它們。

重要

某些許可權可能會由目標服務公開,而不是所有內容所需的許可權。 可能的話,請遵循 最低許可權的原則,只授與身分識別所需的許可權。 例如,如果應用程式只需要從 blob 讀取,請使用儲存體 blob 資料讀取器角色,因為儲存體 blob 資料擁有者包含讀取作業的過多許可權。 下列角色涵蓋一般作業中每個延伸模組所需的主要許可權:

服務 內建角色範例
Azure Blob 儲存體 blob 資料讀取器儲存體 blob 資料擁有
Azure 佇列 儲存體佇列資料讀取器儲存體佇列資料訊息處理器儲存體佇列資料訊息寄件者儲存體佇列資料參與者
事件中樞 Azure 事件中樞資料接收器Azure 事件中樞資料傳送者、 Azure 事件中樞資料擁有
服務匯流排 azure服務匯流排資料接收器azure 服務匯流排資料傳送者、 azure 服務匯流排資料擁有

連線內容

Azure 服務以身分識別為基礎的連線會接受下列屬性:

屬性 擴充功能的必要部分 環境變數 描述
服務 URI Azure Blob1,azure 佇列 <CONNECTION_NAME_PREFIX>__serviceUri 您要連接之服務的資料平面 URI。
完整命名空間 事件中樞,服務匯流排 <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace 完整的事件中樞和服務匯流排命名空間。
權杖認證 (選用) <CONNECTION_NAME_PREFIX>__credential 定義如何取得連接的權杖。 只有在指定使用者指派的身分識別時,才建議使用,其應設定為 "managedidentity"。 這只適用于裝載于 Azure Functions 服務時。
用戶端識別碼 (選用) <CONNECTION_NAME_PREFIX>__clientId credential 設為 "managedidentity" 時,這個屬性會指定取得權杖時要使用的使用者指派身分識別。 屬性會接受對應至指派給應用程式之使用者指派身分識別的用戶端識別碼。 如果未指定,將會使用系統指派的身分識別。 這個屬性在 本機開發案例中的使用方式不同, credential 不應該設定時。

1 Azure blob 需要 blob 和佇列服務 URI。

給定的連線類型可能支援其他選項。 請參閱建立連接元件的檔。

使用以身分識別為基礎的連接進行本機開發

在本機執行時,上述設定會指示執行時間使用您的本機開發人員身分識別。 連接將嘗試從下列位置取得權杖,順序如下:

  • Microsoft 應用程式之間共用的本機快取
  • Visual Studio 中的目前使用者內容
  • Visual Studio Code 中的目前使用者內容
  • Azure CLI 中的目前使用者內容

如果這些選項都沒有成功,將會發生錯誤。

在某些情況下,您可能會想要指定使用不同的身分識別。 您可以新增指向替代身分識別之連接的設定屬性。

注意

在 Azure Functions 服務中裝載時,不支援下列設定選項。

若要使用 Azure Active Directory 服務主體與用戶端識別碼和密碼進行連接,請除了上述連接屬性之外,還可以使用下列必要屬性來定義連接:

屬性 環境變數 描述
租用戶識別碼 <CONNECTION_NAME_PREFIX>__tenantId Azure Active Directory 租使用者 (Directory) 識別碼。
用戶端識別碼 <CONNECTION_NAME_PREFIX>__clientId 用戶端 (應用程式在租使用者中註冊應用程式) 識別碼。
用戶端密碼 <CONNECTION_NAME_PREFIX>__clientSecret 針對應用程式註冊所產生的用戶端密碼。

local.settings.json使用 Azure Blob 進行以身分識別為基礎的連線所需的屬性範例:

{
  "IsEncrypted": false,
  "Values": {
    "<CONNECTION_NAME_PREFIX>__serviceUri": "<serviceUri>",
    "<CONNECTION_NAME_PREFIX>__tenantId": "<tenantId>",
    "<CONNECTION_NAME_PREFIX>__clientId": "<clientId>",
    "<CONNECTION_NAME_PREFIX>__clientSecret": "<clientSecret>"
  }
}

使用身分識別連接到主機儲存體

Azure Functions 預設會將 AzureWebJobsStorage 連接用於核心行為,例如協調計時器觸發程式的單一執行和預設的應用程式金鑰存放區。 您也可以將此設定為利用身分識別。

警告

有些應用程式會 AzureWebJobsStorage 在其觸發程式、系結和/或函式程式碼中重複使用儲存連接。 在 AzureWebJobsStorage 從連接字串變更此連接之前,請確定的所有使用都能夠使用以身分識別為基礎的連接格式。

若要以這種方式設定連線,請確定應用程式的身分識別具有儲存體 Blob 資料擁有者角色,才能支援核心主機功能。 如果您使用 "AzureWebJobsStorage" 做為其他用途,您可能需要額外的許可權。

如果使用的儲存體帳戶使用全域 Azure 的預設 DNS 尾碼和服務名稱,請依照下列 https://<accountName>.blob/queue/file/table.core.windows.net 格式,將設定 AzureWebJobsStorage__accountName 為您的儲存體帳戶名稱。

如果改為在主權雲端或自訂 DNS 中使用儲存體帳戶,請將設定 AzureWebJobsStorage__serviceUri 為 blob 服務的 URI。 如果 "AzureWebJobsStorage" 將用於任何其他服務,您可以改為指定 AzureWebJobsStorage__blobServiceUriAzureWebJobsStorage__queueServiceUriAzureWebJobsStorage__tableServiceUri

報告問題

項目 描述 連結
執行階段 Script Host、觸發程序和繫結、語言支援 提出問題
範本 建立範本的程式碼問題 提出問題
入口網站 使用者介面或經驗問題 提出問題

後續步驟

如需詳細資訊,請參閱下列資源: