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 字串 表示繫結用於將資料接收到函數,還是從函數傳送資料。
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
Azure SQL (預覽)
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 服務中執行時,應用程式設定可能會設定這些環境變數,或在本機開發時從本機設定檔案設定。

連接值

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

但連接名稱也可以參考多個設定項目,在設定識別型連線會很有用處。 您可以使用以雙底線 __ 結尾的共用前置詞,將環境變數當作集合。 接著,可以將連接名稱設定為這個前置詞來參考群組。

例如,Azure Blob 觸發程序定義的 connection 屬性可能為 "Storage1"。 只要沒有名為 "Storage1" 環境變數所設定的單一字串值,就名為 Storage1__blobServiceUri 的環境變數就可用來通知連線的 blobServiceUri 屬性。 每個服務的連接屬性不同。 關於使用連線的元件,請參閱文件。

注意

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

例如:Storage1:blobServiceUri

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

Azure Functions 中的部分連接可設定為使用身分識別,而非秘密。 支援取決於使用連接的延伸模組。 在某些情況下,即使您連接的服務支援以身分識別為基礎的連接,Functions 中仍可能需要連接字串。 如需使用受控識別設定函式應用程式的教學課程,請參閱使用身分識別型連線建立函式應用程式的教學課程

下列元件支援身分識別型連線:

連線來源 支援的方案 深入瞭解
Azure Blob 觸發程序和繫結 All 延伸模組版本 5.0.0 或更新的版本
Azure 佇列觸發程序和繫結 All 延伸模組版本 5.0.0 或更新的版本
Azure 事件中樞觸發程序和繫結 All 延伸模組版本 5.0.0 或更新的版本
Azure 服務匯流排觸發程序和繫結 All 延伸模組版本 5.0.0 或更新的版本
Azure Cosmos DB 觸發程序和繫結 - 預覽 彈性進階 延伸模組版本 4.0.0-preview1 或更新的版本
Azure 資料表 (使用 Azure 儲存體時) - 預覽 All 資料表 API 延伸模組
Durable Functions 儲存體提供者 (Azure 儲存體) - 預覽 All 延伸模組版本 2.7.0 或更新的版本
主機必要儲存體 ("AzureWebJobsStorage") - 預覽 All 使用身分識別連線到主機儲存體

主控於 Azure Functions 服務時,以身分識別為基礎的連接會使用受控識別。 雖然可以使用 credentialclientID 屬性指定使用者指派的身分識別,但預設會使用系統指派的身分識別。 請注意,支援以資源識別碼來設定使用者指派的身分識別。 在本機開發等其他環境中執行時,但是會改用您的開發人員身分識別,雖然這可以自訂。 請參閱使用身分識別型連線進行本機開發

授與權限給身分識別

正在使用的任何身分識別,都必須具有執行預期動作的權限。 您需要使用提供這些權限的內建或自訂角色,在 Azure RBAC 中指派角色

重要

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

選擇下方的索引標籤,以了解每個元件的權限:

您必須建立可在執行時間存取 Blob 容器的角色指派。 擁有者等的管理角色不足。 下表顯示通常作業中使用 Blob 儲存體延伸模組時建議的內建角色。 您的應用程式可能會根據您寫入的程式碼要求額外的權限。

繫結類型 內建角色範例
觸發程序 儲存體 Blob 資料擁有者儲存體佇列資料參與者1

也必須授與其他權限給 AzureWebJobsStorage 連線。2
輸入繫結 儲存體 Blob 資料讀者
輸出繫結 儲存體 Blob 資料擁有者

1 Blob 觸發程序會藉由將有害 Blob 寫入儲存體帳戶中由連線所指定的佇列,來處理多個重試失敗。

2 AzureWebJobsStorage 連線是在內部用於啟用觸發程序的 Blob 和佇列。 如果設定成使用身分識別型連線,則需要超出預設需求的額外權限。 這些是由儲存體 Blob 資料擁有者儲存體佇列資料參與者儲存體帳戶參與者的角色所涵蓋。 如需深入了解,請參閱使用身分識別連線到主機儲存體

身分識別型連線的通用屬性

Azure 服務的身分識別型連線接受下列通用屬性,其中 <CONNECTION_NAME_PREFIX> 是觸發程序或繫結定義中 connection 屬性的值:

屬性 環境變數範本 描述
權杖認證 <CONNECTION_NAME_PREFIX>__credential 定義如何為連線取得權杖。 只有在指定使用者指派的身分識別時,才建議使用,而應該設定為 "managedidentity"。 只有在裝載於 Azure Functions 服務時才有效。
用戶端識別碼 <CONNECTION_NAME_PREFIX>__clientId credential 設定為 "managedidentity" 時 ,這個屬性會指定在取得權杖時要使用的使用者指派身分識別。 屬性接受的用戶端識別碼,對應至指派給應用程式的使用者指派身分識別。 如果沒有指定,則會使用系統指派的身分識別。 不應該設定 credential 時,這個屬性會以不同的方式用於本機開發案例

指定連線類型可能支援其他選項。 關於執行連線的元件,請參閱文件。

使用身分識別型連線進行區域開發

注意

使用身分識別型連線的本機開發需要更新版本的 Azure Functions Core Tools。 您可以執行 func -v 來檢查您目前安裝的版本。 針對 Functions v3,請使用 3.0.3904 版本或更新的版本。 針對 Functions v4,請使用 4.0.3904 版本或更新的版本。

在本機執行時,上述組態會告知執行時間,來使用您的本機開發人員身分識別。 連線將依序嘗試從下列位置取得權杖:

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

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

您的身分識別可能已經針對用於開發的 Azure 資源進行一些角色指派,但那些角色可能無法提供必要的資料存取權。 擁有者等的管理角色不足。 請仔細檢查每個元件連線所需的權限,並確定您已將元件指派給自己。

在某些情況下,您可能想要指定使用不同的身分識別。 您可以根據 Azure Active Directory 服務主體的用戶端識別碼與用戶端密碼,為指向替代身分識別的連線新增組態屬性。 裝載於 Azure Functions 服務時,不支援此組態選項。 若要在本機電腦上使用識別碼和密碼,請使用下列其他屬性定義連線:

屬性 環境變數範本 描述
租用戶識別碼 <CONNECTION_NAME_PREFIX>__tenantId Azure Active Directory 租用戶 (目錄) 識別碼。
用戶端識別碼 <CONNECTION_NAME_PREFIX>__clientId 租用戶中應用程式註冊的用戶端 (應用程式) 識別碼。
用戶端密碼 <CONNECTION_NAME_PREFIX>__clientSecret 為應用程式註冊產生的用戶端密碼。

以下是身分識別型 Azure Blob 連線所需的 local.settings.json 屬性範例:

{
  "IsEncrypted": false,
  "Values": {
    "<CONNECTION_NAME_PREFIX>__blobServiceUri": "<blobServiceUri>",
    "<CONNECTION_NAME_PREFIX>__queueServiceUri": "<queueServiceUri>",
    "<CONNECTION_NAME_PREFIX>__tenantId": "<tenantId>",
    "<CONNECTION_NAME_PREFIX>__clientId": "<clientId>",
    "<CONNECTION_NAME_PREFIX>__clientSecret": "<clientSecret>"
  }
}

使用身分識別連線到主機儲存體 (預覽)

Azure Functions 主機會針對核心行為使用 "AzureWebJobsStorage" 連線,例如協調計時器觸程序和預設應用程式金鑰儲存體的單一資料庫。 這也可以設定成使用身分識別。

注意

Functions 中的其他元件依賴 "AzureWebJobsStorage" 作為預設行為。 如果您使用不支援這種連線類型的舊版延伸模組,則不應該將它移至身分識別型連線,包括 Azure Blob、事件中樞和 Durable Functions 的觸發程序和繫結。 同樣地,使用 Linux 使用量中的伺服器端組件時,AzureWebJobsStorage 會用於部署成品,而如果您啟用此功能,則必須透過外部部署套件進行部署。

此外,有些應用程式會針對觸發程序、繫結和/或函式程式碼中的其他儲存體連線重複使用 "AzureWebJobsStorage"。 請確定所有 "AzureWebJobsStorage" 的用途都能夠使用身分識別型連線格式,再從連接字串變更此連線。

若要使用 "AzureWebJobsStorage" 的身分識別型連線,請設定下列應用程式設定:

設定 描述 範例值
AzureWebJobsStorage__blobServiceUri 使用 HTTPS 配置儲存體帳戶之 Blob 服務的資料平面 URI。 https://<storage_account_name>.blob.core.windows.net
AzureWebJobsStorage__queueServiceUri 使用 HTTPS 配置儲存體帳戶之佇列服務的資料平面 URI。 https://<storage_account_name>.queue.core.windows.net
AzureWebJobsStorage__tableServiceUri 使用 HTTPS 配置儲存體帳戶之資料表服務的資料平面 URI。 https://<storage_account_name>.table.core.windows.net

身分識別型連線的通用屬性也能進行設定。

如果您要使用使用全域 Azure 的預設 DNS 尾碼和服務名稱的儲存體帳戶來設定 "AzureWebJobsStorage",請遵循 https://<accountName>.blob/queue/file/table.core.windows.net 格式,改為設定 AzureWebJobsStorage__accountName 為儲存體帳戶的名稱。 系統會針對此帳戶推斷每個儲存體服務的端點。 如果儲存體帳戶位於主權雲端或具有自訂 DNS,將無法運作。

設定 描述 範例值
AzureWebJobsStorage__accountName 儲存體帳戶的帳戶名稱,只有在帳戶不在主權雲端中且沒有自訂 DNS 時才有效。 此語法獨屬於 "AzureWebJobsStorage" ,無法用於其他身分識別型連線。 <storage_account_name>

您必須建立角色指派,以在執行時間存取 "AzureWebJobsStorage" 的儲存體帳戶。 擁有者等的管理角色不足。 儲存體 Blob 資料擁有者角色涵蓋 Functions 主機儲存體的基本需求 - 執行時間需要 Blob 的讀取和寫入存取權,以及建立容器的能力。 數個延伸模組會使用此連線做為 Blob、佇列和資料表的預設位置,而這些延伸模組可能會新增下表中所述的需求。 針對,如果您使用"AzureWebJobsStorage" 做為任何其他用途,您可能需要額外的權限。

分機 需要的角色 說明
沒有延伸模組 (僅限主機) 儲存體 Blob 資料擁有者 用於一般協調、預設金鑰存放區
Azure Blob (僅限觸發程序) 所有:
儲存體帳戶參與者
儲存體 Blob 資料擁有者
儲存體佇列資料參與者
Blob 觸發程序會在內部使用 Azure 佇列,並寫入 Blob 收據。 無論觸發程式設定的連線為何,都會針對這些使用 AzureWebJobsStorage。
Azure 事件中樞 (僅限觸發程序) (預設需求沒有任何變更)
儲存體 Blob 資料擁有者
檢查點會使用 AzureWebJobsStorage 連線維持在 Blob 中。
計時器觸發程序 (預設需求沒有任何變更)
儲存體 Blob 資料擁有者
為了確保每個事件只有一個執行,會使用 AzureWebJobsStorage 連線鎖定 Blob。
Durable Functions 所有:
儲存體 Blob 資料參與者
儲存體佇列資料參與者
儲存體資料表資料參與者
Durable Functions 會使用 Blob、佇列和資料表來協調活動函式,並維護協調流程狀態。 根據籲社會針對所有這些項目使用 AzureWebJobsStorage 連線,但您可以在 Durable Functions 延伸模組組態中指定不同的連線。

報告問題

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

後續步驟

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