群集策略 APICluster Policies APIs

重要

此功能目前以公共预览版提供。This feature is in Public Preview.

群集策略会限制基于一组规则创建群集的功能。A cluster policy limits the ability to create clusters based on a set of rules. 策略规则会限制可用于创建群集的属性或属性值。The policy rules limit the attributes or attribute values available for cluster creation. 群集策略具有将策略的使用限制到特定用户和组的 ACL。Cluster policies have ACLs that limit their use to specific users and groups.

只有管理员用户才能创建、编辑和删除策略。Only admin users can create, edit, and delete policies. 管理员用户也有权访问所有策略。Admin users also have access to all policies.

有关群集策略的要求和限制,请参阅管理群集策略For requirements and limitations on cluster policies, see Manage cluster policies.

重要

要访问 Databricks REST API,必须进行身份验证To access Databricks REST APIs, you must authenticate.

群集策略 APICluster Policies API

通过群集策略 API 可创建、列出和编辑群集策略。The Cluster Policies API allows you to create, list, and edit cluster policies. 只有管理员可以创建和编辑群及策略。Creation and editing is available to admins only. 可以由任何用户执行列表操作,并且仅限于列出该用户可访问的策略。Listing can be performed by any user and is limited to policies accessible by that user.

重要

群集策略 API 要求在 JSON 请求中以字符串化形式传递策略 JSON 定义The Cluster Policies API requires a policy JSON definition to be passed within a JSON request in stringified form. 在大多数情况下,这需要转义引号字符。In most cases this requires escaping of the quote characters.

本节内容:In this section:

获取 Get

端点Endpoint HTTP 方法HTTP Method
2.0/policies/clusters/get GET

返回给定策略 ID 的策略规范。Return a policy specification given a policy ID.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
policy_idpolicy_id STRING 要检索其信息的策略 ID。The policy ID about which to retrieve information.

响应结构 Response structure

字段名称Field Name 类型Type 描述Description
policy_idpolicy_id STRING 群集策略的规范唯一标识符。Canonical unique identifier for the cluster policy.
namename STRING 群集策略名称。Cluster policy name. 名称必须是唯一的。This must be unique. 长度必须介于 1 到 100 个字符之间。Length must be between 1 and 100 characters.
定义definition STRING 用 Databricks 策略定义语言表示的策略定义 JSON 文档。Policy definition JSON document expressed in Databricks Policy Definition Language. JSON 文档必须作为字符串传递,不能简单地嵌入到请求中。The JSON document must be passed as a string and cannot be simply embedded in the requests.
created_at_timestampcreated_at_timestamp INT64 创建时间。Creation time. 创建此群集策略时的时间戳(毫秒)。The timestamp (in millisecond) when this cluster policy was created.

列表 List

端点Endpoint HTTP 方法HTTP Method
2.0/policies/clusters/list GET

返回请求用户可访问的策略的列表。Return a list of policies accessible by the requesting user.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
sort_ordersort_order ListOrderListOrder 列出策略的顺序方向;ASCDESCThe order direction to list the policies in; either ASC or DESC. 默认为 DESCDefaults to DESC.
sort_columnsort_column PolicySortColumnPolicySortColumn 排序依据的 ClusterPolicy 属性。The ClusterPolicy attribute to sort by. 默认为 CREATION_TIMEDefaults to CREATION_TIME.

响应结构 Response structure

字段名称Field Name 类型Type 描述Description
策略policies 策略的数组An array of Policy 策略列表。List of policies.
total_counttotal_count INT64 策略总数。The total number of policies.
示例Example
{
  "policies": [
    {
      "policy_id": "ABCD000000000000",
      "name": "Test policy",
      "definition": "{\"spark_conf.spark.databricks.cluster.profile\":{\"type\":\"forbidden\",\"hidden\":true}}",
      "created_at_timestamp": 1600000000000
    }
    {
      "policy_id": "ABCD000000000001",
      "name": "Empty",
      "definition": "{}",
      "created_at_timestamp": 1600000000002
    }
  ],
  "total_count": 1
}

创建 Create

端点Endpoint HTTP 方法HTTP Method
2.0/policies/clusters/create POST

使用给定的名称和定义创建新策略。Create a new policy with a given name and definition.

请求结构 Request structure

字段名称Field Name 类型Type 说明Description
namename STRING 群集策略名称。Cluster policy name. 名称必须是唯一的。This must be unique. 长度必须介于 1 到 100 个字符之间。Length must be between 1 and 100 characters.
定义definition STRING 用 Databricks 策略定义语言表示的策略定义 JSON 文档。Policy definition JSON document expressed in Databricks Policy Definition Language. 必须将 JSON 文档作为字符串传递;不能简单地嵌入到请求中。You must pass the JSON document as a string; it cannot be simply embedded in the requests.
示例Example
{
  "name": "Example Policy",
  "definition": "{\"spark_version\":{\"type\":\"fixed\",\"value\":\"next-major-version-scala2.12\",\"hidden\":true}}"
}

响应结构 Response structure

字段名称Field Name 类型Type 描述Description
policy_idpolicy_id STRING 群集策略的规范唯一标识符。Canonical unique identifier for the cluster policy.
示例Example
{
  "policy_id": "ABCD000000000000",
}

编辑 Edit

端点Endpoint HTTP 方法HTTP Method
2.0/policies/clusters/edit POST

更新现有策略。Update an existing policy. 这可能会使此策略控制的某些群集无效。This may make some clusters governed by this policy invalid. 对于此类群集,下一次群集编辑必须提供确认配置,但即使不这么也能继续运行。For such clusters the next cluster edit must provide a confirming configuration, but otherwise they can continue to run.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
policy_idpolicy_id STRING 要更新的策略的 ID。The ID of the policy to update. 此字段为必需字段。This field is required.
namename STRING 群集策略名称。Cluster policy name. 名称必须是唯一的。This must be unique. 长度必须介于 1 到 100 个字符之间。Length must be between 1 and 100 characters.
定义definition STRING 用 Databricks 策略定义语言表示的策略定义 JSON 文档。Policy definition JSON document expressed in Databricks Policy Definition Language. 必须将 JSON 文档作为字符串传递;不能简单地嵌入到请求中。You must pass the JSON document as a string; it cannot be simply embedded in the requests.
示例Example
{
  "policy_id": "ABCD000000000000",
  "name": "Example Policy",
  "definition": "{\"spark_version\":{\"type\":\"fixed\",\"value\":\"next-major-version-scala2.12\",\"hidden\":true}}"
}

删除 Delete

端点Endpoint HTTP 方法HTTP Method
2.0/policies/clusters/delete POST

删除策略。Delete a policy. 此策略控制的群集仍可运行,但无法编辑。Clusters governed by this policy can still run, but cannot be edited.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
policy_idpolicy_id STRING 要删除的策略的 ID。The ID of the policy to delete. 此字段为必需字段。This field is required.
示例Example
{
  "policy_id": "ABCD000000000000"
}

数据结构 Data structures

本节内容:In this section:

策略 Policy

群集策略实体。A cluster policy entity.

字段名称Field Name 类型Type 描述Description
policy_idpolicy_id STRING 群集策略的规范唯一标识符。Canonical unique identifier for the cluster policy.
namename STRING 群集策略名称。Cluster policy name. 名称必须是唯一的。This must be unique. 长度必须介于 1 到 100 个字符之间。Length must be between 1 and 100 characters.
定义definition STRING 用 Databricks 策略定义语言表示的策略定义 JSON 文档。Policy definition JSON document expressed in Databricks Policy Definition Language. 必须将 JSON 文档作为字符串传递;不能简单地嵌入到请求中。You must pass the JSON document as a string; it cannot be simply embedded in the requests.
creator_user_namecreator_user_name STRING 创建者用户名。Creator user name. 如果已删除用户,则该字段不会包含在响应中。The field won’t be included in the response if the user has already been deleted.
created_at_timestampcreated_at_timestamp INT64 创建时间。Creation time. 创建此群集策略时的时间戳(毫秒)。The timestamp (in millisecond) when this cluster policy was created.

PolicySortColumn PolicySortColumn

ListPolices 请求的排序顺序。The sort order for the ListPolices request.

名称Name 描述Description
POLICY_CREATION_TIMEPOLICY_CREATION_TIME 按策略创建类型对结果列表进行排序。Sort result list by policy creation type.
POLICY_NAMEPOLICY_NAME 按策略名称对结果列表进行排序。Sort result list by policy name.

群集策略权限 APICluster Policy Permissions API

使用群集策略权限 API,可以设置群集策略的权限。The Cluster Policy Permissions API enables you to set permissions on a cluster policy. 向用户授予策略的 CAN_USE 权限时,该用户将能够基于该权限创建新群集。When you grant CAN_USE permission on a policy to a user, the user will be able to create new clusters based on it. 用户不需要 cluster_create 权限来创建新的群集。A user does not need the cluster_create permission to create new clusters.

只有管理员用户可以设置群集策略的权限。Only admin users can set permissions on cluster policies.

在以下终结点中,<basepath> = /api/2.0/previewIn the following endpoints, <basepath> = /api/2.0/preview.

本节内容:In this section:

获取权限 Get permissions

端点Endpoint HTTP 方法HTTP Method
<basepath>/permissions/cluster-policies/<clusterPolicyId>/permissionLevels GET

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
clusterPolicyIdclusterPolicyId STRING 要检索其权限的策略。The policy about which to retrieve permissions. 此字段为必需字段。This field is required.

响应结构 Response structure

群集 ACLA Clusters ACL.

示例响应Example response

{
  "object_id": "/cluster-policies/D55CAFDD8E00002B",
  "object_type": "cluster-policy",
  "access_control_list": [
    {
      "user_name": "user@mydomain.com",
      "all_permissions": [
        {
          "permission_level": "CAN_USE",
          "inherited": false
        },
      ]
    },
    {
      "group_name": "admins",
      "all_permissions": [
        {
          "permission_level": "CAN_USE",
          "inherited": true,
          "inherited_from_object": [
              "/cluster-policies/"
          ]
        }
      ]
    },
  ]
}

添加或修改权限Add or modify permissions

端点Endpoint HTTP 方法HTTP Method
<basepath>/permissions/cluster-policies/<clusterPolicyId> PATCH

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
clusterPolicyIdclusterPolicyId STRING 要修改其权限的策略。The policy about which to modify permissions. 此字段为必需字段。This field is required.

请求正文 Request body

字段名称Field Name 类型Type 描述Description
access_control_listaccess_control_list AccessControl 的数组Array of AccessControl 访问控制列表的数组。An array of access control lists.

响应正文Response body

与对 <clusterPolicyId> 执行的 GET 调用相同,返回已修改的群集权限。Same as a GET call on <clusterPolicyId>, returns back modified permissions for cluster.

设置或删除权限Set or delete permissions

PUT 请求替代群集策略对象上的所有直接权限。A PUT request replaces all direct permissions on the cluster policy object. 发出删除请求的方法是发出请求检索当前权限列表的 GET 请求,然后发出请求删除所需条目的 PUT 请求。You can make delete requests by making a GET request to retrieve the current list of permissions followed by a PUT request removing entries to be deleted.

端点Endpoint HTTP 方法HTTP Method
<basepath>/permissions/cluster-policies/<clusterPolicyId> PUT

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
clusterPolicyIdclusterPolicyId STRING 要设置其权限的策略。The policy about which to set permissions. 此字段为必需字段。This field is required.

请求正文Request body

字段名称Field Name 类型Type 描述Description
access_control_listaccess_control_list AccessControlInput 的数组Array of AccessControlInput 访问控制的数组。An array of access controls.

响应正文 Response body

与对 <clusterPolicyId> 执行的 GET 调用相同,返回已修改的群集权限。Same as a GET call on <clusterPolicyId>, returns back modified permissions for cluster.

数据结构Data structures

本节内容:In this section:

群集 ACL Clusters ACL

属性名称Attribute Name 类型Type 描述Description
object_idobject_id STRINGSTRING ACL 对象的 ID,例如 ../cluster-policies/<clusterPolicyId>The ID of the ACL object, for example, ../cluster-policies/<clusterPolicyId>.
object_typeobject_type STRINGSTRING Databricks ACL 对象类型,例如 cluster-policyThe Databricks ACL object type, for example, cluster-policy.
access_control_listaccess_control_list AccessControl 的数组Array of AccessControl ACL 对象上设置的访问控制。The access controls set on the ACL object.

AccessControl AccessControl

属性名称Attribute Name 类型Type 描述Description
user_name 或 group_nameuser_name OR group_name STRINGSTRING 在 ACL 对象上设置了权限的主体(用户或组)的名称。Name of the principal (user or group) that has permissions set on the ACL object.
all_permissionsall_permissions 权限的数组Array of Permission 在此 ACL 对象上为特定主体设置的所有权限的列表。List of all permissions set on this ACL object for a specific principal. 既包括直接在此 ACL 对象上设置的权限,也包括从上级 ACL 对象继承的权限。Includes both permissions directly set on this ACL object and permissions inherited from an ancestor ACL object.

权限 Permission

属性名称Attribute Name 类型Type 描述Description
permission_levelpermission_level STRINGSTRING 权限级别的名称。The name of the permission level.
已继承inherited BOOLEANBOOLEAN 如果不是直接设置 ACL 权限而是继承自上级 ACL 对象,则为 True。True when the ACL permission is not set directly but inherited from an ancestor ACL object. 如果是直接在 ACL 对象上设置,则为 False。False if set directly on the ACL object.
inherited_from_objectinherited_from_object List[STRING]List[STRING] ACL 对象的继承权限所涉及的父 ACL 对象 ID 列表。The list of parent ACL object IDs that contribute to inherited permission on an ACL object. 仅当继承为 true 时才定义此值。This is defined only if inherited is true.

AccessControlInput AccessControlInput

代表应用于主体(用户或组)的 ACL 规则的项。An item representing an ACL rule applied to the principal (user or group).

属性名称Attribute Name 类型Type 描述Description
user_name 或 group_nameuser_name OR group_name STRINGSTRING 在 ACL 对象上设置了权限的主体(用户或组)的名称。Name of the principal (user or group) that has permissions set on the ACL object.
permission_levelpermission_level STRINGSTRING 权限级别的名称。The name of the permission level.

PermissionLevelPermissionLevel

可以在群集策略上设置的权限级别。Permission level that you can set on a cluster policy.

权限级别Permission Level 描述Description
CAN_USECAN_USE 允许用户基于策略创建群集。Allow user to create clusters based on the policy. 用户无需群集创建权限。The user does not need the cluster create permission.