你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure 容器应用中的无服务器代码解释器会话

Azure 容器应用动态会话提供对代码解释器的快速且可缩放的访问。每个代码解释器会话均按 Hyper-V 边界完全隔离，旨在运行不受信任的代码。

用于代码解释器会话

代码解释器会话非常适合在需要运行可能恶意代码或可能对主机系统或其他用户造成损害的场景，例如。

由大型语言模型 (LLM) 生成的代码。
最终用户在 Web 或 SaaS 应用程序中提交的代码。

对于常用的 LLM 框架（如 LangChain、LlamaIndex 和语义内核），可以使用工具和插件将 AI 应用与代码解释器会话集成。

应用程序还可以使用 REST API 与代码解释器会话集成。 API 使你能够：

在会话中运行代码并检索结果。
上传文件到会话并从会话下载文件。

可以上传和下载代码可以处理的可执行代码文件或数据文件。

内置代码解释器会话支持最常见的代码执行方案，而无需管理基础结构或容器。

如果需要完全控制代码执行环境或有需要隔离沙盒的不同场景，则可以使用自定义代码解释器会话。

代码解释器会话池

若要使用代码解释器会话，需要一个名为会话池的 Azure 资源，用于定义代码解释器会话的配置。

在会话池中，可以指定设置，例如最大并发会话数，以及会话在会话停止前可以空闲多长时间。

可以使用 Azure 门户、Azure CLI 或 Azure 资源管理器模板创建会话池。创建会话池后，可以使用池的管理 API 终结点在会话中管理和运行代码。

有关如何创建和配置会话池的详细信息，请参阅 “使用会话池”。

会话中的代码执行

创建会话池后，应用程序可以使用与 LLM 框架的集成或直接使用池的管理 API 终结点与池中的会话进行交互。

会话标识符

重要说明

会话标识符是敏感信息。需要用安全的方法来管理其价值。此过程的一部分是确保应用程序确保每个用户或租户仅有权访问自己的会话。

无法保护对会话的访问可能会导致滥用或未经授权的访问存储在用户会话中的数据。有关详细信息，请参阅会话标识符。

与池中的会话交互时，使用会话标识符引用每个会话。会话标识符是在会话池中定义的唯一字符串。如果你正在生成 Web 应用程序，则可以使用用户的 ID。如果你正在生成聊天机器人，则可以使用对话 ID。

如果正在运行带标识符的会话，则将重用该会话。如果未运行带标识符的会话，则会自动创建新会话。

身份验证

身份验证通过 Microsoft Entra 令牌进行处理。有效的 Microsoft Entra 令牌由属于会话池上的“Azure 容器应用会话执行者”和“参与者”角色的标识生成。

如果使用 LLM 框架集成，该框架会为你处理令牌生成和管理。确保为应用程序配置了托管标识，并在会话池中对其进行了所需的角色分配。

如果直接使用池的管理 API 终结点，则必须生成令牌并将其包含在 HTTP 请求的 Authorization 标头中。除了前面提到的角色分配外，令牌还需要包含受众 (aud) 声明，其值为 https://dynamicsessions.io。

有关详细信息，请参阅身份验证和授权。

使用文件

可以上传和下载文件，并列出代码解释器会话中的所有文件。

支持的字符

文件名和路径只能使用以下受支持的字符：

大写字母和小写字母： A-Z， a-z。
数字：0-9。
特殊字符：-、、_ 、.@$&=;,#、%、^、、.。 () （路径不能包含 .。）
Unicode 字符：包括中文、日语和其他国际字符。

上传文件

若要将文件上传到会话，请在多部分表单数据请求中向 POST 终结点发送 files 请求。将文件数据包含在请求正文中。该文件必须包含文件名。

上传的文件存储在会话的文件系统中的 /mnt/data 目录中。

以下示例演示如何将文件上传到会话。

在发送请求之前，请将括号之间的 <> 占位符替换为特定于请求的值。

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer <TOKEN>

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="<FILE_NAME_AND_EXTENSION>"
Content-Type: application/octet-stream

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

下载文件

若要从会话的 /mnt/data 目录下载文件，请向 GET 终结点发送 files/{filename}/content 请求。响应包含文件数据。

以下示例演示如何设置请求的格式 GET 以下载文件。

在发送请求之前，请将括号之间的 <> 占位符替换为特定于请求的值。

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/<FILE_NAME_AND_EXTENSION>/content?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

获取文件元数据

若要获取会话/mnt/data目录中文件的元数据，请向GET终结点发送files/{filename}请求。响应包括文件属性，例如大小和上次修改时间。

以下示例演示如何设置请求的格式 GET 以检索文件元数据。

在发送请求之前，请将括号之间的 <> 占位符替换为特定于请求的值。

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/<FILE_NAME_AND_EXTENSION>?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

列出文件

若要列出会话的 /mnt/data 目录中的文件，请向 GET 终结点发送 files 请求。

以下示例演示如何列出会话目录中的文件。

在发送请求之前，请将括号之间的 <> 占位符替换为特定于请求的值。

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

响应包含会话中文件的列表。

以下列表显示了请求会话内容时预期的响应类型示例。

{
    "$id": "1",
    "value": [
        {
            "$id": "2",
            "properties": {
                "$id": "3",
                "filename": "test1.txt",
                "size": 16,
                "lastModifiedTime": "2024-05-02T07:21:07.9922617Z"
            }
        },
        {
            "$id": "4",
            "properties": {
                "$id": "5",
                "filename": "test2.txt",
                "size": 17,
                "lastModifiedTime": "2024-05-02T07:21:08.8802793Z"
            }
        }
    ]
}

安全性

代码解释器会话旨在在隔离环境中运行不受信任的代码，以确保应用程序和数据保持受保护。

LLM 框架集成

可以使用以下 LLM 框架来提供与代码解释器会话的集成，而不是直接使用会话池管理 API。

Framework	程序包	教程
LangChain	Python： `langchain-azure-dynamic-sessions`	教程。
LlamaIndex	Python： `llama-index-tools-azure-code-interpreter`	教程。
语义内核	Python：`semantic-kernel`（版本 0.9.8-b1 或更高版本）	教程。

管理 API 终结点

如果不使用 LLM 框架集成，则可以使用管理 API 终结点直接与会话池交互。

在会话中运行代码

要在会话中运行代码，请向 POST 终结点发送 executions 请求，并在请求正文中包含要运行的代码。每个代码执行限制为 220 秒的最大运行时。

以下示例在 Python 中打印 Hello, world! 。

在发送请求之前，请将 <> 括号之间的占位符替换为适合你的会话池和会话标识符的值。

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/executions?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <TOKEN>

{
    "properties": {
        "codeInputType": "inline",
        "executionType": "synchronous",
        "code": "print('Hello, world!')"
    }
}

若要重用会话，请在后续请求中指定相同的会话标识符。

将文件上传到会话

若要将文件上传到会话，请在多部分表单数据请求中向 POST 终结点发送 files 请求。将文件数据包含在请求正文中。该文件必须包含文件名。

上传的文件存储在会话的文件系统中的 /mnt/data 目录中。

在发送请求之前，请将括号之间的 <> 占位符替换为特定于请求的值。

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer <TOKEN>

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="<FILE_NAME_AND_EXTENSION>"
Content-Type: application/octet-stream

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

注意

文件上传限制为 128 MB。如果超出此限制，可能会收到 HTTP 413 错误。

从会话下载文件

若要从会话的 /mnt/data 目录下载文件，请向 GET 终结点发送 files/{filename}/content 请求。响应包含文件数据。

在发送请求之前，请将括号之间的 <> 占位符替换为特定于请求的值。

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/<FILE_NAME_AND_EXTENSION>/content?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

获取文件元数据

若要获取会话/mnt/data目录中文件的元数据，请向GET终结点发送files/{filename}请求。响应包括文件属性，例如大小和上次修改时间。

在发送请求之前，请将括号之间的 <> 占位符替换为特定于请求的值。

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/<FILE_NAME_AND_EXTENSION>?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

列出会话中的文件

若要列出会话的 /mnt/data 目录中的文件，请向 GET 终结点发送 files 请求。

在发送请求之前，请将括号之间的 <> 占位符替换为特定于请求的值。

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

响应包含会话中的文件列表。

下面是请求会话内容时可以期望的响应类型的示例。

{
    "$id": "1",
    "value": [
        {
            "$id": "2",
            "properties": {
                "$id": "3",
                "filename": "test1.txt",
                "size": 16,
                "lastModifiedTime": "2024-05-02T07:21:07.9922617Z"
            }
        },
        {
            "$id": "4",
            "properties": {
                "$id": "5",
                "filename": "test2.txt",
                "size": 17,
                "lastModifiedTime": "2024-05-02T07:21:08.8802793Z"
            }
        }
    ]
}

删除会话

使用删除会话 API 终止代码解释器会话池中的会话。

分配会话后，可以调用此 API 以随时手动终止该 API。这在以下情况下非常有用：

在会话达到其生存时间之前，需要清理资源。
会话池已达到其最大并发会话限制，需要释放新会话的容量。
会话已完成其工作，希望立即释放资源。

API 参考

请求

DELETE <POOL_MANAGEMENT_ENDPOINT>/session?api-version=2025-02-02-preview&identifier=<SessionIdentifier>

参数

参数	类型	必需	Description
`api-version`	字符串	是的	要使用的 API 版本（例如 `2025-02-02-preview`，）。
`identifier`	字符串	是的	要停止的会话的唯一标识符。

示例

请求

DELETE <POOL_MANAGEMENT_ENDPOINT>/session?api-version=2025-02-02-preview&identifier=testSessionIdentifier

响应

HTTP/1.1 204 No Content

检索会话信息

可以查询会话池以检查会话状态、获取过期详细信息并列出所有活动会话。此功能可用于监视会话运行状况、跟踪资源使用情况和实现自定义清理工作流。

获取单个会话

若要检索有关特定会话的详细信息，请使用获取会话 API：

GET <POOL_MANAGEMENT_ENDPOINT>/session?identifier=<SessionIdentifier>&api-version=2025-02-02-preview

终结点 getSession 返回会话元数据，包括会话标识符、当前过期时间和创建时间戳。

SessionView 响应架构

领域	类型	必需	Description
`identifier`	字符串	是的	提供的会话标识符
`etag`	字符串	是的	会话的版本标识符不透明。可以使用此标识符进行更改检测。
`expiresAt`	DateTime	是的	会话终止时的 UTC 时间戳
`createdAt`	DateTime	No	会话创建时间戳
`lastAccessedAt`	DateTime	No	对此会话的最后一次请求的时间戳

示例请求和响应

curl -X GET "https://eastasia.dynamicsessions.io/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myrg/sessionPools/mysessionpool/session?identifier=user-123&api-version=2025-02-02-preview" \
  -H "Authorization: Bearer $TOKEN"

成功响应（HTTP 200）：

{
  "identifier": "user-123",
  "etag": "a1b2c3d4",
  "expiresAt": "2026-04-30T14:30:00Z",
  "createdAt": "2026-04-30T13:30:00Z",
  "lastAccessedAt": "2026-04-30T14:29:00Z"
}

列出池中的所有会话

若要检索会话池中所有会话的列表，请使用 listSessions 终结点：

GET <POOL_MANAGEMENT_ENDPOINT>/listSessions?skip=0&api-version=2025-02-02-preview
Authorization: Bearer <TOKEN>

分页

列表终结点支持基于跳过的分页。默认情况下，每页最多返回 300 个会话。使用skip查询参数进行导航以浏览结果。

参数	Description
`skip`	要从开头跳过的会话数（默认值：0）
`nextLink`	下一页结果的完整 URL（当存在更多结果时包含在响应中）

ApiCollectionEnvelope 响应架构

领域	类型	Description
`value`	SessionView[]	会话对象的数组
`nextLink`	字符串	下一页的 URL（如果没有更多结果，则为 null）

示例分页循环

POOL_URL="https://eastasia.dynamicsessions.io/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myrg/sessionPools/mysessionpool"
next_url="$POOL_URL/.management/listSessions?skip=0&api-version=2025-02-02-preview"

while [ -n "$next_url" ]; do
  response=$(curl -s "$next_url" \
    -H "Authorization: Bearer $TOKEN")

  echo "$response" | jq '.value[] | {identifier, expiresAt}'

  next_url=$(echo "$response" | jq -r '.nextLink // empty')
done

示例响应（HTTP 200）：

{
  "value": [
    {
      "identifier": "user-123",
      "etag": "a1b2c3d4",
      "expiresAt": "2026-04-30T14:30:00Z",
      "createdAt": "2026-04-30T13:30:00Z",
      "lastAccessedAt": "2026-04-30T14:29:00Z"
    },
    {
      "identifier": "user-456",
      "etag": "e5f6a7b8",
      "expiresAt": "2026-04-30T14:30:00Z",
      "createdAt": "2026-04-30T13:30:00Z",
      "lastAccessedAt": "2026-04-30T14:29:00Z"
    }
  ],
  "nextLink": "https://eastasia.dynamicsessions.io/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myrg/sessionPools/mysessionpool/listSessions?skip=300"
}

预装的包

Python 代码解释器会话包括常用的 Python 包，例如 NumPy、pandas 和 scikit-learn。

若要输出预装的包列表，请使用以下代码调用 executions 终结点。

在发送请求之前，请将括号之间的 <> 占位符替换为特定于请求的值。

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/executions?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <TOKEN>

{
    "properties": {
        "codeInputType": "inline",
        "executionType": "synchronous",
        "code": "import pkg_resources\n[(d.project_name, d.version) for d in pkg_resources.working_set]"
    }
}

伐木业

可用输出是从代码执行返回的结果，包括 stdout 和 stderr。

如果需要请求或响应跟踪，请在调用会话池管理 API 的应用程序中捕获它（例如，在应用边界处记录请求 ID、输入和响应）。

注意

代码解释器会话不会向 Log Analytics 发出 AppEnvSession 日志。

Metrics

代码解释器使用情况和执行指标作为代码执行 API 的 HTTP 响应标头返回。这些指标不会写入 Log Analytics。

查看指标

调用代码执行 API （/executions）。
检查 HTTP 响应标头中的使用情况和执行指标。

有关代码执行 API 和终结点的详细信息，请参阅会话和管理 API 终结点中的运行代码。

计费

代码解释器会话根据每个会话的持续时间计费。有关详细信息，请参阅计费。

后续步骤

将代码解释器会话与 LangChain 配合使用

反馈

此页面是否有帮助？

Last updated on 2026-05-10

Azure 容器应用中的无服务器代码解释器会话

用于代码解释器会话

代码解释器会话池

会话中的代码执行

会话标识符

身份验证

使用文件

支持的字符

上传文件

下载文件

获取文件元数据

列出文件

安全性

LLM 框架集成

管理 API 终结点

在会话中运行代码

将文件上传到会话

从会话下载文件

获取文件元数据

列出会话中的文件

删除会话

API 参考

请求

参数

示例

请求

响应

检索会话信息

获取单个会话

SessionView 响应架构

示例请求和响应

列出池中的所有会话

分页

ApiCollectionEnvelope 响应架构

示例分页循环

预装的包

伐木业

Metrics

查看指标

计费

后续步骤

反馈

其他资源