教學：使用 Azure Container Apps 在會話池中執行 shell 指令（預覽版）

本教學示範如何在 Azure 容器應用程式中部署 shell 會話池，並使用 Dynamic Sessions API 和 ARM 範本執行 shell 指令。

在本教學課程中，您會：

  • 使用 ARM 範本部署 shell 會話池
  • 建立一個由使用者指派且擁有適當權限的管理身份
  • 透過動態會話 API 執行 shell 指令

先決條件

開始本教學課程之前，您需要下列資源。

Requirement Description
Azure 帳戶 您需要具有有效訂用帳戶的 Azure 帳戶。 如果您沒有帳戶，您可以 免費建立一個。
Azure CLI 安裝 Azure CLI。

設定

首先將 Azure CLI 更新到最新版本，然後登入 Azure。

  1. 將 Azure CLI 更新為最新版本。

    az upgrade

  2. 註冊 Microsoft.App 資源提供者。

    az provider register --namespace Microsoft.App

  3. 安裝最新版的 Azure 容器應用程式 CLI 延伸模組。

    az extension add --name containerapp --allow-preview true --upgrade

  4. 登入 Azure。

    az login

  5. 查詢您的 Azure 訂用帳戶識別碼，並將值設定為變數。

    SUBSCRIPTION_ID=$(az account show --query id --output tsv)

  6. 設定此程序中使用的變數。

    執行下列命令之前，請務必將 <> 所括住的預留位置以您自己的值取代。

    RESOURCE_GROUP=<RESOURCE_GROUP_NAME>
SESSION_POOL_NAME=<SESSION_POOL_NAME>
LOCATION=<LOCATION>
API_VERSION="2025-10-02-preview"

    您可以使用這些變數，在下列步驟中建立資源。

  7. 設定你想用來建立資源群組的訂閱方式。

    az account set -s $SUBSCRIPTION_ID

  8. 建立資源群組。

    az group create --name $RESOURCE_GROUP --location $LOCATION

建立 ARM 範本

建立一個名為 deploy.json ARM 的範本檔案來定義你的 shell 會話池。

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "resources": [
      {
         "apiVersion": "2025-10-02-preview",
            "name": "myshellpool",
            "type": "Microsoft.App/sessionpools",
            "location": "North Central US",
            "properties": {
                "poolManagementType": "Dynamic",
                "containerType": "Shell", # Set the "containerType" property to "Shell"
                "scaleConfiguration": {
                    "maxConcurrentSessions": 5
                },
                "dynamicPoolConfiguration": {
                    "lifecycleConfiguration": {
                        "lifecycleType": "Timed",
                        "cooldownPeriodInSeconds": 300
                    }
                },
                "sessionNetworkConfiguration": {
                    "status": "EgressEnabled"
                }
            }
        }
    ]
}

部署 shell 會話池

使用 ARM 範本來部署你的 shell session 池。

az deployment group create --resource-group $RESOURCE_GROUP --template-file deploy.json

指派受控識別

建立一個使用者指派的受控識別，用於驗證 API 呼叫工作階段集區。

  1. 設定身份名稱和資源池 ID。

    UAMI_NAME=${SESSION_POOL_NAME}-uami
POOL_ID="/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionpools/$SESSION_POOL_NAME"

  2. 建立使用者指派的受管理身分識別。

    az identity create --resource-group $RESOURCE_GROUP --name $UAMI_NAME --location $LOCATION

  3. 取得受控識別的主體識別碼。

    UAMI_PRINCIPAL=$(az identity show --resource-group $RESOURCE_GROUP --name $UAMI_NAME --query principalId -o tsv)

將管理身份指派給你的 Azure 容器應用程式

建立或更新 Azure 容器應用程式時，請將使用者指定的管理身份指派給應用程式。 例如：

az containerapp update \
  --name <CONTAINER_APP_NAME> \
  --resource-group $RESOURCE_GROUP \
  --user-assigned $UAMI_NAME

詳情請參閱 「為容器應用程式指派受管理身份 」。

為會話執行 API 設定角色指派

要與會話池的 API 互動，您必須將 Azure ContainerApps Session Executor 角色指派給您的管理身份。

等待身分識別傳播，然後將角色指派給受控識別。

az role assignment create --assignee $UAMI_PRINCIPAL --role "Azure ContainerApps Session Executor" --scope $POOL_ID

取得持有人權杖

要存取會話池的 API，你需要一個存取令牌。 方法取決於你執行程式碼的地點：

從您的 Azure 容器應用程式內部

從已指派使用者指派的受控識別的 Azure 容器應用程式執行時，請使用 Azure Instance Metadata Service (IMDS) 取得存取權杖：

ACCESS_TOKEN=$(curl -s -H "Metadata: true" \
  "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://dynamicsessions.io" \
  | jq -r '.access_token')

此指令會取得令牌，並利用 access_token從 JSON 回應中提取jq值。

用於本地測試與開發

在本地或開發環境中測試時，您可以使用 Azure CLI 取得存取權杖（必須具備相應權限）：

ACCESS_TOKEN=$(az account get-access-token --resource "https://dynamicsessions.io" --query accessToken --output tsv)

備註

為了讓本機測試正常運作，您的 Azure CLI 工作階段必須認證為擁有「Azure ContainerApps Session Executor」角色，並指派至工作階段集區的使用者或服務主體。 管理身份方法建議用於生產場景。

在您的工作階段中執行 shell 命令

現在您有持有人權杖可建立資訊安全內容，可以向工作階段集區傳送請求來執行 shell 命令。

  1. 建立 API 呼叫的請求主體。

    EXEC_ID=$(uuidgen)
BODY=$(cat <<EOF
 {
   "codeInputType": "inline",
   "executionType": "synchronous",
   "shellCommand": "echo Hello world!",
   "timeoutInSeconds": 600
 }
 EOF
 )

  2. 建構 API 端點的 URL。

    URL="https://$LOCATION.dynamicsessions.io/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/sessionPools/$SESSION_POOL_NAME/executions?api-version=$API_VERSION&identifier=$EXEC_ID"

  3. 執行 shell 指令。

    在 Azure 容器應用程式內或進行本地測試時：

    curl --request POST --url "$URL" --header "Authorization: Bearer $ACCESS_TOKEN" --header 'content-type: application/json' --data "$BODY"

    你應該會收到包含執行結果的 JSON 回應，包括 shell 指令（hello world 和 hi）的輸出。

確認您的部署

您可以使用以下指令驗證您的資源是否已成功建立：

  1. 確認會話池的部署。

    az resource show --ids "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionpools/$SESSION_POOL_NAME" --query '{name:name, location:location, provisioningState:properties.provisioningState}'

  2. 確認角色分配。

    az role assignment list --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionpools/$SESSION_POOL_NAME" --output table

清理資源

本教學課程中建立的資源會影響您的 Azure 帳單。 如果您不會長期使用這些服務，請執行下列命令來刪除本教學課程中建立的所有內容。

az group delete --resource-group $RESOURCE_GROUP

後續步驟

  • Last updated on