实例池API 2.0

实例池API允许您创建、编辑、删除和列出实例池。

实例池通过维护一组空闲的、随时可用的云实例来减少集群启动和自动伸缩时间。当连接到池的集群需要实例时，它首先尝试分配池的空闲实例之一。如果池没有空闲实例，它将通过从实例提供程序分配一个新实例进行扩展，以适应集群的请求。当一个集群释放一个实例时，它将返回到池中，供另一个集群使用。只有附加到池的集群才能使用该池的空闲实例。

当实例在池中空闲时，Databricks不向DBUs收费。实例提供程序计费不适用。看到定价．

需求

您必须拥有连接到池的权限;看到池访问控制．
您必须将以下权限添加到与用于创建AWS帐户的跨帐户IAM角色或密钥关联的访问策略中:
```
｛“行动”：［“ec2: AssociateIamInstanceProfile”，“ec2: DescribeIamInstanceProfileAssociations”，“ec2: DisassociateIamInstanceProfile”，“ec2: ReplaceIamInstanceProfileAssociation”，“ec2: DeleteTags”］｝
```
有关权限的完整列表以及关于如何更新现有跨帐户IAM角色或密钥的说明，请参见创建跨帐号IAM角色或联系内部的Databricks管理员。

重要的

如果不添加这些权限，将无法启动集群。

重要的

要访问Databricks REST api，必须进行身份验证．

创建

端点	HTTP方法
`2.0 / instance-pools /创建`	`帖子`

创建实例池。使用返回的instance_pool_id查询实例池的状态，包括实例池当前分配的实例数。如果你提供min_idle_instances参数时，实例是在后台准备的，一旦idle_count在InstancePoolStats等于请求的最小值。

如果您的帐户有Databricks容器服务启用创建实例池时使用preloaded_docker_images，您可以使用实例池来启动带有Docker映像的集群。实例池中的Docker映像不必与集群中的Docker映像相匹配。但是，在池上创建的集群的容器环境必须与实例池的容器环境保持一致:不能使用创建的实例池preloaded_docker_images在没有Docker镜像的情况下启动集群，并且不能使用没有Docker镜像创建的实例池preloaded_docker_images到带有Docker映像的启动集群。

请注意

由于实例提供者的限制(帐户限制、现货价格等)或瞬时网络问题，Databricks可能无法获得一些请求的空闲实例。集群仍然可以附加到实例池，但可能无法快速启动。

例子

              —netrc -X POST＼https://dbc-a1b2345c-d6e7.cloud.www.neidfyre.com/api/2.0/instance-pools/create＼——数据@create-instance-pool.json
             

create-instance-pool.json：

              ｛“instance_pool_name”：“把游泳池”，“node_type_id”：“i3.xlarge”，“min_idle_instances”：10，“aws_attributes”：｛“可用性”：“现货”}，“custom_tags”：［｛“关键”：“我的钥匙”，“价值”：“自己的价值”｝］｝
             

              ｛“instance_pool_id”：“1234 - 567890 - fetch12池a3bcdefg”｝
             

请求结构

字段名	类型	描述
instance_pool_name	`字符串`	实例池的名称。这是创建和编辑操作所必需的。必须唯一，非空，且长度小于100个字符。
min_idle_instances	`INT32`	由池维护的空闲实例的最小数目。这是活动集群所使用的任何实例的补充。
max_capacity	`INT32`	池可以包含的最大实例数，包括空闲实例和集群正在使用的实例。一旦达到最大容量，您就不能从池中创建新的集群，现有的集群也不能自动扩展，直到通过集群终止或降级使池中的某些实例空闲。
aws_attributes	InstancePoolAwsAttributes	与在Amazon Web Services上运行的实例池相关的属性。如果在创建时未指定，则使用一组默认值。
node_type_id	`字符串`	池中实例的节点类型。连接到池的所有集群继承此节点类型，池的空闲实例基于此类型分配。方法可以检索可用节点类型的列表列表节点类型API调用。
custom_tags	的数组ClusterTag	用于实例池资源的附加标记。Databricks除了default_tags外，还使用这些标签标记所有池资源(例如AWS实例和EBS卷)。 Databricks最多允许43个自定义标记。
idle_instance_autotermination_minutes	`INT32`	空闲实例超过min_idle_instances在被终止之前由池维护的分钟数。如果未指定，多余的空闲实例将在默认超时时间后自动终止。如果指定，时间必须在0到10000分钟之间。如果你指定`0`，多余的空闲实例会被尽快移除。
enable_elastic_disk	`保龄球`	自动伸缩本地存储:启用后，池中的实例在磁盘空间不足时动态地获取额外的磁盘空间。
disk_spec	DiskSpec	定义附加到池中每个实例的初始远程存储量。
preloaded_spark_versions	的数组`字符串`	池在每个实例上最多安装一个运行时版本的列表。使用预加载的运行时版本的池集群启动更快，因为它们不必等待映像下载。控件可以检索可用运行时版本的列表运行时版本API调用。
preloaded_docker_images	的数组DockerImage	池在每个实例上最多安装一个Docker映像的列表。使用预加载Docker镜像的池集群启动更快，因为它们不必等待镜像下载。仅当您的帐户具有Databricks容器服务时可用启用．

响应结构

字段名	类型	描述
instance_pool_id	`字符串`	创建的实例池ID。

编辑

端点	HTTP方法
`2.0 / instance-pools /编辑`	`帖子`

编辑实例池。这将修改现有实例池的配置。

请注意

说明只能编辑以下值:instance_pool_name，min_idle_instances，max_capacity,idle_instance_autotermination_minutes．
你必须提供instance_pool_name价值。

例子

              —netrc -X POST＼https://dbc-a1b2345c-d6e7.cloud.www.neidfyre.com/api/2.0/instance-pools/edit＼——数据@edit-instance-pool.json
             

edit-instance-pool.json：

              ｛“instance_pool_id”：“1234 - 567890 - fetch12池a3bcdefg”，“instance_pool_name”：“my-edited-pool”，“min_idle_instances”：5，“max_capacity”：200，“idle_instance_autotermination_minutes”：30.｝
             

{}

请求结构

字段名	类型	描述
instance_pool_id	`字符串`	要编辑的实例池的ID。该字段为必填项。
instance_pool_name	`字符串`	实例池的名称。这是创建和编辑操作所必需的。必须唯一，非空，且长度小于100个字符。
min_idle_instances	`INT32`	由池维护的空闲实例的最小数目。这是活动集群所使用的任何实例的补充。
max_capacity	`INT32`	池可以包含的最大实例数，包括空闲实例和集群正在使用的实例。一旦达到最大容量，您就不能从池中创建新的集群，现有的集群也不能自动扩展，直到通过集群终止或降级使池中的某些实例空闲。
idle_instance_autotermination_minutes	`INT32`	空闲实例超过的分钟数`min_idle_instances`在终止之前由池维护。如果未指定，多余的空闲实例将在默认超时时间后自动终止。如果指定，时间必须在0到10000分钟之间。如果提供0，则会尽快删除多余的空闲实例。

删除

端点	HTTP方法
`2.0 / instance-pools /删除`	`帖子`

删除实例池。这将永久地删除实例池。池中的空闲实例将异步终止。无法将新集群附加到池。连接到池的正在运行的集群将继续运行，但不能自动扩展。连接到池的终止集群将无法启动，直到它们被编辑为不再使用池。

例子

              —netrc -X POST＼https://dbc-a1b2345c-d6e7.cloud.www.neidfyre.com/api/2.0/instance-pools/delete＼——数据'{"instance_pool_id": "1234-567890-fetch12-pool-A3BcdEFg"}'
             

{}

请求结构

字段名	类型	描述
instance_pool_id	`字符串`	需要删除的实例池ID。

得到

端点	HTTP方法
`2.0 / instance-pools /`	`得到`

检索给定实例池标识符的实例池的信息。

例子

              —netrc -X GET＼https://dbc-a1b2345c-d6e7.cloud.www.neidfyre.com/api/2.0/instance-pools/get＼——数据'{"instance_pool_id": "1234-567890-fetch12-pool-A3BcdEFg"}'
             

              ｛“instance_pool_name”：“mypool”，“min_idle_instances”：0，“aws_attributes”：｛“可用性”：“现货”，“zone_id”：“us-west-2a”，“spot_bid_price_percent”：One hundred.}，“node_type_id”：“c4.2xlarge”，“custom_tags”：｛“我的钥匙”：“自己的价值”}，“idle_instance_autotermination_minutes”：60，“enable_elastic_disk”：假，“disk_spec”：｛“disk_type”：｛“ebs_volume_type”：“GENERAL_PURPOSE_SSD”}，“disk_count”：1，“disk_size”：One hundred.}，“preloaded_spark_versions”：［“5.4.x-scala2.11”]，“instance_pool_id”：“1234 - 567890 - fetch12池a3bcdefg”，“default_tags”：｛“供应商”：“砖”，“DatabricksInstancePoolCreatorId”：“100125”，“DatabricksInstancePoolId”：“1234 - 567890 - fetch12池a3bcdefg”}，“状态”：“活跃”，“统计数据”：｛“used_count”：10，“idle_count”：5，“pending_used_count”：5，“pending_idle_count”：5}，“状态”：{}｝
             

请求结构

字段名	类型	描述
instance_pool_id	`字符串`	要检索其信息的实例池。

响应结构

字段名	类型	描述
instance_pool_name	`字符串`	实例池的名称。这是创建和编辑操作所必需的。必须唯一，非空，且长度小于100个字符。
min_idle_instances	`INT32`	由池维护的空闲实例的最小数目。这是活动集群所使用的任何实例的补充。
max_capacity	`INT32`	池可以包含的最大实例数，包括空闲实例和集群正在使用的实例。一旦达到最大容量，您就不能从池中创建新的集群，现有的集群也不能自动扩展，直到通过集群终止或降级使池中的某些实例空闲。
aws_attributes	InstancePoolAwsAttributes	与在Amazon Web Services上运行的实例池相关的属性。如果在创建时未指定，则使用一组默认值。
node_type_id	`字符串`	池中实例的节点类型。连接到池的所有集群继承此节点类型，池的空闲实例基于此类型分配。方法可以检索可用节点类型的列表列表节点类型API调用。
custom_tags	的数组ClusterTag	用于实例池资源的附加标记。Databricks除了default_tags外，还使用这些标签标记所有池资源(例如AWS实例和EBS卷)。 Databricks最多允许43个自定义标记。
idle_instance_autotermination_minutes	`INT32`	空闲实例超过的分钟数`min_idle_instances`在终止之前由池维护。如果未指定，多余的空闲实例将在默认超时时间后自动终止。如果指定，时间必须在0到10000分钟之间。如果提供0，则会尽快删除多余的空闲实例。
enable_elastic_disk	`保龄球`	自动伸缩本地存储:启用后，池中的实例在磁盘空间不足时动态地获取额外的磁盘空间。
disk_spec	DiskSpec	定义附加到池中每个实例的初始远程存储量。
preloaded_spark_versions	的数组`字符串`	包含池在每个实例上安装的运行时版本的列表。使用预加载的运行时版本的池集群启动更快，因为它们不必等待映像下载。控件可以检索可用运行时版本的列表运行时版本API调用。
instance_pool_id	`字符串`	实例池的规范唯一标识符。
default_tags	的数组ClusterTag	Databricks添加的标签，不考虑任何custom_tags，包括: 供应商:砖 DatabricksInstancePoolCreatorId: < create_user_id > DatabricksInstancePoolId: < instance_pool_id >
状态	InstancePoolState	实例池的当前状态。
统计数据	InstancePoolStats	实例池使用情况的统计信息。
状态	InstancePoolStatus	池中失败的挂起实例的状态。

列表

端点	HTTP方法
`2.0 / instance-pools /列表`	`得到`

列出所有实例池的信息。

例子

              —netrc -X GET＼https://dbc-a1b2345c-d6e7.cloud.www.neidfyre.com/api/2.0/instance-pools/list
             

              ｛“instance_pools”：［｛“instance_pool_name”：“mypool”，“min_idle_instances”：0，“aws_attributes”：｛“可用性”：“现货”，“zone_id”：“us-west-2a”，“spot_bid_price_percent”：One hundred.}，“node_type_id”：“c4.2xlarge”，“idle_instance_autotermination_minutes”：60，“enable_elastic_disk”：假，“disk_spec”：｛“disk_type”：｛“ebs_volume_type”：“GENERAL_PURPOSE_SSD”}，“disk_count”：1，“disk_size”：One hundred.}，“preloaded_spark_versions”：［“5.4.x-scala2.11”]，“instance_pool_id”：“1234 - 567890 - fetch12池a3bcdefg”，“default_tags”：｛“供应商”：“砖”，“DatabricksInstancePoolCreatorId”：“100125”，“DatabricksInstancePoolId”：“1234 - 567890 - fetch12池a3bcdefg”}，“状态”：“活跃”，“统计数据”：｛“used_count”：10，“idle_count”：5，“pending_used_count”：5，“pending_idle_count”：5}，“状态”：{}}，｛“…”｝］｝
             

响应结构

字段名	类型	描述
instance_pools	的数组InstancePoolStatus	包含其统计信息的实例池列表。

数据结构

本节:

InstancePoolState

实例池的状态。当前允许的状态转换为:

活跃的->删除

的名字	描述
活跃的	表示实例池处于活动状态。集群可以附加到它。
删除	表示实例池已被删除，不再可访问。

InstancePoolStats

实例池使用情况的统计信息。

字段名	类型	描述
used_count	`INT32`	集群正在使用的活动实例的数量。
idle_count	`INT32`	集群未使用的活动实例数。
pending_used_count	`INT32`	分配给集群的挂起实例数。
pending_idle_count	`INT32`	未分配给集群的挂起实例数。

InstancePoolStatus

池中失败的挂起实例的状态。

字段名	类型	描述
pending_instance_errors	的数组PendingInstanceError	失败的挂起实例的错误消息列表。

PendingInstanceError

挂起实例失败的错误消息。

字段名	类型	描述
即instance_id	`字符串`	失败实例的ID。
消息	`字符串`	描述失败原因的消息。

DiskSpec

描述要附加到每个实例的初始磁盘集。例如，如果有3个实例，并且每个实例都配置为从2个磁盘开始，每个磁盘100 GiB，那么Databricks将为这些实例创建总共6个磁盘，每个磁盘100 GiB。

字段名

类型

描述

disk_type

DiskType

要附加的磁盘类型。

disk_count

INT32

要附加到每个实例的磁盘数量:

该特性仅对受支持的节点类型启用。
用户最多可以选择该节点类型所支持的硬盘数量。
对于没有本地磁盘的节点类型，至少需要指定一个磁盘。

disk_size

INT32

要附加的每个磁盘的大小(以GiB为单位)。值必须落在特定实例类型的支持范围内:

通用SSD: 100 - 4096 GiB
吞吐量优化HDD: 500 - 4096 GiB

DiskType

描述硬盘的类型。

字段名	类型	描述
ebs_volume_type	EbsVolumeType	要使用的EBS卷类型。

InstancePoolAndStats

字段名	类型	描述
instance_pool_name	`字符串`	实例池的名称。这是创建和编辑操作所必需的。必须唯一，非空，且长度小于100个字符。
min_idle_instances	`INT32`	由池维护的空闲实例的最小数目。这是活动集群所使用的任何实例的补充。
max_capacity	`INT32`	池可以包含的最大实例数，包括空闲实例和集群正在使用的实例。一旦达到最大容量，您就不能从池中创建新的集群，现有的集群也不能自动扩展，直到通过集群终止或降级使池中的某些实例空闲。
aws_attributes	InstancePoolAwsAttributes	与在Amazon Web Services上运行的实例池相关的属性。如果在创建时未指定，则使用一组默认值。
node_type_id	`字符串`	池中实例的节点类型。连接到池的所有集群继承此节点类型，池的空闲实例基于此类型分配。方法可以检索可用节点类型的列表列表节点类型API调用。
custom_tags	的数组ClusterTag	用于实例池资源的附加标记。Databricks除了default_tags外，还使用这些标签标记所有池资源(例如AWS实例和EBS卷)。 Databricks最多允许43个自定义标记。
idle_instance_autotermination_minutes	`INT32`	空闲实例超过的分钟数`min_idle_instances`在终止之前由池维护。如果未指定，多余的空闲实例将在默认超时时间后自动终止。如果指定，时间必须在0到10000分钟之间。如果提供0，则会尽快删除多余的空闲实例。
enable_elastic_disk	`保龄球`	自动伸缩本地存储:启用后，池中的实例在磁盘空间不足时动态地获取额外的磁盘空间。
disk_spec	DiskSpec	定义附加到池中每个实例的初始远程存储量。
preloaded_spark_versions	的数组`字符串`	包含池在每个实例上安装的运行时版本的列表。使用预加载的运行时版本的池集群启动更快，因为它们不必等待映像下载。控件可以检索可用运行时版本的列表运行时版本API调用。
instance_pool_id	`字符串`	实例池的规范唯一标识符。
default_tags	的数组ClusterTag	Databricks添加的标签，不考虑任何custom_tags，包括: 供应商:砖 DatabricksInstancePoolCreatorId: < create_user_id > DatabricksInstancePoolId: < instance_pool_id >
状态	InstancePoolState	实例池的当前状态。
统计数据	InstancePoolStats	实例池使用情况的统计信息。

InstancePoolAwsAttributes

创建实例池时设置的与Amazon Web Services相关的属性。

字段名	类型	描述
可用性	AwsAvailability	池中所有实例使用的可用性类型。只有`ON_DEMAND`而且`现货`都受支持。
zone_id	`字符串`	实例池所在的可用分区/数据中心标识符。这个字符串的形式类似于“us-west-2a”。提供的可用分区必须与Databricks部署在同一个区域。例如，如果Databricks部署在“us-east-1”区域，“us-west-2a”不是有效的zone ID。这是一个可选字段。如果不指定，则使用默认区域。属性可以找到可用分区的列表以及默认值列表区域API。
spot_bid_price_percent	`INT32`	AWS现货实例的最高价格，占相应实例类型按需价格的百分比。例如，如果该字段被设置为50，并且实例池需要一个新的`i3.xlarge`现货实例，则最高价格是按需价格的一半`i3.xlarge`实例。类似地，如果该字段设置为200，则最大价格是按需价格的两倍`i3.xlarge`实例。如果不指定，默认值为100。当此实例池请求现货实例时，只有其最大价格百分比与此字段匹配的现货实例才会被考虑。为安全起见，该字段不能大于10000。

EbsVolumeType

Databricks支持的所有EBS卷类型。看到https://aws.amazon.com/ebs/features/获取详细信息。

的名字	描述
GENERAL_PURPOSE_SSD	使用AWS gp2 EBS卷提供额外的存储。
THROUGHPUT_OPTIMIZED_HDD	使用AWS st1卷提供额外的存储空间。