通过

通过公共 API 管理环境

  • 项目

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

重要

此功能目前为预览版。

可用环境 API 的摘要

API 说明 类别
创建环境 在工作区中创建新环境。 常规
获取环境 获取环境的元数据。 响应包括环境的状态。 常规
更新环境变量 更新环境的元数据，例如名称和说明。 常规
删除环境 删除现有环境。 常规
列出工作区中的环境 获取工作区中环境的列表。 常规
发布环境 使用当前挂起的更改触发环境发布。 常规
发布取消 取消正在进行的环境发布 常规
获取已发布 Spark 计算 获取有效的 Spark 计算配置。 Spark 计算
获取暂存 Spark 计算 获取完整的暂存计算配置。 暂存配置包括已发布和挂起的计算配置。 Spark 计算
获取已发布的库 获取有效的库列表。 Libraries
获取暂存库 获取完整的暂存库列表。 此列表包括已发布的和挂起的库。 Libraries
上传暂存库 在环境中添加一个自定义库或一个/多个公共库。 Libraries
删除暂存库 删除一个暂存自定义库或所有公共库。 Libraries

详细了解项目 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。 可以通过多部分/表单数据内容类型指定文件。

注意

  • 为了更有效地操作公共库，强烈建议将 PyPI 和 conda 中的所有预期库组合到一个 environment.yml 文件中。
  • 上传 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

相关内容