通过公共 API 管理环境

2025-10-09

Microsoft Fabric REST API 为 Fabric 项的创建、读取、更新和删除 (CRUD) 操作提供服务终结点。本文介绍可用的环境 REST API 及其用法。

将环境 API 迁移到其稳定的 GA 版本

重要

GA 版本包括现有 API 的请求/响应协定、API 弃用和新 API 中的更新。可以在以下部分中找到详细信息。
引入了新的查询参数 preview ，以促进请求/响应协定更改的转换。查询 preview 参数默认为直到 True2026 年 3 月 31 日，使预览合同仍然可用。将值设置为 False 以开始使用协定的稳定发布版本。
即将被弃用的 API 将继续受支持，直到 2026 年 3 月 31 日，请尽快使用新推出的 API 进行替换。

请求/响应协定更新的 API

类别	API	说明	注释	预览版 "Swagger"	发布版本 Swagger
项操作	发布环境	使用当前挂起的更改触发环境的发布操作。	响应合同中的更新。	发布环境（预览版）	发布环境
分期	列出暂存库	获取完整的暂存库列表。此列表包括已发布的和挂起的库。	响应合同的更新。	列出过渡库（预览版）	列出过渡库
分期	列出暂存 Spark 计算	获取完整的暂存计算配置。暂存配置包括已发布和挂起的计算配置。	更新响应合同。	列出暂存 Spark 计算（预览版）	列出过渡 Spark 计算
分期	更新 Spark 计算	更新环境的计算配置和 Spark 属性。	请求和响应协定中的更新。	更新 Spark 计算（预览版）	更新 Spark 计算
已发布	列出已发布的库	获取在 Spark 会话中已发布且有效的库。	响应合同中的更新。	列出已发布的库（预览版）	列出已发布的库
已发布	列出已发布的 Spark 计算资源	获取在 Spark 会话中发布且有效的 Spark 计算配置和 Spark 属性。	在响应合约中进行更新。	列出已发布的库（预览版）	列出已发布的库

该preview参数的默认值为True，此默认状态将持续到2026 年 3 月 31 日。即，如果请求发送时没有指定该参数，系统会将其视为True，直到弃用日期为止。强烈建议您尽快将实现迁移到稳定版本，并显式将参数preview设置为False以实现迁移。

以 List staging libraries API 为例，API 响应进行了更新。

使用preview参数作为True发送请求时

示例请求：

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/libraries?preview=True

示例响应：

{
  "customLibraries": {
    "wheelFiles": [
      "samplewheel-0.18.0-py2.py3-none-any.whl"
    ],
    "pyFiles": [
      "samplepython.py"
    ],
    "jarFiles": [
      "samplejar.jar"
    ],
    "rTarFiles": [
      "sampleR.tar.gz"
    ]
  },
  "environmentYml": "name: sample-environment\ndependencies:\n  - fuzzywuzzy==0.0.1\n  - matplotlib==0.0.1"
}

使用 preview 作为参数发送请求时 False

示例请求：

  GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/libraries?preview=False

示例响应：

{
  "libraries": [
    {
      "name": "samplewheel-0.18.0-py2.py3-none-any.whl",
      "libraryType": "Custom"
    },
    {
      "name": "fuzzywuzzy",
      "libraryType": "External",
      "version": "0.0.1"
    }
  ],
  "continuationToken": "null",
  "continuationUri": "null"
}

待弃用的 API

重要

即将弃用的 API 将继续受支持，直到 2026 年 3 月 31 日。我们强烈建议使用新引入的 API 来尽快替换实现。

类别	API	说明	注意
分期	上传过渡库	在环境中添加一个自定义库或一/多个公共库。	支持直到 2026 年 3 月 31 日，请使用新引入 `Import external libraries`/`Upload custom library` 的 API 来替换。
分期	删除过渡库	删除一个过渡自定义库或所有公共库。	支持直到 2026 年 3 月 31 日，请使用新引入 `Remove external library`/`Delete custom library` 的 API 来替换。

下面是一些示例，介绍在管理暂存库时的场景。

在您的环境中添加公共库

以前，可以使用 Upload staging libraries API 上传更新的 YAML 文件，现在可以使用 Import external libraries API 导入更新的 YAML。
在您的环境中删除一个公共库模块

以前，可以使用 Upload staging libraries API 上传更新的 YAML 文件，现在可以使用 Remove external library API 将其删除。
删除您环境中的所有公共代码库

以前，可以使用 Delete staging libraries API 删除所有公共库，现在可以使用 Remove external library API 逐个删除公共库，或使用 Import external libraries 上传空 YAML 文件来实现相同的功能。

新 API

类别	API	说明	注意
项操作	使用定义创建环境	使用定义创建新环境。	新 API。
项操作	获取环境定义	获取环境的定义。	新 API。
项操作	更新环境定义	更新环境的定义。	新 API。
分期	导入外部库	将外部库作为 environment.yml 文件上传到环境中。它替代环境中现有外部库的列表。	新 API。
分期	导出外部库	以 environment.yml 文件的形式获取完整的外部库。	新 API。
分期	删除外部库	从环境中删除外部库。此 API 一次接受一个库。	新 API。
分期	上传自定义库	在环境中上传自定义包。此 API 允许一次上传一个文件。支持的文件格式是.jar、.py、.whl 和.tar.gz。	新 API。
分期	删除自定义库	从环境中删除自定义包。将自定义包全名与扩展一起放入 API 请求中，以将其删除。	新 API。
已发布	导出外部库	以 environment.yml 文件的形式获取已发布的外部库。	新 API。

无更新的API

类别	API	说明
项操作	创建环境	在工作区中创建新的空环境。
项操作	获取环境	获取环境的元数据。响应包括环境的状态。
项操作	删除环境	删除现有环境。
项操作	列出环境	获取工作区中的环境列表。
项操作	更新环境	更新环境的元数据，例如名称和说明。
项操作	取消发布环境	取消正在进行的环境发布操作。

若要了解有关环境公共 API 的详细信息，请参阅项 API - 环境。

环境公共 API 用例

重要

本部分演示了 API 的稳定发布版本。

本部分演示如何使用 API 在管理环境时实现特定方案。可以将以下示例中的{WORKSPACE_ID}和{ARTIFACT_ID}属性替换为适当的值。

创建新环境

若要创建新的空环境，请使用以下 API。

示例请求

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments

{
    "displayName": "Environment_1",
    "description": "An environment description"
}

管理暂存库

可以使用上传和删除过渡库 API 来管理环境中的库部分。

检查环境已发布的库

在添加或删除库之前，请使用“获取已发布库”API 检查哪些库当前有效。

示例请求

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/libraries?preview=False

示例响应

{
  "libraries": [
    {
      "name": "samplewheel-0.18.0-py2.py3-none-any.whl",
      "libraryType": "Custom"
    },
    {
      "name": "fuzzywuzzy",
      "libraryType": "External",
      "version": "0.0.1"
    }
  ],
  "continuationToken": "null",
  "continuationUri": "null"
}

导入公共库或上传自定义库

可以使用导入外部库和上传自定义库 API 向环境添加新的公共/自定义库。导入外部库 API 接受 environment.yml 文件，而支持的文件类型为 .whl、 .jar、 .tar.gz， .py 用于上传自定义库 API。

注意

为了更高效地管理公共库，建议在 environment.yml 文件中整合所有从 PyPI 和 Conda 获取的所需库。

上传 API 允许在一个请求中最多 200 MB 的文件。公共 API 目前不支持超出此大小限制的库。

示例请求

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries/importExternalLibraries

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries/samplelibrary.jar

删除自定义库

通过指定类型后缀的完整库文件名，可以一次删除一个自定义库。

注意

如果要删除现有公共库的子集或所有这些库，请通过 Import public libraries API 导入更新的 YAML 文件。

示例请求

DELETE https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries/samplelibrary.jar

管理暂存 Spark 计算

可以使用更新暂存 Spark 计算来管理 Spark 计算。

检查已发布的 Spark 计算的环境

在更改环境的配置之前，请使用“获取发布的 Spark 计算 API”来检查 Spark 计算配置当前是否有效。

示例请求

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/sparkcompute?preview=False

示例响应

{
  "instancePool": {
    "name": "MyWorkspacePool",
    "type": "Workspace",
    "id": "78942136-106c-4f3e-80fc-7ff4eae11603"
  },
  "driverCores": 4,
  "driverMemory": "56g",
  "executorCores": 4,
  "executorMemory": "56g",
  "dynamicExecutorAllocation": {
    "enabled": false,
    "minExecutors": 1,
    "maxExecutors": 1
  },
  "sparkProperties": [
    {
      "key": "spark.acls.enable",
      "value": "false"
    }
  ],
  "runtimeVersion": "1.2"
}

更新计算配置

可以通过编辑此 API 的请求正文来更新 Spark 运行时、切换到另一个池、优化计算配置以及添加或删除 Spark 属性。

可以通过指定池名称和池来切换附加池。指定池名称为 Starter Pool，从而将池切换到默认设置。若要通过 REST API 获取工作区可用自定义池的完整列表，请参阅 “自定义池 - 列出工作区自定义池”。

如果要删除现有的 Spark 属性，请将要删除的键的值指定为 null。

示例请求

PATCH https://api.fabric.microsoft.com/v1/workspaces/f089354e-8366-4e18-aea3-4cb4a3a50b48/environments/707cfd07-cbf1-41da-aad7-dd157ddb8c11/staging/sparkcompute?preview=False

{
  "instancePool": {
    "name": "MyWorkspacePool",
    "type": "Workspace"
  },
  "driverCores": 4,
  "driverMemory": "56g",
  "executorCores": 4,
  "executorMemory": "56g",
  "dynamicExecutorAllocation": {
    "enabled": false,
    "minExecutors": 1,
    "maxExecutors": 1
  },
  "sparkProperties": [
    {
      "key": "spark.acls.enable",
      "value": "false"
    },
    {
      "key": "spark.admin.acls",
      "value": null
    }
  ],
  "runtimeVersion": "1.2"
}

使更改生效

使用以下 API 集发布更改。

准备发布操作

环境一次只能接受一个发布操作。 “在发布环境之前，请验证环境的状态，并最终审查暂存环境的更改。” 成功发布环境后，暂存状态中的所有配置都生效。

步骤 1： 获取环境的元数据。
```
GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/
```
在响应正文中，可以清楚地告知环境的状态。在转到下一步之前，请确保当前没有正在进行的发布操作。

步骤 2： 准备预发布库/Spark 计算环境，以便进行最终评审。

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries?preview=False

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/sparkcompute?preview=False

触发环境的发布操作

对过渡库和 Spark 计算所做的更改会进行缓存，但需要发布才能生效。使用下一个示例触发发布操作。响应正在遵循长时间运行的作（LRO）模式，可能会返回 HTTP 响应代码 202。

示例请求

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/publish?preview=False

示例响应

Location: https://api.fabric.microsoft.com/v1/operations/abcdef00-9d7e-469a-abf1-fca847a0ea69
x-ms-operation-id: abcdef00-9d7e-469a-abf1-fca847a0ea69
Retry-After: 120

在发布操作期间，还可以调用以下 API 以取消发布。

示例请求

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/cancelPublish

反馈

此页面是否有帮助？

通过

通过公共 API 管理环境

将环境 API 迁移到其稳定的 GA 版本

请求/响应协定更新的 API

待弃用的 API

新 API

无更新的API

环境公共 API 用例

创建新环境

管理暂存库

检查环境已发布的库

导入公共库或上传自定义库

删除自定义库

管理暂存 Spark 计算

检查已发布的 Spark 计算的环境

更新计算配置

使更改生效

准备发布操作

触发环境的发布操作

相关内容

反馈

其他资源