クラスター ポリシー 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 TypeType 説明Description
policy_idpolicy_id STRING 情報を取得する対象のポリシー ID。The policy ID about which to retrieve information.

応答構造体 Response structure

フィールド名Field Name TypeType 説明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 ポリシー定義 JSON ドキュメントは、Databricks ポリシー定義言語で表現されています。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 TypeType 説明Description
sort_ordersort_order ListOrderListOrder ポリシーを一覧表示する順序の方向です。 ASC または DESC のいずれかです。The order direction to list the policies in; either ASC or DESC. 既定値は DESC です。Defaults to DESC.
sort_columnsort_column PolicySortColumnPolicySortColumn 並べ替えの基準となる ClusterPolicy 属性。The ClusterPolicy attribute to sort by. 既定値は CREATION_TIME です。Defaults to CREATION_TIME.

応答構造体 Response structure

フィールド名Field Name TypeType 説明Description
policiespolicies ポリシーの配列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 TypeType 説明Description
namename STRING クラスターポリシー名。Cluster policy name. これは一意である必要があります。This must be unique. 長さは 1 ~ 100 文字にする必要があります。Length must be between 1 and 100 characters.
定義definition STRING ポリシー定義 JSON ドキュメントは、Databricks ポリシー定義言語で表現されています。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 TypeType 説明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 TypeType 説明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 ポリシー定義 JSON ドキュメントは、Databricks ポリシー定義言語で表現されています。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 TypeType 説明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 TypeType 説明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 ポリシー定義 JSON ドキュメントは、Databricks ポリシー定義言語で表現されています。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

要求の並べ替え順序 ListPolicesThe 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/preview です。In 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 TypeType 説明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 TypeType 説明Description
clusterPolicyIdclusterPolicyId STRING アクセス許可を変更する対象のポリシー。The policy about which to modify permissions. このフィールドは必須です。This field is required.

要求本文 Request body

フィールド名Field Name TypeType 説明Description
access_control_listaccess_control_list Accesscontrol-namespaceの配列Array of AccessControl アクセス制御リストの配列。An array of access control lists.

応答本文Response body

の GET 呼び出しと同じように <clusterPolicyId> 、クラスターの変更されたアクセス許可を返します。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 TypeType 説明Description
clusterPolicyIdclusterPolicyId STRING アクセス許可を設定する対象のポリシー。The policy about which to set permissions. このフィールドは必須です。This field is required.

要求本文Request body

フィールド名Field Name TypeType 説明Description
access_control_listaccess_control_list Accesscontrolinputの配列Array of AccessControlInput アクセス制御の配列。An array of access controls.

応答本文 Response body

の GET 呼び出しと同じように <clusterPolicyId> 、クラスターの変更されたアクセス許可を返します。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-namespaceの配列Array of AccessControl ACL オブジェクトに設定されているアクセス制御。The access controls set on the ACL object.

Accesscontrol-namespace 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.

Access制御 linput 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.