共用方式為

透過公用 API 管理環境

  • 發行項

Microsoft Fabric REST API 會為 Fabri 項目的建立、讀取、更新和刪除 (CRUD) 作業提供服務端點。 本文說明可用的環境 REST API 及其使用方式。

重要

這項功能目前為預覽版。

可用環境 API 的摘要

API 描述 類別
建立環境 在工作區中建立新環境。 一般
SUT 環境 取得環境的中繼資料。 回應包括環境的狀態。 一般
更新環境 更新環境的中繼資料，例如名稱和描述。 一般
刪除環境 刪除現有環境 一般
列出工作區中的環境 列出工作區中的環境清單。 一般
發佈環境 使用目前擱置的變更觸發環境發佈。 一般
發佈取消 取消環境的持續發佈 一般
取得已發佈的 Spark 計算 取得有效的 Spark 計算組態。 Spark 計算
取得暫存 Spark 計算 取得完整的暫存計算組態。 暫存組態包括已發佈和擱置的計算組態。 Spark 計算
取得已發佈的程式庫 取得有效的程式庫清單。 程式庫
取得暫存程式庫 取得完整的暫存程式庫清單。 此清單包含已發佈和擱置的程式庫。 程式庫
上傳暫存程式庫 在環境中新增一個自訂程式庫或一個/多個公用程式庫。 程式庫
刪除暫存程式庫 刪除一個暫存自訂程式庫或所有公用程式庫。 程式庫

深入了解項目項目 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。 您可以透過 multipart/form-data content-type 來指定檔案。

注意

  • 為了更有效率地操作公用程式庫，強烈建議在 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

相關內容