實例集區 API 2.0

實例集區 API 可讓您建立、編輯、刪除和列出實例集區。

實例集區藉由維護一組閒置、現成可用的雲端實例,以減少叢集啟動和自動調整時間。 當連結至集區的叢集需要執行個體時,其會先嘗試配置集區的其中一個閒置執行個體。 如果集區沒有閒置的執行個體,就會藉由從執行個體提供者配置新的執行個體來進行擴充,以因應叢集的要求。 當叢集釋放執行個體時,執行個體會回到集區中,而且可供其他叢集使用。 只有連結至集區的叢集可以使用該集區的閒置執行個體。

Azure Databricks 不會在執行個體於集區中閒置時對 Databricks 單位收費。 執行個體提供者計費確實適用。 請參閱定價

規格需求

重要

若要存取 Databricks REST API,您必須驗證

創建

端點 HTTP 方法
2.0/instance-pools/create POST

建立實例集區。 使用傳 instance_pool_id 回的 來查詢實例集區的狀態,其中包含實例集區目前配置的實例數目。 如果您提供 min_idle_instances 參數,實例會布建在背景中,並準備好在InstancePoolStats中的 等於所要求的最小值之後 idle_count 使用。

如果您的帳戶 已啟用 Databricks Container Services,並使用 建立 preloaded_docker_images 實例集區,您可以使用實例集區來啟動具有 Docker 映射的叢集。 實例集區中的 Docker 映射不需要符合叢集中的 Docker 映射。 不過,在集區上建立之叢集的容器環境必須與實例集區的容器環境一致:您無法使用建立的實例集區來啟動沒有 Docker 映射的叢集,而且您無法使用不使用 preloaded_docker_images Docker 映射啟動叢集所建立 preloaded_docker_images 的實例集區。

注意

Azure Databricks 可能無法取得某些要求的閒置實例,因為執行個體提供者限制或暫時性網路問題。 叢集仍然可以連結至實例集區,但可能不會儘快啟動。

範例

curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/instance-pools/create \
--data @create-instance-pool.json

create-instance-pool.json:

{
  "instance_pool_name": "my-pool",
  "node_type_id": "Standard_D3_v2",
  "min_idle_instances": 10,
  "custom_tags": [
    {
      "key": "my-key",
      "value": "my-value"
    }
  ]
}
{ "instance_pool_id": "1234-567890-fetch12-pool-A3BcdEFg" }

要求結構

欄位名稱 類型 說明
instance_pool_name STRING 實例集區的名稱。 這是建立和編輯作業的必要專案。 它必須是唯一、非空白且小於 100 個字元。
min_idle_instances INT32 集區所維護的閒置實例數目下限。 這是使用中叢集所使用的任何實例。
max_capacity INT32 集區可包含的實例數目上限,包括閒置實例和叢集所使用的實例數目上限。 達到最大容量之後,您無法從集區建立新的叢集,而且現有的叢集無法自動擴大,直到某些實例透過叢集終止或相應減少在集區中閒置為止。
node_type_id STRING 集區中實例的節點類型。 連結至集區的所有叢集都會繼承此節點類型,而且集區的閒置實例會根據此類型進行配置。 您可以使用 清單節點類型 API 呼叫來擷取可用節點類型的清單。
custom_tags ClusterTag的陣列 實例集區資源的其他標籤。 除了default_tags以外,Azure Databricks 會標記所有集區資源 (例如 VM 磁片區) 這些標籤。

Azure Databricks 最多可允許 41 個自訂標籤。
idle_instance_autotermination_minutes INT32 閒置實例超過min_idle_instances的分鐘數,會在終止之前由集區維護。 如果未指定,則會在預設逾時期間之後自動終止多餘的閒置實例。 如果指定,時間必須介於 0 到 10000 分鐘之間。 如果提供 0,則會儘快移除多餘的閒置實例。
enable_elastic_disk BOOL 自動調整本機儲存體:啟用時,集區中的實例會在磁碟空間不足時動態取得額外的磁碟空間。
disk_spec DiskSpec 定義連結至集區中每個實例的初始遠端儲存體數量。
preloaded_spark_versions STRING 的陣列。 最多一個執行時間版本的清單,集區會在每個實例上安裝。 使用預先載入執行階段版本的集區叢集會更快啟動,因為它們不需要等待映射下載。 您可以使用執行時間版本 API 呼叫來擷取可用的執行時間 版本 清單。
preloaded_docker_images DockerImage的陣列 每個實例上最多安裝一個 Docker 映射的清單。 使用預先載入 Docker 映射的集區叢集會更快啟動,因為它們不需要等待映射下載。 只有在您的帳戶 已啟用Databricks Container Services 時才可使用。
azure_attributes InstancePoolAzureAttributes 定義實例可用性類型 (,例如現成或隨選) 和最大價格。

回應結構

欄位名稱 類型 說明
instance_pool_id STRING 已建立實例集區的識別碼。

編輯

端點 HTTP 方法
2.0/instance-pools/edit POST

編輯實例集區。 這會修改現有實例集區的組態。

注意

  • 您只能編輯下列值: instance_pool_namemin_idle_instancesmax_capacityidle_instance_autotermination_minutes
  • 您必須提供 instance_pool_name 值。

範例

curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/instance-pools/edit \
--data @edit-instance-pool.json

edit-instance-pool.json:

{
  "instance_pool_id": "1234-567890-fetch12-pool-A3BcdEFg",
  "instance_pool_name": "my-edited-pool",
  "min_idle_instances": 5,
  "max_capacity": 200,
  "idle_instance_autotermination_minutes": 30
}
{}

要求結構

欄位名稱 類型 說明
instance_pool_id STRING 要編輯之實例集區的識別碼。 此為必要欄位。
instance_pool_name STRING 實例集區的名稱。 這是建立和編輯作業的必要專案。 它必須是唯一、非空白且小於 100 個字元。
min_idle_instances INT32 集區所維護的閒置實例數目下限。 除了使用中叢集所使用的任何實例之外,此專案也一樣。
max_capacity INT32 集區可包含的最大實例數目,包括閒置實例和叢集所使用的實例數目上限。 達到最大容量之後,您無法從集區建立新的叢集,而且現有的叢集無法自動調整,直到某些實例透過叢集終止或相應減少在集區中閒置為止。
idle_instance_autotermination_minutes INT32 在終止之前,集區會維護閒置實例超過 的 min_idle_instances 分鐘數。 如果未指定,則會在預設逾時期間之後自動終止多餘的閒置實例。 如果指定,時間必須介於 0 到 10000 分鐘之間。 如果提供 0,則會儘快移除多餘的閒置實例。

刪除

端點 HTTP 方法
2.0/instance-pools/delete POST

刪除實例集區。 這會永久刪除實例集區。 集區中的閒置實例會以非同步方式終止。 新的叢集無法連結至集區。 執行連結至集區的叢集會繼續執行,但無法自動相應增加。 連結至集區的終止叢集將無法啟動,直到編輯為不再使用集區為止。

範例

curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/instance-pools/delete \
--data '{ "instance_pool_id": "1234-567890-fetch12-pool-A3BcdEFg" }'
{}

要求結構

欄位名稱 類型 說明
instance_pool_id STRING 要刪除之實例集區的識別碼。

獲取

端點 HTTP 方法
2.0/instance-pools/get GET

擷取指定其識別碼的實例集區資訊。

範例

curl --netrc -X GET \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/instance-pools/get \
--data '{ "instance_pool_id": "1234-567890-fetch12-pool-A3BcdEFg" }'
{
  "instance_pool_name": "mypool",
  "node_type_id": "Standard_D3_v2",
  "custom_tags": {
    "my-key": "my-value"
  },
  "idle_instance_autotermination_minutes": 60,
  "enable_elastic_disk": false,
  "preloaded_spark_versions": [
    "5.4.x-scala2.11"
  ],
  "instance_pool_id": "101-120000-brick1-pool-ABCD1234",
  "default_tags": {
    "Vendor": "Databricks",
    "DatabricksInstancePoolCreatorId": "100125",
    "DatabricksInstancePoolId": "101-120000-brick1-pool-ABCD1234"
  },
  "state": "ACTIVE",
  "stats": {
    "used_count": 10,
    "idle_count": 5,
    "pending_used_count": 5,
    "pending_idle_count": 5
  },
  "status": {}
}

要求結構

欄位名稱 類型 說明
instance_pool_id STRING 要擷取資訊的實例集區。

回應結構

欄位名稱 類型 說明
instance_pool_name STRING 實例集區的名稱。 這是建立和編輯作業的必要專案。 它必須是唯一、非空白且小於 100 個字元。
min_idle_instances INT32 集區所維護的閒置實例數目下限。 除了使用中叢集所使用的任何實例之外,此專案也一樣。
max_capacity INT32 集區可包含的最大實例數目,包括閒置實例和叢集所使用的實例數目上限。 達到最大容量之後,您無法從集區建立新的叢集,而且現有的叢集無法自動調整,直到某些實例透過叢集終止或相應減少在集區中閒置為止。
node_type_id STRING 集區中實例的節點類型。 連結至集區的所有叢集都會繼承此節點類型,且集區的閒置實例會根據此類型來配置。 您可以使用 清單節點類型 API 呼叫來擷取可用節點類型的清單。
custom_tags ClusterTag的陣列 實例集區資源的其他標籤。 除了default_tags之外,Azure Databricks 也會標記所有集區資源 (例如 VM 磁片區) 這些標籤。

Azure Databricks 最多可允許 41 個自訂標記。
idle_instance_autotermination_minutes INT32 在終止之前,集區會維護閒置實例超過 的 min_idle_instances 分鐘數。 如果未指定,則會在預設逾時期間之後自動終止多餘的閒置實例。 如果指定,時間必須介於 0 到 10000 分鐘之間。 如果提供 0,則會儘快移除多餘的閒置實例。
enable_elastic_disk BOOL 自動調整本機儲存體:啟用時,集區中的實例會在磁碟空間不足時動態取得額外的磁碟空間。
disk_spec DiskSpec 定義連結至集區中每個實例的初始遠端儲存體數量。
preloaded_spark_versions STRING 的陣列。 具有集區在每個實例上安裝的執行時間版本清單。 使用預先載入執行時間版本的集區叢集會更快啟動,因為它們不需要等待映射下載。 您可以使用執行時間版本 API 呼叫來擷取可用執行時間 版本 的清單。
instance_pool_id STRING 實例集區標準的唯一識別碼。
default_tags ClusterTag的陣列 不論任何custom_tags,Azure Databricks 都會新增的標記,包括:

* 廠商:Databricks
* DatabricksInstancePoolCreatorId: < create_user_id>
* DatabricksInstancePoolId: < instance_pool_id>
state InstancePoolState 實例集區的目前狀態。
stats InstancePoolStats 實例集區使用量的相關統計資料。
status InstancePoolStatus 集區中失敗暫止實例的狀態。

清單

端點 HTTP 方法
2.0/instance-pools/list GET

列出所有實例集區的資訊。

範例

curl --netrc -X GET \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/instance-pools/list
{
  "instance_pools": [
    {
      "instance_pool_name": "mypool",
      "node_type_id": "Standard_D3_v2",
      "idle_instance_autotermination_minutes": 60,
      "enable_elastic_disk": false,
      "preloaded_spark_versions": [
        "5.4.x-scala2.11"
      ],
      "instance_pool_id": "101-120000-brick1-pool-ABCD1234",
      "default_tags": {
        "Vendor": "Databricks",
        "DatabricksInstancePoolCreatorId": "100125",
        "DatabricksInstancePoolId": "101-120000-brick1-pool-ABCD1234"
      },
      "state": "ACTIVE",
      "stats": {
        "used_count": 10,
        "idle_count": 5,
        "pending_used_count": 5,
        "pending_idle_count": 5
      },
      "status": {}
    },
    {
      "..."
    }
  ]
}

回應結構

欄位名稱 類型 說明
instance_pools InstancePoolStatus的陣列 包含其統計資料的實例集區清單。

資料結構

本節內容:

InstancePoolState

實例集區的狀態。 目前的允許狀態轉換如下:

  • ACTIVE ->DELETED
名称 說明
使用中 表示實例集區為使用中。 叢集可以連結至叢集。
DELETED 表示實例集區已刪除且無法再存取。

InstancePoolStats

實例集區使用方式的相關統計資料。

欄位名稱 類型 說明
used_count INT32 叢集正在使用中的實例數目。
idle_count INT32 未由叢集使用中的實例數目。
pending_used_count INT32 指派給叢集的暫止實例數目。
pending_idle_count INT32 未指派給叢集的暫止實例數目。

InstancePoolStatus

集區中失敗擱置實例的狀態。

欄位名稱 類型 說明
pending_instance_errors PendingInstanceError的陣列 失敗擱置實例的錯誤訊息清單。

PendingInstanceError

失敗擱置實例的錯誤訊息。

欄位名稱 類型 說明
instance_id STRING 失敗實例的識別碼。
message STRING 描述失敗原因的訊息。

DiskSpec

描述要連結至每個實例的初始磁片集。 例如,如果有 3 個實例,而且每個實例都設定為從 2 個磁片開始,則每個實例 100 GiB,則 Azure Databricks 會針對這些實例建立總共 6 個磁片,每個磁片 100 GiB。

欄位名稱 類型 說明
disk_type DiskType 要連接的磁片類型。
disk_count INT32 要連結至每個實例的磁片數目:

* 此功能僅針對支援的節點類型啟用。
* 使用者可以選擇節點類型所支援的磁片限制。
* 對於沒有本機磁片的節點類型,至少必須指定一個磁片。
disk_size INT32 要連接的 GiB) 中每個磁片的大小 (。 值必須屬於特定實例類型的支援範圍:

* 進階 LRS (SSD) :1 - 1023 GiB
* 標準 LRS (HDD) :1- 1023 GiB

DiskType

描述磁片的類型。

欄位名稱 類型 說明
azure_disk_volume_type AzureDiskVolumeType 要使用的 Azure 磁片類型。

InstancePoolAndStats

欄位名稱 類型 說明
instance_pool_name STRING 實例集區的名稱。 這是建立和編輯作業的必要專案。 它必須是唯一、非空白且小於 100 個字元。
min_idle_instances INT32 集區所維護的閒置實例數目下限。 這是使用中叢集所使用的任何實例。
max_capacity INT32 集區可包含的實例數目上限,包括閒置實例和叢集所使用的實例數目上限。 達到最大容量之後,您無法從集區建立新的叢集,而且現有的叢集無法自動擴大,直到某些實例透過叢集終止或相應減少在集區中閒置為止。
node_type_id STRING 集區中實例的節點類型。 連結至集區的所有叢集都會繼承此節點類型,而且集區的閒置實例會根據此類型進行配置。 您可以使用 清單節點類型 API 呼叫來擷取可用節點類型的清單。
custom_tags ClusterTag的陣列 實例集區資源的其他標籤。 除了default_tags以外,Azure Databricks 會標記所有集區資源 (例如 VM 磁片區) 這些標籤。

Azure Databricks 最多可允許 41 個自訂標籤。
idle_instance_autotermination_minutes INT32 閒置實例超過 min_idle_instances 的分鐘數會由集區維護,然後再終止。 如果未指定,則會在預設逾時期間之後自動終止多餘的閒置實例。 如果指定,時間必須介於 0 到 10000 分鐘之間。 如果提供 0,則會儘快移除多餘的閒置實例。
enable_elastic_disk BOOL 自動調整本機儲存體:啟用時,集區中的實例會在磁碟空間不足時動態取得額外的磁碟空間。
disk_spec DiskSpec 定義連結至集區中每個實例的初始遠端儲存體數量。
preloaded_spark_versions STRING 的陣列。 具有集區所安裝執行時間版本的清單。每個實例上都會安裝集區。 使用預先載入執行階段版本的集區叢集會更快啟動,因為它們不需要等待映射下載。 您可以使用執行時間版本 API 呼叫來擷取可用的執行時間 版本 清單。
instance_pool_id STRING 實例集區的正式唯一識別碼。
default_tags ClusterTag的陣列 不論任何custom_tags,Azure Databricks 所新增的標籤,包括:

* 廠商:Databricks
* DatabricksInstancePoolCreatorId: < create_user_id>
* DatabricksInstancePoolId: < instance_pool_id>
state InstancePoolState 實例集區的目前狀態。
stats InstancePoolStats 實例集區使用方式的相關統計資料。

AzureDiskVolumeType

Azure Databricks 支援的所有 Azure 磁片類型。 請參閱https://learn.microsoft.com/azure/virtual-machines/linux/disks-types

名称 說明
PREMIUM_LRS 進階儲存層,由 SSD 支援。
STANDARD_LRS 標準儲存層,由 HDD 支援。

InstancePoolAzureAttributes

建立與 Azure 相關的實例集區期間所設定的屬性。

欄位名稱 類型 說明
availability AzureAvailability 用於所有後續節點的可用性類型。
spot_bid_max_price DOUBLE 用於 Azure 現成實例的最大價格。 您可以將此設定為大於或等於目前的現成價格。 您也可以將此設定為 -1 (預設) ,指定無法根據價格收回實例。 實例的價格將是現成實例的目前價格或標準實例的價格。 您可以在Azure 入口網站中檢視歷程記錄定價和收回率。