通过公共 API 管理环境

2025-05-06

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

重要

新版本包括新的 API、API 弃用和 API 响应/请求协定的更改。以下部分中的表汇总了所有 API 更改。

环境 API 摘要

类别	API（应用程序编程接口）	说明	注意
项操作	创建环境	在工作区中创建新的空环境。	无更改
项操作	使用定义创建环境	使用定义创建新环境。	新 API
项操作	删除环境	删除现有环境。	无更改
项操作	列出环境	获取工作区中环境的列表。	无更改
项操作	获取环境	获取环境的元数据。响应包括环境的状态。	响应协定更新
项操作	获取环境定义	获取环境的定义。	新 API
项操作	更新环境变量	更新环境的元数据，例如名称和说明。	无更改
项操作	更新环境定义	更新环境的定义。	新 API
项操作	发布环境	使用当前挂起的更改触发环境发布。	响应协定更新
项操作	取消发布环境	取消正在进行的环境发布	无更改
分期	列出暂存库	获取完整的暂存库列表。此列表包括已发布的和挂起的库。	响应协定更新
分期	导入外部库	将外部库作为environment.yml文件上传到环境中。它替代环境中现有外部库的列表。	新 API
分期	导出外部库	以environment.yml文件的形式获取完整的外部库。	新 API
分期	删除外部库	从环境中删除外部库。此 API 一次接受一个库	新 API
分期	上传自定义库	在环境中上传自定义包。此 API 允许一次上传一个文件。支持的文件格式是.jar、.py、.whl 和.tar.gz。	新 API
分期	删除自定义库	从环境中删除自定义包。将自定义包全名与扩展一起放入 API 请求中，以将其删除。	新 API
分期	上传暂存库	在环境中添加一个自定义库或一个/多个公共库。	已弃用
分期	删除暂存库	删除一个暂存自定义库或所有公共库。	已弃用
分期	列出暂存 Spark 设置	获取完整的暂存计算配置。暂存配置包括已发布和挂起的计算配置。	响应协定更新
分期	更新 Spark 设置	更新环境的计算配置和 Spark 属性	请求/响应协定更新
已发布	列出已发布的库	获取在 Spark 会话中已发布且有效的库。	响应协定更新
已发布	列出已发布的 Spark 设置	获取在 Spark 会话中发布且有效的 Spark 计算配置和 Spark 属性。	响应协定更新
已发布	导出外部库	以environment.yml文件的形式获取已发布的外部库。	新 API

在项 API - 环境中详细了解现有环境公共 API

环境公共 API 更新详细信息

本部分介绍即将推出的现有 API 更新。

获取环境

在 Get Environment API 的响应中，“startTime”将变为“startDateTime”，“endTime”将变为“endDateTime”。它们表示发布操作的开始/结束时间。

注意

“startTime”和“endTime”使用 Date-Time 格式，而“startDateTime”和“endDateTime”将是 字符串，该字符串采用 UTC 格式并使用 YYYY-MM-DDTHH：mm：ssZ 格式。

接口

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}

原始示例响应

{
  "displayName": "Environment_1",
  "description": "An Environment description",
  "type": "Environment",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "id": "5b218778-e7a5-4d73-8187-f10824047715",
  "properties": {
    "publishDetails": {
      "state": "Success",
      "targetVersion": "46838a80-5450-4414-bea0-40fb6f3e0c0d",
      "startTime": "2024-03-29T14:17:09.0697022Z",
      "endTime": "2024-03-29T14:48:09.0697022Z",
      "componentPublishInfo": {
        "sparkLibraries": {
          "state": "Success"
        },
        "sparkSettings": {
          "state": "Success"
        }
      }
    }
  }
}

新的示例响应

{
  "displayName": "Environment_1",
  "description": "An Environment description",
  "type": "Environment",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "id": "5b218778-e7a5-4d73-8187-f10824047715",
  "properties": {
    "publishDetails": {
      "state": "Success",
      "targetVersion": "46838a80-5450-4414-bea0-40fb6f3e0c0d",
      "startDateTime": "2024-03-29T14:17:09Z",
      "endDateTime": "2024-03-29T14:48:09Z",
      "componentPublishInfo": {
        "sparkLibraries": {
          "state": "Success"
        },
        "sparkSettings": {
          "state": "Success"
        }
      }
    }
  }
}

发布环境

发布环境 API 将从发布版本开始支持长时间运行的操作，响应契约将发生变化。发送请求的终结点保持不变。

接口

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/staging/publish

原始示例响应

{
  "publishDetails": {
    "state": "Running",
    "targetVersion": "46838a80-5450-4414-bea0-40fb6f3e0c0d",
    "startTime": "2024-03-29T14:17:09.0697022Z",
    "componentPublishInfo": {
      "sparkLibraries": {
        "state": "Running"
      },
      "sparkSettings": {
        "state": "Running"
      }
    }
  }
}

新的示例响应


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

列出暂存/已发布库

这两个 API 可以获取环境暂存/已发布库的完整列表。发送请求的终结点保持不变，而库将以不同的结构返回。

接口

获取暂存库

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/staging/libraries

获取已发布的库

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

原始示例响应


{
  "customLibraries": {
    "wheelFiles": [
      "samplewheel-0.18.0-py2.py3-none-any.whl"
    ],
    "pyFiles": [
      "samplepython.py"
    ],
    "jarFiles": [
      "samplejar.jar"
    ],
    "rTarFiles": [
      "sampleR.tar.gz"
    ]
  },
  "environmentYml": "dependencies:\r\n- pip:\r\n  - matplotlib==3.4.3"
}

新的示例响应

{
  "libraries": [
    {
      "name": "samplewheel-0.18.0-py2.py3-none-any.whl",
      "libraryType": "Custom"
    },
    {
      "name": "samplepython.py",
      "libraryType": "Custom"
    },
    {
      "name": "samplejar.jar",
      "libraryType": "Custom"
    },
    {
      "name": "sampleR.tar.gz",
      "libraryType": "Custom"
    },
    {
      "name": "fuzzywuzzy",
      "libraryType": "External",
      "version": "0.0.1"
    },
    {
      "name": "matplotlib",
      "libraryType": "External",
      "version": "0.0.1"
    }
  ],
  "continuationToken": "null",
  "continuationUri": "null"
}

列出暂存/已发布的 Spark 设置

这两个 API 可以获取环境的 Spark 计算配置和属性。发送请求的终结点保持不变，而配置将以不同的结构返回。 Spark 属性将更改为列表。

接口

获取 Spark 测试环境设置

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/staging/sparkcompute

获取已发布的 Spark 设置

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/sparkcompute

原始示例响应

{
  "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": {
    "spark.acls.enable": "false"
  },
  "runtimeVersion": "1.2"
}

新的示例响应

{
  "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"
}

更新 Spark 设置

此 API 用于更新环境的 Spark 计算和属性，发布后，请求和响应中的 Spark 属性协定将更新。

原始示例请求

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

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

新的示例请求

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

{
  "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"
}

原始示例响应

{
  "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": {
    "spark.acls.enable": "false"
  },
  "runtimeVersion": "1.2"
}

新的示例响应

{
  "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 用例

重要

本部分不包括新的 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

示例响应

{
    "customLibraries": {
        "wheelFiles": [
            "samplewheel-0.18.0-py2.py3-none-any.whl"
        ],
        "pyFiles": [
            "samplepython.py"
        ],
        "jarFiles": [
            "samplejar.jar"
        ],
        "rTarFiles": [
            "sampleR.tar.gz"
        ]
    },
    "environmentYml": "dependencies:\r\n- pip:\r\n  - matplotlib==3.4.3"
}

上传库

用于上传暂存库的 API 一次接受一个文件。对于公共库，支持的文件类型包括 .whl、.jar、.tar.gz、.py 和 environment.yml。可以通过多部分/表单数据内容类型指定文件。

注意

为了更有效地操作公共库，强烈建议在 environment.yml 文件中整合来自 PyPI 和 conda 的所有预期库。
上传 API 允许在一个请求中最多 200 MB 的文件，公共 API 目前不支持超出此大小限制的库。

示例请求

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

删除库

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

注意

如果您将 environment.yml 指定为要删除的文件，则您将删除所有公共库。
如果要删除现有公共库的子集，请改用上传库，并上传仅包含预期库的 environment.yml。上传的 environment.yml 将完全替换现有的公共库部分。

示例请求

DELETE https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries?libraryToDelete=fuzzywuzzy-0.18.0-py2.py3-none-any.whl

管理暂存 Spark 计算

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

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

在更改环境的配置之前，可以使用获取已发布的 Spark 计算 API 来检查当前有效的 Spark 计算配置内容。

示例请求

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

示例响应

{
    "instancePool": {
        "name": "Starter Pool",
        "type": "Workspace"
    },
    "driverCores": 4,
    "driverMemory": "56g",
    "executorCores": 4,
    "executorMemory": "56g",
    "dynamicExecutorAllocation": {
        "enabled": false,
        "minExecutors": 1,
        "maxExecutors": 1
    },
    "sparkProperties": {
        "spark.acls.enable": "false"
    },
    "runtimeVersion": "1.2"
}

更新计算配置

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

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

如果要删除现有的 Spark 属性，则需要将值指定为 null（带要删除的密钥），如以下示例所示。

示例请求

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

{
    "instancePool": {
        "name": "Starter Pool",
        "type": "Workspace"
    },
    "driverCores": 4,
    "driverMemory": "56g",
    "executorCores": 4,
    "executorMemory": "56g",
    "dynamicExecutorAllocation": {
        "enabled": false,
        "minExecutors": 1,
        "maxExecutors": 1
    },
    "sparkProperties": {
        "spark.acls.enable": 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

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

触发环境的发布

对暂存库和 Spark 计算进行的更改会缓存，但需要发布才能生效。按照以下示例操作以触发发布。

示例请求

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

示例响应

{
    "publishDetails":
    {
        "state": "Running",
        "targetVersion": "46838a80-5450-4414-bea0-40fb6f3e0c0d",
        "startTime": "2024-03-29T14:17:09.0697022Z",
        "componentPublishInfo": {
            "sparkLibraries": {
                "state": "Running"
            },
            "sparkSettings": {
                "state": "Running"
            }
        }
    }
}

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

示例请求

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

通过

通过公共 API 管理环境

环境 API 摘要

环境公共 API 更新详细信息

获取环境

发布环境

列出暂存/已发布库

列出暂存/已发布的 Spark 设置

更新 Spark 设置

环境公共 API 用例

创建新环境

管理暂存库

检查环境已发布的库

上传库

删除库

管理暂存 Spark 计算

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

更新计算配置

使更改生效

准备发布

触发环境的发布

相关内容

反馈

其他资源