机密 APISecrets API

可使用机密 API 来管理机密、机密范围和访问权限。The Secrets API allows you to manage secrets, secret scopes, and access permissions. 若要管理机密,必须:To manage secrets, you must:

  1. 创建机密范围Create a secret scope.
  2. 将机密添加到范围中Add your secrets to the scope.
  3. 如果你具有 Azure Databricks 高级计划,请将访问控制分配到机密范围中If you have the Azure Databricks Premium Plan, assign access control to the secret scope.

若要详细了解如何创建和管理机密,请参阅机密管理To learn more about creating and managing secrets, see Secret management. 使用机密实用工具在笔记本和作业中访问和引用机密。You access and reference secrets in notebooks and jobs by using Secrets utilities.

重要

要访问 Databricks REST API,必须进行身份验证To access Databricks REST APIs, you must authenticate. 若要将机密 API 与 Azure Key Vault 机密一起使用,必须使用 Azure Active Directory 令牌进行身份验证。To use the Secrets API with Azure Key Vault secrets, you must authenticate using an Azure Active Directory token.

创建机密范围 Create secret scope

端点Endpoint HTTP 方法HTTP Method
2.0/secrets/scopes/create POST

可以:You can either:

  • 创建 Azure Key Vault 支持的范围,其中机密存储在 Azure 管理的存储中,并使用基于云的特定加密密钥进行加密。Create an Azure Key Vault-backed scope in which secrets are stored in Azure-managed storage and encrypted with a cloud-based specific encryption key.
  • 创建 Databricks 支持的机密范围,其中机密存储在 Databricks 管理的存储中,并使用基于云的特定加密密钥进行加密。Create a Databricks-backed secret scope in which secrets are stored in Databricks-managed storage and encrypted with a cloud-based specific encryption key.

创建 Azure Key Vault 支持的范围Create an Azure Key Vault-backed scope

范围名称:The scope name:

  • 在工作区中必须唯一。Must be unique within a workspace.
  • 必须包含字母数字字符、短划线、下划线和句点,并且不得超过 128 个字符。Must consist of alphanumeric characters, dashes, underscores, and periods, and may not exceed 128 characters.

这些名称被视为是非敏感信息,工作区中的所有用户都可读取它们。The names are considered non-sensitive and are readable by all users in the workspace. 一个工作区最多只能有 100 个机密范围。A workspace is limited to a maximum of 100 secret scopes.

示例请求:Example request:

{
  "scope": "my-simple-azure-keyvault-scope",
  "scope_backend_type": "AZURE_KEYVAULT",
  "backend_azure_keyvault":
  {
    "resource_id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azure-rg/providers/Microsoft.KeyVault/vaults/my-azure-kv",
    "dns_name": "https://my-azure-kv.vault.azure.net/"
  },
  "initial_manage_principal": "users"
}

如果已指定 initial_manage_principal,则应用于该范围的初始 ACL 将应用到所提供的具有 MANAGE 权限的主体(用户或组)。If initial_manage_principal is specified, the initial ACL applied to the scope is applied to the supplied principal (user or group) with MANAGE permissions. 此选项唯一支持的主体是 users 组,其中包含工作区中的所有用户。The only supported principal for this option is the group users, which contains all users in the workspace. 如果未指定 initial_manage_principal,则会将应用于该范围的具有 MANAGE 权限的初始 ACL 分配给 API 请求颁发者的用户标识。If initial_manage_principal is not specified, the initial ACL with MANAGE permission applied to the scope is assigned to the API request issuer’s user identity.

如果具有指定名称的范围已存在,会引发 RESOURCE_ALREADY_EXISTSThrows RESOURCE_ALREADY_EXISTS if a scope with the given name already exists. 如果超出工作区中的最大范围数,会引发 RESOURCE_LIMIT_EXCEEDEDThrows RESOURCE_LIMIT_EXCEEDED if maximum number of scopes in the workspace is exceeded. 如果范围名称无效,则会引发 INVALID_PARAMETER_VALUEThrows INVALID_PARAMETER_VALUE if the scope name is invalid.

创建 Databricks 支持的机密范围Create a Databricks-backed secret scope

范围名称:The scope name:

  • 在工作区中必须唯一。Must be unique within a workspace.
  • 必须包含字母数字字符、短划线、下划线和句点,并且不得超过 128 个字符。Must consist of alphanumeric characters, dashes, underscores, and periods, and may not exceed 128 characters.

这些名称被视为是非敏感信息,工作区中的所有用户都可读取它们。The names are considered non-sensitive and are readable by all users in the workspace. 一个工作区最多只能有 100 个机密范围。A workspace is limited to a maximum of 100 secret scopes.

示例请求:Example request:

{
  "scope": "my-simple-databricks-scope",
  "initial_manage_principal": "users"
}

如果已指定 initial_manage_principal,则应用于该范围的初始 ACL 将应用到所提供的具有 MANAGE 权限的主体(用户或组)。If initial_manage_principal is specified, the initial ACL applied to the scope is applied to the supplied principal (user or group) with MANAGE permissions. 此选项唯一支持的主体是 users 组,其中包含工作区中的所有用户。The only supported principal for this option is the group users, which contains all users in the workspace. 如果未指定 initial_manage_principal,则会将应用于该范围的具有 MANAGE 权限的初始 ACL 分配给 API 请求颁发者的用户标识。If initial_manage_principal is not specified, the initial ACL with MANAGE permission applied to the scope is assigned to the API request issuer’s user identity.

如果具有指定名称的范围已存在,会引发 RESOURCE_ALREADY_EXISTSThrows RESOURCE_ALREADY_EXISTS if a scope with the given name already exists. 如果超出工作区中的最大范围数,会引发 RESOURCE_LIMIT_EXCEEDEDThrows RESOURCE_LIMIT_EXCEEDED if maximum number of scopes in the workspace is exceeded. 如果范围名称无效,则会引发 INVALID_PARAMETER_VALUEThrows INVALID_PARAMETER_VALUE if the scope name is invalid.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
scopescope STRING 用户请求的范围名称。Scope name requested by the user. 范围名称是唯一的。Scope names are unique. 此字段为必需字段。This field is required.
initial_manage_principalinitial_manage_principal STRING 最初就所创建的范围获得 MANAGE 权限的主体。The principal that is initially granted MANAGE permission to the created scope.

删除机密范围 Delete secret scope

端点Endpoint HTTP 方法HTTP Method
2.0/secrets/scopes/delete POST

删除机密范围。Delete a secret scope.

示例请求:Example request:

{
  "scope": "my-secret-scope"
}

如果范围不存在,会引发 RESOURCE_DOES_NOT_EXISTThrows RESOURCE_DOES_NOT_EXIST if the scope does not exist. 如果用户没有进行此 API 调用的权限,则会引发 PERMISSION_DENIEDThrows PERMISSION_DENIED if the user does not have permission to make this API call.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
scopescope STRING 要删除的范围的名称。Name of the scope to delete. 此字段为必需字段。This field is required.

列出机密范围 List secret scopes

端点Endpoint HTTP 方法HTTP Method
2.0/secrets/scopes/list GET

列出工作区中所有可用的机密范围。List all secret scopes available in the workspace.

示例响应:Example response:

{
  "scopes": [{
      "name": "my-databricks-scope",
      "backend_type": "DATABRICKS"
  },{
      "name": "mount-points",
      "backend_type": "DATABRICKS"
  }]
}

如果你没有进行此 API 调用的权限,会引发 PERMISSION_DENIEDThrows PERMISSION_DENIED if you do not have permission to make this API call.

响应结构 Response structure

字段名称Field Name 类型Type 描述Description
范围scopes SecretScope 的数组An array of SecretScope 可用的机密范围。The available secret scopes.

放置机密 Put secret

机密的创建/修改方法由范围后端的类型决定。The method for creating or modifying a secret depends on the type of scope backend. 若要在 Azure Key Vault 支持的范围中创建或修改机密,请使用 Azure SetSecret REST API。To create or modify a secret in a scope backed by Azure Key Vault, use the Azure SetSecret REST API. 若要创建或修改 Databricks 支持的范围中的机密,请使用以下终结点:To create or modify a secret from a Databricks-backed scope, use the following endpoint:

端点Endpoint HTTP 方法HTTP Method
2.0/secrets/put POST

在提供的具有指定名称的范围下插入机密。Insert a secret under the provided scope with the given name. 如果已存在同名的机密,此命令将覆盖现有机密的值。If a secret already exists with the same name, this command overwrites the existing secret’s value. 服务器在存储机密之前,会使用机密范围的加密设置对它进行加密。The server encrypts the secret using the secret scope’s encryption settings before storing it. 你必须对机密范围具有 WRITEMANAGE 权限。You must have WRITE or MANAGE permission on the secret scope.

密钥必须包含字母数字字符、短划线、下划线和句点,且不得超过 128 个字符。The secret key must consist of alphanumeric characters, dashes, underscores, and periods, and cannot exceed 128 characters. 允许的最大机密值大小为 128 KB。The maximum allowed secret value size is 128 KB. 指定范围内的最大机密数为The maximum number of secrets in a given scope is 1000.

只能从群集上的命令中读取机密值(例如通过笔记本);没有用于读取群集外部的机密值的 API。You can read a secret value only from within a command on a cluster (for example, through a notebook); there is no API to read a secret value outside of a cluster. 应用的权限取决于调用命令的用户,而且你必须至少具有 READ 权限。The permission applied is based on who is invoking the command and you must have at least READ permission.

示例请求:Example request:

{
  "scope": "my-databricks-scope",
  "key": "my-string-key",
  "string_value": "foobar"
}

“string_value”或“bytes_value”输入字段会指定机密的类型,此类型将决定请求机密值时返回的值。The input fields “string_value” or “bytes_value” specify the type of the secret, which will determine the value returned when the secret value is requested. 必须恰好指定一个类型。Exactly one must be specified.

如果没有这种机密范围,会引发 RESOURCE_DOES_NOT_EXISTThrows RESOURCE_DOES_NOT_EXIST if no such secret scope exists. 如果超出范围内的最大机密数,会引发 RESOURCE_LIMIT_EXCEEDEDThrows RESOURCE_LIMIT_EXCEEDED if maximum number of secrets in scope is exceeded. 如果密钥名称或值的长度无效,会引发 INVALID_PARAMETER_VALUEThrows INVALID_PARAMETER_VALUE if the key name or value length is invalid. 如果用户没有进行此 API 调用的权限,则会引发 PERMISSION_DENIEDThrows PERMISSION_DENIED if the user does not have permission to make this API call.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
string_value 或 bytes_valuestring_value OR bytes_value STRINGBYTESSTRING OR BYTES 使用指定为 string_value,则值将以 UTF-8 (MB4) 格式存储。If string_value, if specified, the value will be stored in UTF-8 (MB4) form.

如果指定为 bytes_value,则值将存储为字节。If bytes_value, if specified, value will be stored as bytes.
scopescope STRING 将与机密关联的范围的名称。The name of the scope to which the secret will be associated with. 此字段为必需字段。This field is required.
keykey STRING 用于标识机密的唯一名称。A unique name to identify the secret. 此字段为必需字段。This field is required.

删除机密 Delete secret

机密的删除方法由范围后端的类型决定。The method for deleting a secret depends on the type of scope backend. 若要从 Azure Key Vault 支持的范围中删除机密,请使用 Azure SetSecret REST API。To delete a secret from a scope backed by Azure Key Vault, use the Azure SetSecret REST API. 若要删除 Databricks 支持的范围中的机密,请使用以下终结点:To delete a secret from a Databricks-backed scope, use the following endpoint:

端点Endpoint HTTP 方法HTTP Method
2.0/secrets/delete POST

删除存储在此机密范围中的机密。Delete the secret stored in this secret scope. 你必须对机密范围具有 WRITEMANAGE 权限。You must have WRITE or MANAGE permission on the secret scope.

示例请求:Example request:

{
  "scope": "my-secret-scope",
  "key": "my-secret-key"
}

如果没有这种机密范围或机密,会引发 RESOURCE_DOES_NOT_EXISTThrows RESOURCE_DOES_NOT_EXIST if no such secret scope or secret exists. 如果你没有进行此 API 调用的权限,会引发 PERMISSION_DENIEDThrows PERMISSION_DENIED if you do not have permission to make this API call.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
scopescope STRING 包含要删除的机密的范围的名称。The name of the scope that contains the secret to delete. 此字段为必需字段。This field is required.
keykey STRING 要删除的机密的名称。Name of the secret to delete. 此字段为必需字段。This field is required.

列出机密 List secrets

端点Endpoint HTTP 方法HTTP Method
2.0/secrets/list GET

列出在此范围中存储的密钥。List the secret keys that are stored at this scope. 这是一项仅限元数据的操作;无法使用此 API 检索机密数据。This is a metadata-only operation; you cannot retrieve secret data using this API. 必须具有 READ 权限才能进行此调用。You must have READ permission to make this call.

示例响应:Example response:

{
  "secrets": [
    {
      "key": "my-string-key",
      "last_updated_timestamp": 1520467595000
    },
    {
      "key": "my-byte-key",
      "last_updated_timestamp": 1520467595000
    }
  ]
}

从 epoch 开始,返回的 last_updated_timestamp 以毫秒为单位。The last_updated_timestamp returned is in milliseconds since epoch.

如果没有这种机密范围,会引发 RESOURCE_DOES_NOT_EXISTThrows RESOURCE_DOES_NOT_EXIST if no such secret scope exists. 如果你没有进行此 API 调用的权限,会引发 PERMISSION_DENIEDThrows PERMISSION_DENIED if you do not have permission to make this API call.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
scopescope STRING 要列出其机密的范围的名称。The name of the scope whose secrets you want to list. 此字段为必需字段。This field is required.

响应结构 Response structure

字段名称Field Name 类型Type 描述Description
secretssecrets SecretMetadata 的数组An array of SecretMetadata 指定范围内包含的所有机密的元数据信息。Metadata information of all secrets contained within the given scope.

放置机密 ACL Put secret ACL

端点Endpoint HTTP 方法HTTP Method
2.0/secrets/acls/put POST

在指定范围点上创建或覆盖与给定主体(用户或组)相关联的 ACL。Create or overwrite the ACL associated with the given principal (user or group) on the specified scope point. 通常,用户或组将使用其可用的最强大的权限,这些权限的排序如下:In general, a user or group will use the most powerful permission available to them, and permissions are ordered as follows:

  • MANAGE - 允许更改 ACL,并在此机密范围进行读取和写入。MANAGE - Allowed to change ACLs, and read and write to this secret scope.
  • WRITE - 允许在此机密范围进行读取和写入。WRITE - Allowed to read and write to this secret scope.
  • READ - 允许读取此机密范围并列出哪些机密可用。READ - Allowed to read this secret scope and list what secrets are available.

必须具有 MANAGE 权限才能调用此 API。You must have the MANAGE permission to invoke this API.

示例请求:Example request:

{
  "scope": "my-secret-scope",
  "principal": "data-scientists",
  "permission": "READ"
}

主体是与要授予或撤销访问权限的现有 Azure Databricks 主体相对应的用户名或组名。The principal is a user or group name corresponding to an existing Azure Databricks principal to be granted or revoked access.

如果没有这种机密范围,会引发 RESOURCE_DOES_NOT_EXISTThrows RESOURCE_DOES_NOT_EXIST if no such secret scope exists. 如果主体的权限已存在,会引发 RESOURCE_ALREADY_EXISTSThrows RESOURCE_ALREADY_EXISTS if a permission for the principal already exists. 如果权限无效,会引发 INVALID_PARAMETER_VALUEThrows INVALID_PARAMETER_VALUE if the permission is invalid. 如果你没有进行此 API 调用的权限,会引发 PERMISSION_DENIEDThrows PERMISSION_DENIED if you do not have permission to make this API call.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
scopescope STRING 要向其应用权限的范围的名称。The name of the scope to apply permissions to. 此字段为必需字段。This field is required.
主体principal STRING 要应用权限的主体。The principal to which the permission is applied. 此字段为必需字段。This field is required.
权限 (permission)permission AclPermissionAclPermission 应用于主体的权限级别。The permission level applied to the principal. 此字段为必需字段。This field is required.

删除机密 ACL Delete secret ACL

端点Endpoint HTTP 方法HTTP Method
2.0/secrets/acls/delete POST

删除给定范围上的给定 ACL。Delete the given ACL on the given scope.

必须具有 MANAGE 权限才能调用此 API。You must have the MANAGE permission to invoke this API.

示例请求:Example request:

{
  "scope": "my-secret-scope",
  "principal": "data-scientists"
}

如果没有这种机密范围、主体或 ACL,会引发 RESOURCE_DOES_NOT_EXISTThrows RESOURCE_DOES_NOT_EXIST if no such secret scope, principal, or ACL exists. 如果你没有进行此 API 调用的权限,会引发 PERMISSION_DENIEDThrows PERMISSION_DENIED if you do not have permission to make this API call.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
scopescope STRING 要从中删除权限的范围的名称。The name of the scope to remove permissions from. 此字段为必需字段。This field is required.
主体principal STRING 要从中删除现有 ACL 的主体。The principal to remove an existing ACL from. 此字段为必需字段。This field is required.

获取机密 ACL Get secret ACL

端点Endpoint HTTP 方法HTTP Method
2.0/secrets/acls/get GET

介绍有关给定 ACL 的详细信息,例如组和权限。Describe the details about the given ACL, such as the group and permission.

必须具有 MANAGE 权限才能调用此 API。You must have the MANAGE permission to invoke this API.

示例响应:Example response:

{
  "principal": "data-scientists",
  "permission": "READ"
}

如果没有这种机密范围,会引发 RESOURCE_DOES_NOT_EXISTThrows RESOURCE_DOES_NOT_EXIST if no such secret scope exists. 如果你没有进行此 API 调用的权限,会引发 PERMISSION_DENIEDThrows PERMISSION_DENIED if you do not have permission to make this API call.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
scopescope STRING 要从中提取 ACL 信息的范围的名称。The name of the scope to fetch ACL information from. 此字段为必需字段。This field is required.
主体principal STRING 要为其提取 ACL 信息的主体。The principal to fetch ACL information for. 此字段为必需字段。This field is required.

响应结构 Response structure

字段名称Field Name 类型Type 描述Description
主体principal STRING 要应用权限的主体。The principal to which the permission is applied. 此字段为必需字段。This field is required.
权限 (permission)permission AclPermissionAclPermission 应用于主体的权限级别。The permission level applied to the principal. 此字段为必需字段。This field is required.

列出机密 ACL List secret ACLs

端点Endpoint HTTP 方法HTTP Method
2.0/secrets/acls/list GET

列出在给定范围上设置的 ACL。List the ACLs set on the given scope.

必须具有 MANAGE 权限才能调用此 API。You must have the MANAGE permission to invoke this API.

示例响应:Example response:

{
  "items": [
    {
        "principal": "admins",
        "permission": "MANAGE"
    },{
        "principal": "data-scientists",
        "permission": "READ"
    }
  ]
}

如果没有这种机密范围,会引发 RESOURCE_DOES_NOT_EXISTThrows RESOURCE_DOES_NOT_EXIST if no such secret scope exists. 如果你没有进行此 API 调用的权限,会引发 PERMISSION_DENIEDThrows PERMISSION_DENIED if you do not have permission to make this API call.

请求结构 Request structure

字段名称Field Name 类型Type 描述Description
scopescope STRING 要从中提取 ACL 信息的范围的名称。The name of the scope to fetch ACL information from. 此字段为必需字段。This field is required.

响应结构 Response structure

字段名称Field Name 类型Type 描述Description
itemsitems AclItem 的数组An array of AclItem 应用于给定范围内的主体的关联 ACL 规则。The associated ACLs rule applied to principals in the given scope.

数据结构Data structures

本节内容:In this section:

AclItem AclItem

一个表示在关联范围点上应用于给定主体(用户或组)的 ACL 规则的项。An item representing an ACL rule applied to the given principal (user or group) on the associated scope point.

字段名称Field Name 类型Type 描述Description
主体principal STRING 要应用权限的主体。The principal to which the permission is applied. 此字段为必需字段。This field is required.
权限 (permission)permission AclPermissionAclPermission 应用于主体的权限级别。The permission level applied to the principal. 此字段为必需字段。This field is required.

SecretMetadata SecretMetadata

有关机密的元数据。The metadata about a secret. 列出机密时返回。Returned when listing secrets. 不包含实际的机密值。Does not contain the actual secret value.

字段名称Field Name 类型Type 描述Description
keykey STRING 用于标识机密的唯一名称。A unique name to identify the secret.
last_updated_timestamplast_updated_timestamp INT64 机密的上次更新时间戳(以毫秒为单位)。The last updated timestamp (in milliseconds) for the secret.

SecretScope SecretScope

用于存储机密的组织资源。An organizational resource for storing secrets. 机密范围可以是不同的类型,而且可将 ACL 应用于范围内所有机密的控制权限。Secret scopes can be different types, and ACLs can be applied to control permissions for all secrets within a scope.

字段名称Field Name 类型Type 说明Description
namename STRING 用于标识机密范围的唯一名称。A unique name to identify the secret scope.
backend_typebackend_type ScopeBackendTypeScopeBackendType 机密范围后端的类型。The type of secret scope backend.

AclPermission AclPermission

应用于机密范围的机密 ACL 的 ACL 权限级别。The ACL permission levels for secret ACLs applied to secret scopes.

权限Permission 说明Description
READREAD 允许对此范围中的机密执行读取操作(获取和列出)。Allowed to perform read operations (get, list) on secrets in this scope.
WRITEWRITE 允许在此机密范围对机密进行读取和写入。Allowed to read and write secrets to this secret scope.
管理MANAGE 允许读取/写入 ACL 以及在此机密范围对机密进行读取/写入。Allowed to read/write ACLs, and read/write secrets to this secret scope.

ScopeBackendType ScopeBackendType

机密范围后端的类型。The type of secret scope backend.

类型Type 描述Description
AZURE_KEYVAULTAZURE_KEYVAULT 将机密存储在 Azure Key Vault 中的机密范围。A secret scope in which secrets are stored in an Azure Key Vault.
DATABRICKSDATABRICKS 将机密存储在 Databricks 管理的存储中,并使用基于云的特定加密密钥进行加密的机密范围。A secret scope in which secrets are stored in Databricks managed storage and encrypted with a cloud-based specific encryption key.