透過公用 API 管理環境

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

將環境 API 移轉至其穩定的 GA 版本

重要

GA 正式版包括現有 API 請求/回應合約的更新、API 廢棄聲明以及新 API。您可以在以下各節中找到詳細資訊。
引進了新的查詢參數 beta ，以方便要求/回應合約變更的轉換。 beta查詢參數預設為 True2026 年 3 月 31 日之前，因此預覽合約仍然可用。將值設定為 False ，以開始使用合約的穩定發行版本。
Preview 查詢參數已被取代 beta。為了向下相容，預覽版仍被支援，且行為與測試版相同。
即將被廢棄的 API 將繼續支援至 2026 年 3 月 31 日，請盡快使用新推出的 API 替換舊的 API。

具有要求/回應合約更新的 API

類別	API	描述	註釋	預覽版 Swagger	發佈版本 Swagger
項目作業	發佈環境	觸發具有目前擱置變更的環境發佈作業。	在回應合約中更新。	發佈環境（預覽）	發佈環境
分期	列出暫存連結庫	取得完整的暫存程式庫清單。此清單包含已發佈和擱置的程式庫。	在回應合約中更新。	列出預備程式庫（預覽版）	列出預備程式庫
分期	列出 Spark 運算的準備環境	取得完整的預備計算組態。暫存組態包括已發佈和擱置的計算組態。	在回應合約中更新。	列表暫存的 Spark 運算（預覽版）	列出預備 Spark 計算
分期	更新 Spark 計算	更新環境的計算組態和 Spark 屬性。	更新請求和回應契約。	更新 Spark 計算（預覽）	更新 Spark 計算
發布	列出已發佈的函式庫	取得在 Spark 會話中已發佈且生效的函式庫。	在回應合約中更新。	列出已發佈的程式庫（預覽版）	列出已發佈的程式庫
發布	列出已發佈的 Spark 計算資源	取得 Spark 計算設定和 Spark 屬性，這些屬性會在 Spark 工作階段中發佈且生效。	在回應合約中更新。	列出已發佈的程式庫（預覽版）	列出已發佈的程式庫

參數 beta 預設為 True 直到 2026 年 3 月 31 日，即系統將參數 True 視為請求正在發送，而無需指定此參數，直到淘汰日期。我們強烈建議您將實作儘快移轉至穩定版本，方法是將參數beta明確設定為False。

以 List staging libraries API 為例，其 API 回應中有更新。

當傳送請求時，參數為betaTrue

範例要求：

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/libraries?beta=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"
}

當傳送請求時，參數為previewFalse

範例要求：

  GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/libraries?beta=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進行替換。

以下是幾個範例，涵蓋管理暫存程式庫時的案例。

在您的環境中新增公用程式庫

以前，您可以使用 API 上傳 Upload staging libraries 更新的 YAML 文件，現在可以使用 API 導入 Import external libraries 更新的 YAML。
刪除環境中的一個公用文件庫

以前，您可以使用 Upload staging libraries API 上傳更新的 YAML 文件，現在您可以使用 Remove external library API 將其刪除。
刪除環境中的所有公用文件庫

以前可以使用API刪除 Delete staging libraries 所有公共函式庫，現在可以使用API逐 Remove external library 一刪除公共函式庫或使用上傳 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 來管理環境中的程式庫區段。

檢查已發佈的環境程式庫

新增或刪除程式庫之前，請使用 Get Published Libraries API 來檢查哪些程式庫目前有效。

範例要求

GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/libraries?beta=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。

注意

若要更有效率地操作公用程式庫，建議您將 PyPI 和 Conda 的所有預期程式庫撰寫在 environment.yml 檔案中。

上傳 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

刪除自訂程式庫

透過指定具有類型尾碼的完整程式庫檔名，您可以一次刪除一個自訂程式庫。

注意

如果您想刪除現有公共函式庫的子集或所有函式庫，請透過 API 匯 Import public libraries 入更新的 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?beta=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?beta=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?beta=False

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

觸發環境的發布操作

您對暫存程式庫和 Spark 運算所做的變更已快取，但必須發佈才能生效。使用下一個範例來觸發發佈作業。回應遵循長時間執行作業（LRO）型樣，且可能會傳回 HTTP 回應碼 202。

範例要求

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/publish?beta=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

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-21

共用方式為

透過公用 API 管理環境

將環境 API 移轉至其穩定的 GA 版本

具有要求/回應合約更新的 API

即將淘汰的 API

新的 API

沒有更新的 API

環境公用 API 使用案例

建立新環境

管理暫存程式庫

檢查已發佈的環境程式庫

匯入公用程式庫或上傳自訂程式庫

刪除自訂程式庫

管理暫存 Spark 計算

檢視已發佈於環境中的 Spark 計算

更新計算組態

讓變更生效

準備發佈作業

觸發環境的發布操作

相關內容

意見反應

其他資源