使用動態會話於 Azure 容器應用程式中

Azure 容器應用程式動態sessions提供隔離且安全的上下文，當你需要將程式碼或應用程式與其他工作負載分開執行時。會話會在會話集區內執行，以立即存取新的和現有的會話。這些會話非常適合在需以受控制方式處理用戶產生的輸入，或整合需在隔離環境中執行程式碼的第三方服務時使用。你不需要部署容器應用程式資源來使用動態會話，建立會話池並呼叫其管理 API。

這篇文章教您如何管理並與動態會話互動。

管理端點與路由

您的應用程式會使用工作階段集區的管理 API 與工作階段互動。關於請求路由的概念概述，請參閱關鍵概念。

要取得會話池管理端點，請參見會話池管理端點。

https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io

欲了解更多管理會話池的資訊，請參閱會話池管理端點。

管理 API 認證與授權

所有對會話池管理 API 的請求都需要透過 Microsoft Entra 令牌進行認證（AuthN）及授權（AuthZ），並透過會話池上的 Azure ContainerApps Session Executor 角色進行授權。詳情與範例請參見認證與授權。

向會話發送請求

若要將要求傳送至會話的容器，您可以使用管理端點作為要求的根目錄。在基礎集區管理端點之後路徑中的任何內容都會轉送至工作階段的容器。

例如，若您呼叫<POOL_MANAGEMENT_ENDPOINT>/api/uploadfile，該請求會被路由至目標埠<TARGET_PORT>/api/uploadfile的會話容器。

範例要求

以下範例說明如何使用使用者 ID 作為唯一會話識別碼向會話發送請求。

在傳送要求之前，請將 <> 這些括號中的佔位符替換為您要求特有的值。

POST <POOL_MANAGEMENT_ENDPOINT>/<API_PATH_EXPOSED_BY_CONTAINER>?identifier=<USER_ID>
Authorization: Bearer <TOKEN>
{
  "command": "echo 'Hello, world!'"
}

此要求會轉送至具有使用者 ID 識別碼的工作階段容器。

如果指定識別碼沒有現有工作階段，Azure 容器應用程式會在轉送要求前，自動從集區配置一個工作階段。

在此範例中，會話容器在目標埠 <TARGET_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>接收請求。

識別碼

若要將 HTTP 要求傳送至工作階段，您必須在要求中提供工作階段標識碼。當您對工作階段提出要求時，會在URL中名為 identifier 的查詢字串參數中傳遞工作階段識別碼。

如果具有此識別碼的會話已經存在，請求會被發送至現有的會話。
如果不存在具有該識別碼的工作階段，系統會在傳送要求之前自動配置新的工作階段。

下圖顯示會話池如何將請求路由至現有會話，或在需要時分配新會話。

圖示顯示會話池將請求路由至現有會話或根據識別碼建立新會話。

標識碼格式

工作階段識別碼是自由格式的字串，這表示您可以採取任何符合應用程式需求的方式加以定義。

會話識別碼是你定義的字串，在會話池中是唯一的。如果您要建置 Web 應用程式，您可以使用使用者的識別碼作為會話識別碼。如果您要建置聊天機器人，可以使用交談識別碼。

識別碼必須是長度為 4 到 128 個字元的字串，而且只能包含來自此清單的英數位元和特殊字元：|、-、&、^、%、$、#、(、)、{、}、[、]、;、< 和 >。

錯誤回應

當錯誤發生時，API 會回傳結構化錯誤回應，並提供詳細資料以協助你診斷問題。

{
  "error": {
    "code": "ErrorCode",
    "message": "Human-readable error description",
    "details": "Optional additional context",
    "target": "Field or parameter that caused the error",
    "traceId": "Request trace ID for debugging"
  }
}

常見的錯誤碼

錯誤碼	HTTP 狀態	說明	Resolution
`SessionWithIdentifierNotFound`	400	這個會話識別碼在這個會話池裡不存在	確認會話識別碼正確且會話沒有過期
`SessionRequestValidationFailed`	400	請求缺少必填欄位或參數無效	檢查查詢參數（識別碼、跳過、API 版本）格式是否正確
`SessionRequestNotSupported`	400	API 無法辨識請求類型	確認您正在使用受支援的 API 端點和方法
`InternalServerError`	500	伺服器端發生了意外錯誤	重新嘗試請求;如果錯誤持續，請檢查日誌中的traceId。

實務中的會話生命週期

當您持續對相同的工作階段進行呼叫時，該工作階段會持續在集區中配置。當冷卻期結束後，若會話中沒有任何要求，會話將自動終結。

備註

在少數情況下，如果工作階段背景的 TTL 延長要求失敗 (例如容器意外結束)，系統會自動將工作階段從集區中移除。你會在下一次請求該會話時看到「找不到會話」錯誤。此清理工作是自動進行的，您無需自行操作。

安全性

安全性模型

動態會話是用來在安全且隔離的環境中執行不受信任的程式代碼和應用程式。雖然工作階段彼此隔離，但單一工作階段內的任何項目，包括檔案和環境變數，都可由工作階段的使用者存取。

只有在您信任會話的使用者時，才設定或上傳敏感數據至會話。

網路存取

根據預設，會話被防止發出向外的網路請求。您可以透過在連線池中設定網路狀態來控制網路存取。

最佳做法

安全標識碼：隨時使用安全會話標識符。使用密碼編譯方法來產生會話標識符，以確保唯一且無法預測的值。避免使用攻擊者可能猜到的循序標識碼。
使用 HTTPS：一律使用 HTTPS 來加密傳輸中的數據。這可保護會話標識碼和客戶端與伺服器之間交換的任何敏感數據，避免遭到攔截。
限制工作階段存留時間：為工作階段實作逾時。例如，在會話自動終止之前，最多允許 15 分鐘的無活動。這有助於降低因設備遺失或無人看管所造成的風險。
限制會話可見度：設定嚴格的訪問控制，以確保會話標識碼只能在會話集區中看到。避免在 URL 或記錄中公開會話標識碼。
定期輪替會話認證：定期檢閱並更新與您的會話相關聯的認證。輪替可降低未經授權的存取風險。

自訂容器工作階段的其他指引

使用安全傳輸協定：傳輸中資料（包括會話識別碼）應始終使用 HTTPS 加密。這種方法能防止中間人攻擊。
監視會話活動：實作記錄和監視來追蹤會話活動。使用這些記錄來識別不尋常的模式或潛在的安全性缺口。
驗證使用者輸入：將所有使用者輸入視為危險。使用輸入驗證和衛生技術來防範插入式攻擊，並確保只會處理受信任的數據。

身份驗證與授權

當你透過池管理 API 向會話發送請求時，認證會使用 Microsoft Entra 令牌來處理。只有屬於工作階段集區上 Azure ContainerApps Session Executor 角色的身分所取得的 Microsoft Entra 權杖，才有權呼叫集區管理 API。

若要將角色指派給某個身份，請使用以下的 Azure 命令列介面指令：

az role assignment create \
    --role "Azure ContainerApps Session Executor" \
    --assignee <PRINCIPAL_ID> \
    --scope <SESSION_POOL_RESOURCE_ID>

如果你使用的是大型語言模型（LLM）框架整合，該框架會幫你處理代幣的產生和管理。請確保應用程式設定了具備受控識別，並在工作階段集區上具有必要角色指派。

如果您是直接使用池的管理 API 端點，則必須生成令牌，並將其包含在 HTTP 請求的 Authorization 標頭中。除了前述的角色指派外，代幣還需包含一個受眾（aud）主張，其值為https://dynamicsessions.io。

要使用 Azure CLI 產生 token，請執行以下指令：

az account get-access-token --resource https://dynamicsessions.io

在 C# 裡，你可以用 Azure.Identity 函式庫來產生一個標記。首先，安裝程式庫：

dotnet add package Azure.Identity

然後，使用下列程式碼來產生 token:

using Azure.Identity;

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://dynamicsessions.io/.default" }));
var accessToken = token.Token;

在 JavaScript 中，您可以使用 @azure/identity 程式庫來產生權杖。首先，安裝程式庫：

npm install @azure/identity

然後，使用下列程式碼來產生 token:

const { DefaultAzureCredential } = require("@azure/identity");
const { TokenCredential } = require("@azure/core-auth");

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://dynamicsessions.io/.default");
const accessToken = token.token;

在 Python 中，你可以使用 azure-identity 函式庫來產生一個標記。首先，安裝程式庫：

pip install azure-identity

然後，使用下列程式碼來產生 token:

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://dynamicsessions.io/.default")
access_token = token.token

這很重要

有效的權杖可用於在集區中建立及存取任何工作階段。請保持您的令牌安全，並不要與未受信任的對方分享。終端用戶絕對不應該有令牌的直接存取權。只讓令牌可供應用程式使用，且永遠不會提供給終端使用者。

保護會話標識碼

會話標識碼是您必須安全地管理的敏感性資訊。您的應用程式需要確保每個使用者或租用戶只能存取自己的工作階段。

防止濫用工作階段識別碼的特定策略會有所不同，取決於應用程式的設計和架構。不過，您的應用程式必須一律完全控制工作階段識別碼的建立和使用，以便惡意使用者無法存取其他使用者的工作階段。

範例策略包括：

每個使用者一個工作階段：如果您的應用程式使用每個使用者一個工作階段，則必須安全地驗證每個使用者，而且您的應用程式必須針對每個登入的使用者使用唯一的工作階段識別碼。
每個代理程式交談一個工作階段：如果您的應用程式針對每個 AI 代理程式交談使用一個工作階段，請確定您的應用程式針對使用者無法修改的每個交談使用唯一工作階段識別碼。

這很重要

無法保護會話存取的安全，可能會導致濫用或未經授權存取儲存在您用戶會話中的數據。

使用受控識別

來自 Microsoft Entra ID 的受管理的身份允許您的容器會話池及其會話存取其他由 Microsoft Entra 保護的資源。工作階段集區支援系統指派與使用者指派的受控識別。

欲了解更多有關 Microsoft Entra ID 中的受管理身分資訊，請參閱 Managed identities for Azure resources。

有兩種方式可以搭配自定義容器會話集區使用受控識別：

映射提取驗證：使用受控識別向容器登錄進行驗證，以提取容器映射。
Resource access：在會話中使用會話池的管理身份來存取其他Microsoft Entra受保護的資源。由於其安全性影響，預設會停用此功能。

這很重要

如果你在會話中啟用了對受管理身份的存取權限，任何在會話中執行的程式碼或程式都可以為該池的受管理身份建立 Microsoft Entra 令牌。由於會話通常會執行不受信任的程序代碼，因此請謹慎使用此功能。

Azure CLI
Azure Resource Manager

若要啟用自訂容器會話池的管理身份，請使用 Azure Resource Manager。

若要啟用自定義容器會話集區的受控識別，您可以將屬性新增 identity 至會話集區資源。

屬性 identity 必須包含一個具備值 type 或 SystemAssigned 的屬性 UserAssigned。如需如何設定此屬性的詳細資訊，請參閱設定受控識別。

下列範例顯示 ARM 範本代碼段，可針對自訂容器會話集區啟用使用者指派的身分識別，並將其用於映像提取驗證。

在傳送要求之前，請將 <> 括弧之間的預留位置替換為會話池和會話識別碼的適當值。

{
  "type": "Microsoft.App/sessionPools",
  "apiVersion": "2024-08-02-preview",
  "name": "my-session-pool",
  "location": "westus2",
  "properties": {
    "environmentId": "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>",
    "poolManagementType": "Dynamic",
    "containerType": "CustomContainer",
    "scaleConfiguration": {
      "maxConcurrentSessions": 10,
      "readySessionInstances": 5
    },
    "dynamicPoolConfiguration": {
      "executionType": "Timed",
      "cooldownPeriodInSeconds": 600
    },
    "customContainerTemplate": {
      "registryCredentials": {
          "server": "myregistry.azurecr.io",
          "identity": "<IDENTITY_RESOURCE_ID>"
      },
      "containers": [
        {
          "image": "myregistry.azurecr.io/my-container-image:1.0",
          "name": "mycontainer",
          "resources": {
            "cpu": 0.25,
            "memory": "0.5Gi"
          },
          "command": [
            "/bin/sh"
          ],
          "args": [
            "-c",
            "while true; do echo hello; sleep 10;done"
          ],
          "env": [
            {
              "name": "key1",
              "value": "value1"
            },
            {
              "name": "key2",
              "value": "value2"
            }
          ]
        }
      ],
      "ingress": {
        "targetPort": 80
      }
    },
    "sessionNetworkConfiguration": {
      "status": "EgressEnabled"
    },
    "managedIdentitySettings": [
      {
        "identity": "<IDENTITY_RESOURCE_ID>",
        "lifecycle": "None"
      }
    ]
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "<IDENTITY_RESOURCE_ID>": {}
    }
  }
}

此樣本包含下列受控識別的設定：

參數	價值觀	說明
`customContainerTemplate.registryCredentials.identity`	`<IDENTITY_RESOURCE_ID>`	用於映像提取驗證的受控識別資源識別碼。
`managedIdentitySettings.identity`	`<IDENTITY_RESOURCE_ID>`	用於工作階段中的受控識別資源識別碼。
`managedIdentitySettings.lifecycle`	`None`	可使用受控識別的工作階段生命週期。 - `None` （預設值）：會話無法存取身分識別。此設定僅用於映像提取。 - `Main`：除了映像提取之外，主要工作階段也可以存取該身分。請小心使用。

森林伐木業

Azure 容器應用程式動態會話整合 Azure 監視器和 Log Analytics，以收集會話執行期間產生的日誌。程式碼直譯器和自訂容器會話池的設定步驟相同，但可用的日誌類別會依會話類型而異。透過 API 回應標頭回傳的指標不會寫入 Log Analytics。

依工作階段類型而異的記錄差異

請參考以下指引比較記錄行為，並跳到符合您會話類型的相關細節：

Code 直譯器會話：執行時會回傳輸出（包括 stdout 和 stderr），但不會輸出 AppEnvSession Log Analytics 表。請參閱程式碼解譯器會話記錄。
自訂容器工作階段：當您的容器寫入 stdout 或 stderr 時，AppEnvSession Log Analytics 資料表就會發出，而且平台記錄可用於集區生命週期和事件。請參見自訂容器會話記錄。
Common：透過 API 回應標頭回傳的指標不會寫入 Log Analytics。

欲了解環境資源（Microsoft.App/managedEnvironments）上支援的會話類別完整列表，請參見支援日誌Microsoft。App/managedEnvironments。

工作階段類型：瞭解不同類型的動態工作階段：
- 代碼解譯器會話
- 自訂容器會話
教學課程：直接使用 REST API 或透過 LLM Agent：
- 使用 LLM 代理程式：
- 使用 REST API
  - JavaScript 程式代碼解釋器

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-05-10

使用動態會話於 Azure 容器應用程式 中

管理端點與路由

管理 API 認證與授權

向會話發送請求

範例要求

識別碼

標識碼格式

錯誤回應

常見的錯誤碼

實務中的會話生命週期

安全性

安全性模型

網路存取

最佳做法

自訂容器工作階段的其他指引

身份驗證與授權

保護會話標識碼

使用受控識別

森林伐木業

依工作階段類型而異的記錄差異

相關內容

意見反應

其他資源

使用動態會話於 Azure 容器應用程式中