统一目录API 2.1规范

目的和范围

本文档给出了Unity Catalog (UC) 2.1 API的紧凑规范,重点关注组成UC公共API的消息和端点。Delta Sharing API也在范围之内。

以下领域是本文件涵盖:

术语

用户类型

所有访问Unity的用户目录api必须是帐户级用户。它们还必须被添加到相关的Databricks工作区(以获得用于访问UC API服务器的PAT令牌)。

Metastore管理员

Metastore Admins可以管理Metastore内所有可安全对象的特权,例如谁可以创建目录或查询表。有关Metastore管理角色的更多详细信息,请阅读在Unity目录中管理权限

账户管理员

帐户管理员是帐户级别的用户,具有在帐户控制台中配置的“帐户所有者”角色。欲了解更多细节,请阅读Unity目录中的管理员权限

客户端类型

Unity Catalog的API服务器可以通过外部客户端访问。这些客户端使用“外部”令牌进行身份验证(例如,从工作区获得的PAT令牌)。这是一个重要的区别。你必须首先获得一个个人存取令牌(PAT)从外部客户端访问Unity Catalog API。这包括使用Databricks CLIunity-catalog命令访问UC API。

API的约定

API使用说明

常用数据模型

属性

目录模式而且表格每个对象都有一个属性字段,它是键值对的不透明列表。这个列表允许将来扩展或自定义对象的配置。

字段名

类型

描述

属性

地图(字符串,字符串)

可扩展的目录属性

公共api

本节中的API端点供外部客户机使用。这些API端点对Unity Catalog对象强制执行权限,这样客户端用户只能访问他们拥有权限的对象。

Metastore CRUD API

对象模型

DeltaSharingScope

的支持值delta_sharing_scope字段(在MetastoreInfo)为以下字符串:


MetastoreInfo:

字段名

类型

创建

更新

描述

的名字

字符串

要求的事情

选择

亚转移瘤名称

storage_root

字符串(url)

要求的事情

犯错

Metastore存储根路径。在创建时,新的亚metastore的ID (UUID)被追加到所提供的storage_root,那么输出storage_root和输入不一样吗storage_root

default_data_access_config_id
(弃用)

字符串(uuid)

IGN

选择

用于在Metastore中为对象创建访问令牌的默认DataAccessConfiguration的唯一标识符。现在被storage_root_credential_id

storage_root_credential_id

字符串(uuid)

IGN

选择

存储凭据的唯一标识符,默认情况下用于访问storage_root云存储面积。

老板

字符串

IGN[1]

选择

Metastore所有者的用户名/组名

delta_sharing_enabled(弃用)

保龄球

IGN

选择

是否为该Metastore启用增量共享(默认值:

delta_sharing_scope

字符串(DeltaSharingScope)

IGN

选择

增量共享作用域(默认为INTERNAL)。

delta_sharing_recipient_token_lifetime_in_seconds

int32

IGN

选择

一生δ以秒为单位共享接收方令牌(无默认值;必须在以下情况下指定delta_sharing_scope设置为INTERNAL_AND_EXTERNAL).

delta_sharing_organization_name

字符串

IGN

选择

增量共享实体的组织名称。该名称将在databrick -to- databricks Delta Sharing中用作正式名称。

privilege_model_version

字符串

IGN

选择

特权模型版本。这是这样的形式major.minor

输出:

metastore_id

字符串(uuid)

IGN

IGN

亚metastore的唯一标识符

字符串

IGN

IGN

Metastore家庭碎片的云供应商,例如:aws”、“azure

地区

字符串

IGN

IGN

Metastore home碎片的云区域,例如“us-west-2”、“westus

global_metastore_id

字符串

IGN

IGN

跨云和区域的全球唯一亚矿ID。例如,“aws: us-east-1:8dd1e334-c7df-44c9-a359-f86f9aae8919

created_at

int64

IGN

IGN

亚转移形成日期

created_by

字符串

IGN

IGN

metastore创建者的用户名

updated_at

int64

IGN

IGN

最近更新到亚转移的日期

updated_by

字符串

IGN

IGN

上次修改metastore的用户名

DeleteMetastoreOpts:

字段名

类型

要求吗?

描述

保龄球

选择

默认值:.当,当指定的Metastore为非空(包含未删除的)时,删除失败目录,数据访问配置,共享或收件人)。当设置为真正的时,无论指定的Metastore的内容如何,该Metastore都会被删除。

RPC端点

HTTP方法

URI

端点的名字

输入

输出

帖子

<前缀>/metastores

createMetastore

MetastoreInfo
(部分)

MetastoreInfo

得到

<前缀>/metastores

listMetastores

没有一个

数组(MetastoreInfo)

得到

<前缀>/metastores/: id

getMetastore

没有一个

MetastoreInfo

补丁

<前缀>/metastores/: id

updateMetastore

MetastoreInfo
(部分)

MetastoreInfo

删除

<前缀>/metastores/: id

deleteMetastore

DeleteMetastoreOpts

没有一个

端点行为笔记

授权

所有Metastore Admin CRUD API端点都受限Metastore管理员

listMetastores输出

listMetastores端点并列出客户帐户中存在的所有Metstores。相反,它通过工作区(由客户机的PAT令牌决定)可以访问的内容来限制列表。实际上,这意味着输出将会是一个空列表(如果没有Metastore被分配给工作区)或者一个包含单个Metastore的列表(分配给工作区的那个)。

Metastore概要API

metastore_summary端点为客户提供了一个简单的方法来确定metastore_id从用户的身份验证令牌推断出分配给工作区的Metastore。

对象模型

MetastoreSummaryInfo(弃用)

字段名

类型

描述

metastore_id

字符串(uuid)

亚metastore的唯一标识符

的名字

字符串

亚转移瘤名称

storage_root_credential_id

字符串(uuid)

用于访问云存储中的表数据的存储凭据的唯一标识符

default_data_access_config_id
(弃用)

字符串(uuid)

用于访问云存储中的表数据的DAC的唯一标识符

字符串

Metastore家庭碎片的云供应商,例如:aws”、“azure

地区

字符串

Metastore home碎片的云区域,例如“us-west-2”、“westus

global_metastore_id

字符串

跨云和区域的全球唯一亚矿ID。例如,“aws: us-east-1:8dd1e334-c7df-44c9-a359-f86f9aae8919

RPC端点

HTTP方法

URI

端点的名字

输出

得到

<前缀>/ metastore_summary

getMetastoreSummary

MetastoreSummaryInfo(弃用)

转移瘤分配API

对象模型

MetastoreAssignment:

字段名

类型

创建

更新

删除

描述

metastore_id

字符串(uuid)

要求的事情

选择

要求的事情

亚metastore的唯一标识符

default_catalog_name

字符串

要求的事情

选择

IGN

默认的目录用于这个作业。此字段仅适用于SQL仓库。


注意:或者,你可以使用"spark. databicks . SQL .initial.catalog.name {value}"在特定的作业/交互集群以及SQL仓库上设置默认目录。要了解更多细节,请阅读相关文章蜂巢亚metastores中的默认目录

RPC端点

HTTP方法

URI

端点的名字

输入

输出

<前缀>/工作/
: workspace_id / metastore

createMetastoreAssignment

MetastoreAssignment

没有一个

补丁

<前缀>/工作/
: workspace_id / metastore

updateMetastoreAssignment

MetastoreAssignment

没有一个

删除

<前缀>/工作/
: workspace_id / metastore

deleteMetastoreAssignment

MetastoreAssignment

没有一个

输入

workspace_id路径参数为int64编号,工作区的唯一标识符。

端点行为笔记

如果一项作业就一样workspace_id已经存在,它将被新的覆盖metastore_id而且default_catalog_name

此端点可用于更新metastore_id和/或default_catalog_name对于指定的工作空间,如果工作空间已经分配了一个Metastore。

授权

createMetastoreAssignment而且deleteMetastoreAssignment端点要求客户端用户是帐户管理员。

updateMetastoreAssignment端点要求:

  1. 当更新metastore_id:客户端用户必须是帐户管理员。
  2. 否则,客户端用户必须是工作区管理员。

存储凭据CRUD API

对象模型

AwsIamRole

字段名

类型

创建

更新

描述

role_arn

字符串

要求的事情

选择

用于访问S3数据的AWS IAM角色的ARN (Amazon Resource Name)

输出:

unity_catalog_iam_arn

字符串

IGN

IGN

Databricks管理的AWS IAM用户的ARN (Amazon Resource Name)。这是将要承担AWS IAM角色的标识。

external_id

字符串

IGN

IGN

外部ID用于角色假设,以防止混淆代理问题。

AzureServicePrincipal

字段名

类型

创建

更新

描述

directory_id

字符串

要求的事情

选择

与应用程序的Azure Active directory (AAD)租户对应的目录ID

application_id

字符串

要求的事情

选择

引用的AAD承租者中应用程序注册的应用程序ID

client_secret

字符串

要求的事情

选择

在AAD中为上述应用程序ID生成的客户端秘密。该字段在输出时被编辑。

GcpServiceAccountKey

字段名

类型

创建

更新

描述

电子邮件

字符串

要求的事情

选择

服务账号的邮箱

private_key_id

字符串

要求的事情

选择

服务帐户的私钥ID

private_key

字符串

要求的事情

选择

服务帐号的RSA私钥。该字段在输出时被编辑。


DeleteStorageCredentialOpts:

字段名

类型

要求吗?

描述

保龄球

选择

默认值:.当,当指定的存储凭据具有依赖的外部位置或外部表时,删除失败。当设置为真正的时,无论其依赖项如何,指定的存储凭据都将被删除。

StorageCredentialInfo

字段名

类型

创建

更新

描述

的名字

字符串

要求的事情

选择

存储凭证的名称(在父Metastore中必须是唯一的)

评论

字符串

选择

选择

用户提供的自由格式文本

老板

字符串

IGN[2]

选择

存储证书所有者的用户名/组名

skip_validation

保龄球

选择

选择

指定在创建/更新对象之前是否应该测试具有指定配置的存储凭据(用于访问云存储)。默认值:假
注意:这是一个只能输入的字段

凭据详细信息-其中之一:

aws_iam_role

AwsIamRole

要求的事情

选择

AWS的凭证详细信息

azure_service_principal

AzureServicePrincipal

要求的事情

选择

Azure的凭据详细信息

gcp_service_account_key

GcpServiceAccountKey

要求的事情

选择

GCP的证书详细信息

输出:

id

字符串(uuid)

IGN

IGN

存储凭据的唯一标识符

metastore_id

字符串(uuid)

IGN

IGN

父Metastore的唯一标识符

created_at

int64

IGN

IGN

存储凭证创建日期

created_by

字符串

IGN

IGN

存储证书创建者的用户名

updated_at

int64

IGN

IGN

上次更新存储凭据的日期

updated_by

字符串

IGN

IGN

上次更新“存储凭据”的用户名

RPC端点

HTTP方法

URI

端点的名字

输入

输出

帖子

<前缀>/ storage-credentials

createStorage
凭证

StorageCredentialInfo
(部分)

StorageCredentialInfo

得到

<前缀>/ storage-credentials

listStorage
凭证

没有一个

数组(StorageCredentialInfo)

得到

<前缀>/ storage-credentials:名字

getStorage
凭证

没有一个

StorageCredentialInfo

补丁

<前缀>/ storage-credentials:名字

updateStorageCredential

StorageCredentialInfo
(部分)

StorageCredentialInfo

删除

<前缀>/ storage-credentials:名字

deleteStorageCredential

DeleteStorageCredentialOpts

没有一个

端点行为笔记

授权

createStorageCredential端点要求用户是帐户管理员。

getStorageCredential端点要求用户:

  1. 是Metastore admin还是Account admin
  2. 存储凭证的所有者是谁
  3. 在存储凭证上有什么特权吗

listStorageCredentials端点返回:

  1. 所有存储凭证(在当前Metastore内)如果用户为Metastore admin或Account admin
  2. 调用者是所有者或拥有的所有存储凭证(在当前Metastore内)一些特权

updateStorageCredential端点要求:

  1. 用户是存储凭据的所有者,帐户管理员,如果其所有者发生了更改,则用户是metastore管理员
  2. 该用户是所有其他更新(如更新到的名字评论凭证等属性的凭证)

deleteStorageCredential端点要求用户是存储凭据或帐户管理员的所有者。

外部位置CRUD API

对象模型

DeleteExternalLocationOpts

字段名

类型

要求吗?

描述

保龄球

选择

默认值:.当,当指定的外部位置有依赖的外部表时,删除失败。当设置为真正的时,无论其依赖项如何,指定的外部位置都将被删除。


ListFilesReq

字段名

类型

要求吗?

描述

url

字符串(url)

要求的事情

用于列出文件的路径URL

credential_name

字符串

选择

用于访问URL的存储凭据的名称

max_results

int32

选择

限制要返回的结果的数量

FileInfo

字段名

类型

描述

路径

字符串(url)

存储对象的路径URI

的名字

字符串

对象名称

大小

int64

大小(字节)

mtime

int64

修改时间,基于unix纪元

is_dir

保龄球

对象是否为目录(或文件)

ListFilesResp

字段名

类型

描述

文件

数组(FileInfo)

的列表FileInfo对象,每个file/dir一个

ExternalLocationInfo

字段名

类型

创建

更新

描述

的名字

字符串

要求的事情

选择

外部位置的名称(在父Metastore内必须是唯一的)

评论

字符串

选择

选择

用户提供的自由格式文本

老板

字符串

IGN[3]

选择

外部位置所有者的用户名/组名

url

字符串(url)

要求的事情

选择

云存储中的路径URL,格式为:

AWS:“s3: / / bucket-host / [bucket-dir]
Azure:“abfss: / /主机/(路径)
GCP:“g: / / bucket-host /(路径)

credential_name

字符串

要求的事情

选择

与此外部位置一起使用的存储凭据的名称

read_only

保龄球

选择

选择

外部位置是否为只读(默认为:

只供输入(更新):

保龄球

N/A

选择

即使更改也强制更新url使依赖的外部表无效(默认:

skip_validation

保龄球

N/A

选择

是否在更新外部位置时跳过存储凭据验证(默认:

输出:

credential_id
(弃用)

字符串(uuid)

IGN

IGN

外部位置的唯一标识符

metastore_id

字符串(uuid)

IGN

IGN

父Metastore的唯一标识符

created_at

int64

IGN

IGN

外部位置创建日期

created_by

字符串

IGN

IGN

外部位置创建者的用户名

updated_at

int64

IGN

IGN

上次更新到外部位置的日期

updated_by

字符串

IGN

IGN

上次更新外部位置的用户名

RPC端点

HTTP方法

URI

端点的名字

输入

输出

帖子

<前缀>/ external-locations

createExternalLocation

ExternalLocation
信息
(部分)

ExternalLocationInfo

得到

<前缀>/ external-locations

listExternal
位置

没有一个

数组(ExternalLocationInfo)

得到

<前缀>/ external-locations:名字

getExternal
位置

没有一个

ExternalLocationInfo

补丁

<前缀>/ external-locations:名字

updateExternalLocation

ExternalLocation
信息
(部分)

ExternalLocationInfo

删除

<前缀>/ external-locations:名字

deleteExternalLocation

DeleteExternal
LocationOpts

没有一个

得到

<前缀> /文件

listFiles

ListFilesReq

ListFilesResp

端点行为笔记

外部位置URL约束

存储url的外部位置不能与其他外部位置或外部表冲突。具体地说,

授权

createExternalLocation端点要求用户

  1. 是Metastore管理
  2. 在Metastore上有CREATE EXTERNAL LOCATION特权

getExternalLocation端点要求用户:

  1. 是Metastore管理
  2. 外部位置的所有者是谁
  3. 在外部位置上有一些特权

listExternalLocations端点返回任意一个:

  1. 当用户是Metastore管理员时,所有外部位置(在当前Metastore内)
  2. 用户是其所有者或用户拥有的所有外部位置一些特权

updateExternalLocation端点要求:

  1. 用户是外部位置的所有者
  2. 用户是Metastore管理员,只有老板字段已更改

deleteExternalLocation端点要求用户是外部位置的所有者。

目录CRUD API

对象模型

CatalogInfo

字段名

类型

创建

更新

描述

的名字

字符串

要求的事情

选择

的名字目录相对于母亚metastore

评论

字符串

选择

选择

用户提供的自由格式文本

属性

地图(字符串,字符串)

选择

选择

可扩展的目录属性

老板

字符串

IGN[4]

选择

用户名/ groupname目录老板

provider_name

字符串

选择

IGN

对于Delta共享目录:增量共享提供程序的名称

share_name

字符串

选择

IGN

对于Delta共享目录:共享提供者下的共享名称

输出:

metastore_id

字符串(uuid)

IGN

IGN

父Metastore的唯一标识符

created_at

int64

IGN

IGN

日期目录创建

created_by

字符串

IGN

IGN

的用户名目录创造者

updated_at

int64

IGN

IGN

最近更新日期至目录

updated_by

字符串

IGN

IGN

上次更新用户的用户名目录

RPC端点

HTTP方法

URI

端点的名字

输入

输出

帖子

<前缀>/目录

createCatalog

CatalogInfo
(部分)

CatalogInfo

得到

<前缀>/目录

listCatalogs

没有一个

数组(CatalogInfo)

得到

<前缀>/目录/:名称

getCatalog

没有一个

CatalogInfo

补丁

<前缀>/目录/:名称

updateCatalog

CatalogInfo
(部分)

CatalogInfo

删除

<前缀>/目录/:名称

deleteCatalog

没有一个

没有一个

端点行为笔记

授权

createCatalog端点要求用户

  1. 是Metastore管理
  2. 在Metastore上有CREATE CATALOG特权

在创建Delta共享目录时,用户还需要是提供者的所有者。

getCatalog端点要求用户:

  1. 是Metastore管理
  2. 目录的所有者是谁
  3. 使用目录上的特权

listCatalogs端点返回任意一个:

  1. 所有目录(在当前Metastore),当用户是一个Metastore管理员
  2. 的所有目录(在当前Metastore内),其中用户是所有者或用户拥有使用特权

一般而言,updateCatalog端点要求:

  1. 用户是Catalog的所有者
  2. 用户是Metastore管理员,只有老板字段已更改

在这种情况下,目录的名字改变,updateCatalog要求用户同时是Catalog所有者和Metastore管理员。

deleteCatalog端点要求用户是Catalog的所有者。

架构CRUD API

对象模型

SchemaInfo

字段名

类型

创建

更新

描述

的名字

字符串

要求的事情

选择

相对于父模式的名称目录

catalog_name

字符串

要求的事情

IGN

家长姓名目录

评论

字符串

选择

选择

用户提供的自由格式文本

老板

字符串

IGN[5]

选择

模式所有者的用户名/组名

属性

地图(字符串,
字符串)

选择

选择

可扩展模式属性

输出:

metastore_id

字符串(uuid)

IGN

IGN

父Metastore的唯一标识符

full_name

字符串

IGN

IGN

Schema的完全限定名为<目录> . <模式>

created_at

int64

IGN

IGN

模式创建日期

created_by

字符串

IGN

IGN

Schema创建者的用户名

updated_at

int64

IGN

IGN

最后一次更新到架构的日期

updated_by

字符串

IGN

IGN

上次更新Schema的用户名

RPC端点

HTTP方法

URI

端点的名字

输入

输出

帖子

<前缀>/模式

createSchema

SchemaInfo
(部分)

SchemaInfo

得到

<前缀>/模式[?< q_args >

listSchemas

q_args

数组(SchemaInfo)

得到

<前缀>/ /模式:full_name

getSchema

没有一个

SchemaInfo

补丁

<前缀>/ /模式:full_name

updateSchema

SchemaInfo
(部分)

SchemaInfo

删除

<前缀>/ /模式:full_name

deleteSchema

没有一个

没有一个

输入

q_args:

字段名

类型

要求/ OPT

描述

catalog_name

字符串

要求的事情

父节点名称目录

端点行为笔记

授权

所有*模式端点要求用户有权访问父Catalog。这也意味着用户

  1. 是Metastore管理
  2. 是父目录的所有者
  3. 使用父目录上的特权

下面的所有要求都是在访问父Catalog的要求之外的。

createSchema端点要求用户

  1. 是Metastore管理
  2. 创建父目录上的特权

getSchema端点要求用户:

  1. 是Metastore管理
  2. 是Schema的所有者
  3. 使用Schema上的特权

listSchemas端点返回任意一个:

  1. 所有模式(在当前Metastore和父目录中),当用户是Metastore管理员或父目录的所有者时
  2. 的所有模式(在当前Metastore和父目录中),其中用户是所有者或用户拥有使用特权

一般而言,updateSchema端点要求:

  1. 用户是Schema的所有者
  2. 用户是Metastore管理员,只有老板字段已更改

在图式的情况下的名字改变,updateSchema还要求用户在父目录上拥有CREATE权限(或者是Metastore管理员)。

deleteSchema端点要求用户是模式的所有者或父目录的所有者。

表RD API

对象模型

TableInfo

字段名

类型

创建

更新

描述

的名字

字符串

要求的事情

选择

表的名称相对于父模式

catalog_name

字符串

要求的事情

IGN

家长姓名目录

schema_name

字符串

要求的事情

IGN

相对于父模式的父模式名称目录

table_type

字符串

要求的事情

IGN

区分视图与托管/外部表

data_source_format

字符串

要求*

选择

参见数据源格式规范

数组(ColumnInfo)

要求的事情

选择

表列序列

storage_location

字符串

要求*

要求*

表数据存储位置的URL(*外部表的REQ)。对于托管表,如果提供了路径,则它需要是通过Sttaging表API,否则为空)

storage_credential_name

字符串

选择

IGN

仅针对EXTERNAL table:要使用的存储凭据的名称(不能通过UpdateTable端点更改)。

view_definition

字符串

视图REQ

选择

定义视图的SQL文本(用于table_type= = "视图”)

sql_path

字符串

选择

选择

可无条件引用对象的方案一览表(裁判

评论

字符串

选择

选择

用户提供的自由格式文本

老板

字符串

IGN[6]

选择

表所有者的用户名/组名

属性

地图(字符串,字符串)

选择

选择

可扩展表属性

输出:

metastore_id

字符串(uuid)

IGN

IGN

父Metastore的唯一标识符

full_name

字符串

IGN

IGN

表的完全限定名为<目录>, < schema >。<表>

data_access_configuration_id
(弃用)

字符串(uuid)

IGN

IGN

用于访问表数据的DataAccessConfig的唯一标识符。

created_at

int64

IGN

IGN

表创建日期

created_by

字符串

IGN

IGN

表创建者用户名

updated_at

int64

IGN

IGN

最后一次更新表的日期

updated_by

字符串

IGN

IGN

上次更新表的用户名


REQ* =外部表和托管表


表类型

的支持值table_type字段(在TableInfo)为以下字符串:

列类型名称

type_name字段(在ColumnInfo中)支持的值是以下字符串:

数据源格式

支持多个外部表数据源格式.标识这些格式的字符串常量是:

ColumnInfo

字段名

类型

创建

更新

描述

的名字

字符串

要求的事情

选择

列的用户可见名称

type_name

字符串

要求的事情

选择

(外)型名称;看到列类型名称以上

type_text

字符串

要求的事情

选择

列类型规范(带元数据)作为SQL文本

type_json

字符串

要求的事情

选择

列类型规范(带元数据)为JSON字符串

type_precision

int32

选择

选择

精度数字;适用于DECIMAL列

type_scale

int32

选择

选择

小数点右数;适用于DECIMAL列

type_interval_type

字符串

选择

选择

INTERVAL列的格式

位置

int32

要求的事情

选择

列的序号位置,从0开始。

评论

字符串

选择

选择

用户提供的自由格式文本

可以为空

保龄球

选择

选择

field是否为空(默认值:真正的

partition_index

int16

选择

选择

分区ID

RPC端点

HTTP方法

URI

端点的名字

输入

输出

得到

<前缀>/表[?< q_args >

listTables

q_args

TableList

得到

<前缀>/ /表:full_name

可以获得的

没有一个

TableInfo

删除

<前缀>/ /表:full_name

deleteTable

没有一个

没有一个

得到

< pe_prefix > /表/:full_name

privilegedGetTable

没有一个

TableInfo

输入

q_args:

字段名

类型

要求/ OPT

描述

catalog_name

字符串

要求的事情

父节点名称目录

schema_name

字符串

要求的事情

相对于其父模式的父模式名称目录

这两个catalog_name而且schema_name的参数listTables端点是必需的。在多个schema中列出表(在同一个schema中)目录),以分页的“散装”方式,请参阅listTableSummaries下面的API。

端点行为笔记

授权

可以获得的endpoint要求用户要么是Metastore管理员,要么满足以下所有要求:

  1. 拥有所有权或者使用在父Catalog和Schema上的特权
  2. 拥有所有权或者选择请求表上的特权

listTables端点返回任意一个:

  1. 所有表(在当前Metastore和父目录和模式),当用户是Metastore管理员
  2. 用户拥有所有权的所有表(在当前Metastore和父Catalog和Schema中)选择权限,前提是用户也拥有所有权或使用在父Catalog和Schema上的特权

deleteTable端点要求用户

  1. 是父目录的所有者
  2. 使用父目录上的特权,并且是父模式的所有者
  3. 使用父目录和模式上的特权,并且是表的所有者

ListTableSummaries API

对象模型

TableSummariesReq

字段名

类型

要求/ OPT

描述

catalog_name

字符串

要求的事情

家长姓名目录用于感兴趣的模式和表

schema_name_pattern

字符串

选择

一个SQL LIKE模式(支持而且_)指定感兴趣的schema的名称

table_name_pattern

字符串

选择

一个SQL LIKE模式(支持而且_)指定感兴趣的表的名称

max_results

int32

选择

要返回的最大表数(即页长);默认值为1000

page_token

字符串

选择

为下一页结果发送的不透明令牌

TableSummary

字段名

类型

描述

full_name

字符串

表的完全限定名称
<
目录>, < schema >。<表>

table_type

字符串

区分视图与托管/外部表

TableSummariesResp

字段名

类型

描述

数组(TableSummary)

表摘要列表

next_page_token

字符串

用于检索结果下一页的不透明令牌

RPC端点

HTTP方法

URI

端点的名字

输入

输出

帖子

<前缀>/ table-summaries

listTableSummaries

TableSummariesReq

TableSummariesResp

端点行为笔记

授权

listTables端点返回任意一个:

  1. 当用户是Metastore管理员时,所有表(在当前Metastore和父Catalog和Schema内)的TableSummary
  2. 对于用户拥有所有权的所有表和模式(在当前Metastore和父目录中)的TableSummary选择桌上的特权和所有权还是使用权限,前提是用户还拥有所有权或使用父目录上的特权

权限API

术语和权限管理模型

的砖权限API管理权限水平(例如,“CAN_USE”,“CAN_MANAGE”),用户为各种对象类型(notebook, Jobs, Tokens等)拥有的标量值。对于Unity管理的对象目录,主体(用户或组)可能具有不具有权限的集合组织因为它们是独立的能力。例如,给定用户可能具有修改模式的能力,但这种能力并不意味着用户具有在该模式中创建表的能力,反之亦然。

虽然术语可能不是行业标准,但我们定义了以下术语:

这样,我们就可以说a可获得的权限,或者一个用户的权限在该安全(对象)上。

SQL对象权限

Unity Catalog中的安全对象是分层的,权限向下继承。这意味着在目录上授予特权将自动将特权授予目录中的所有当前和未来对象。类似地,在模式上授予的特权将由该模式中的所有当前和未来对象继承。

看到Unity Catalog特权和安全对象获取每个可安全对象上受支持的特权值。

对象模型

PrivilegeAssignment

PrivilegesAssignment类型将单个主体映射到分配给该主体的特权。

字段名

类型

描述

主要

字符串

用户名(邮箱地址)或组名

特权

数组(字符串)

分配给主体的特权列表

PermissionsList

PermissionsList消息类型用于列出给定安全对象上的所有权限。它将每个主体映射到其分配的特权。

字段名

类型

描述

privilege_assignments

数组(PrivilegeAssignment)

所有权限(为可安全对象配置)的列表,将所有指定主体映射到其关联的权限。

一个例子PermissionsList


“privilege_assignments”:(

“主要”:“
username@examplesemail.com",
“特权”(“选择”):
},

“主要”:“eng-data-security”,
“特权”(“选择”,“修改”,“创造”)
},

“主要”:“用户”,
"特权":["使用模式","使用目录"]



PermissionsChange

updatePermissions(PATCH)端点允许客户端指定一组要对安全对象的权限进行的增量更改。

PermissionsChangeType指定向单个主体添加和/或从单个主体删除的特权。

字段名

类型

描述

主要

字符串

用户名(邮箱地址)或组名

添加

数组(字符串)

要为主体添加的特权列表

删除

数组(字符串)

要从主体中删除的特权列表

PermissionsDiff

PermissionsDiff消息类型指定要对安全对象的权限进行更改的列表。

字段名

类型

描述

变化

数组(PermissionsChange)

要对安全对象的权限进行更改的列表

一个例子PermissionsDiff


“变化”:[

“主要”:“username@examplesemail.com”,
“添加”:“选择”,
“删除”(“修改”):
},

“主要”:“eng-data-security”,
“删除”(“创造”):
},

“主要”:“用户”,
"添加":["使用模式","使用目录"]


改变所有权

权限变更的一种特殊情况是所有权变更。这对应于SQL命令“ALTER OWNER to . ALTER ,并受到治理模型中描述的限制。

通过调用update端点来更改所有权,其输入包含包含新所有者的用户名/组名的“owner”字段。需要明确的是,这次所有权变更确实如此
涉及调用权限API。

在不久的将来,UC支持的特权可能会增加“OWN”特权。


RPC端点

统一目录Permissions api适用于多种安全类型,具有以下安全标识符(sec_full_name)字段:

sec_type

sec_id领域

描述

metastore

id

亚转移ID

目录

的名字

目录的名字

模式

full_name

模式的全名(<目录>。< schema >)

表格

full_name

表的全名(<目录>, < schema >。<表>)

storage-credential

的名字

存储凭据名称

外部位置的

的名字

外部位置名称

视图

full_name

视图的全名(..)

函数

的名字

函数的全名(..)

HTTP方法

URI

端点的名字

输入

输出

得到

<前缀>/ /权限/ < sec_type >
< sec_full_name > [?q_args]

getPermissions

q_args

PermissionsList

补丁

<前缀>/ /权限/ < sec_type >
< sec_full_name >

updatePermissions

PermissionsDiff

PermissionsList

<前缀>/ /权限/ < sec_type >
< sec_full_name >

PermissionsList

没有一个

例子
GET / api / 2.1 /团结-目录/ /权限目录/ some_cat
把/ api / 2.1 /团结-
目录/ /表/ some_cat.other_schema.my_table权限

输入

q_args:

字段名

类型

要求/ OPT

描述

主要

字符串

选择

利益主体(仅返回此用户/组的权限)

授权、错误响应

数据治理模型详细描述了格兰特撤销而且显示格兰特命令,这些命令对应于权限的添加、删除以及从getPermissions端点。输出和错误行为API端点的值为:


“error_code”:“
未经授权的",
"message": "用户只能授予或撤销模式和表权限。"

用户信息的API

对象模型

GetMyInfoResp:

字段名

类型

描述

is_metastore_admin

保龄球

标志,指示用户是否是Metastore管理员

GetMyGroupsResp:

字段名

类型

描述

group_name

数组(字符串)

组名列表

RPC端点

HTTP方法

URI

端点的名字

输入

输出

得到

<前缀>[/用户信息我吗?< q_args >

getMyInfo

q_args

GetMyInfoResp

得到

<前缀>/用户信息/我的群组

getMyGroups

GetMyGroupsReq

GetMyGroupsResp

输入

q_args:

字段名

类型

要求/ OPT

描述

for_account_level

保龄球

选择

返回的组是否对应于帐户级或工作区级的组成员关系

共享CRUD API (Delta Sharing)

对象模型

ShareInfo

字段名

类型

创建

更新

描述

的名字

字符串

要求的事情

选择

相对于父亚metastore的Share名称

评论

字符串

选择

选择

用户提供的自由格式文本

对象

数组(ShareDataObject)

IGN

选择

共享中的共享数据对象列表

老板

字符串

IGN[7]

选择

共享所有者的用户名/组名

输出:

created_at

int64

IGN

IGN

创建共享日期

created_by

字符串

IGN

IGN

共享创建者用户名

updated_at

int64

IGN

IGN

最后一次更新到共享的日期

updated_by

字符串

IGN

IGN

上次更新共享的用户名

ShareDataObject

字段名

类型

创建

更新

描述

的名字

字符串

IGN

选择

唯一标识数据对象的完全限定名称。例如,一个表的完全限定名的格式是' .. '。

评论

字符串

IGN

选择

用户提供的自由格式文本

shared_as

字符串

IGN

选择

用户为共享中的数据对象提供的新名称。如果没有提供这个新名称,对象的原始名称将被用作“shared_as”名称。“shared_as”名称在共享中必须是唯一的。

对于表,新名称必须遵循' . '的格式。

partition_specification

PartitionSpecification

IGN

选择

为共享表定义分区过滤规范的格式。

它由一个分区列表组成,分区列表又包含一个PartitionValues列表。

cdf_enabled

保龄球

IGN

选择

是否启用更改数据提要(cdf),或指示是否在共享对象上启用cdf。

start_version

int64

IGN

选择

与cdf对象关联的开始版本。

这允许数据提供者控制客户端可访问的最低对象版本。

如果指定,客户端可以查询版本>= start_version的快照或更改。

如果不指定,客户端只能从对象添加到共享时的版本开始查询。

注意:start_version应该<=对象的“当前”版本。

输出:

added_at

int64

IGN

IGN

表添加到共享的日期

added_by

字符串

IGN

IGN

添加表共享的用户的用户名

data_object_type

字符串

IGN

IGN

数据对象类型。

目前唯一支持的类型是“TABLE”。

PartitionSpecification

字段名

类型

创建

更新

描述

分区

数组(分区)

IGN

选择

分区具有“或”的逻辑关系

分区

字段名

类型

创建

更新

描述

数组(PartitionValues)

IGN

选择

分区值具有与的逻辑关系

PartitionValues

字段名

类型

创建

更新

描述

的名字

字符串

IGN

选择

分区列的名称。在单个分区中必须是不同的

价值

字符串

IGN

选择

分区列的值。当此值未设置时,它表示“空”值。

人事处

字符串

IGN

选择

操作符来申请值。可以是“EQUAL”或“LIKE”。

RPC端点

HTTP方法

URI

端点的名字

输入

输出

帖子

<前缀>/股

createShare

ShareInfo
(部分)

ShareInfo

得到

<前缀>/股

listShares

没有一个

数组(ShareInfo)

得到

<前缀>/ /股票:名字

getShare

没有一个

ShareInfo

补丁

<前缀>/ /股票:名字

updateShare

ShareInfo
(部分)

ShareInfo

删除

<前缀>/ /股票:名字

deleteShare

没有一个

没有一个

得到

<前缀> /股票/:名称/权限

getSharePermissions

没有一个

PermissionsList

补丁

<前缀> /股票/:名称/权限

updateSharePermissions

PermissionsDiff

PermissionsList

端点行为笔记

授权

createShare端点要求用户

  1. 是Metastore管理
  2. 在Metastore上有CREATE SHARE特权

getShare端点要求用户:

  1. 是Metastore管理
  2. 该股份的所有者是谁

listShares端点返回任意一个:

  1. 所有的共享(在当前的Metastore),当用户是一个Metastore管理员
  2. 用户是所有者的所有股份(在当前Metastore内)

一般而言,updateShare端点要求:

  1. 用户是共享的所有者
  2. 用户是Metastore管理员,只有老板字段已更改

在这种情况下,分享的名字改变,updateShare要求用户同时是共享所有者和Metastore管理员。

对于添加的每个表updateShare,共享所有者也必须拥有选择特权摆在桌面上。必须无限期地维护此特权,以便接收方能够访问表。因此,强烈建议使用组作为共享所有者。

通过删除表updateShare不需要额外的特权。

deleteShare端点要求用户是共享的所有者。

getSharePermissions端点要求用户:

  1. 是Metastore管理
  2. 该股份的所有者是谁

updateSharePermissions端点要求用户:

  1. 是Metastore管理
  2. 该股份的所有者是谁

对于新的接受者授予,用户还必须是接受者的所有者。

接收者撤销不需要额外的特权。

接收方CRUD API(增量共享)

对象模型

RecipientInfo

字段名

类型

创建

更新

描述

的名字

字符串

要求的事情

选择

受体名称相对于父亚metastore

authentication_type

字符串

要求的事情

IGN

增量共享认证类型。可以是"TOKEN"或"DATABRICKS"

评论

字符串

选择

选择

用户提供的自由格式文本

老板

字符串

IGN[8]

选择

收件人所有者的用户名/组名

data_recipient_global_metastore_id

字符串

选择

IGN

由数据接收者提供的全局UC亚metastore id。

当认证类型为DATABRICKS时,该字段才会出现。

标识符的格式为::

ip_access_list

数组(IpAccessList)

选择

选择

IP访问列表。该字段仅适用于TOKEN认证类型。

输出:

created_at

int64

IGN

IGN

收件人创建日期

created_by

字符串

IGN

IGN

收件人创建者用户名

updated_at

int64

IGN

IGN

最后一次更新给收件人的日期

updated_by

字符串

IGN

IGN

上次更新用户的用户名

令牌

数组(RecipientTokenInfo)

IGN

IGN

接收方令牌。该字段仅在认证类型为TOKEN时才会出现。

字符串

IGN

IGN

收件人UC Metastore的云供应商。

当认证类型为DATABRICKS时,该字段才会出现。

地区

字符串

IGN

IGN

接受者UC Metastore的云区域。

当认证类型为DATABRICKS时,该字段才会出现。

metastore_id

字符串

IGN

IGN

收件人UC Metastore的UUID。

当认证类型为DATABRICKS时,该字段才会出现。

IpAccessList

字段名

类型

创建

更新

描述

allowed_ip_addresses

数组(字符串)

选择

选择

CIDR表示法允许的IP地址。100的限制。

RecipientTokenInfo

字段名

类型

创建

更新

描述

输出:

id

字符串

IGN

IGN

接收者令牌的唯一id。

activation_url

字符串

IGN

IGN

检索访问令牌的完整激活url。

如果已经检索到令牌,则它将为空。

expiration_time

int64

IGN

IGN

令牌的过期时间戳,以epoch毫秒为单位。

created_at

int64

IGN

IGN

接收令牌创建日期

created_by

字符串

IGN

IGN

接收令牌创建者的用户名

updated_at

int64

IGN

IGN

最后一次更新接收令牌的日期

updated_by

字符串

IGN

IGN

上次更新接收令牌的用户名

ShareToPrivilegeAssignment

字段名

类型

创建

更新

描述

输出:

share_name

字符串

IGN

IGN

共享名称。

privilege_assignments

数组(PrivilegeAssignment)

IGN

IGN

分配给主体的特权。

RotateRecipientToken

字段名

类型

创建

更新

描述

existing_token_expire_in_seconds

int64

IGN

要求的事情

这将只将现有令牌的过期时间设置为较小的时间戳,

不能延长过期时间。使用0立即使现有令牌过期,负数将返回错误。

RPC端点

HTTP方法

URI

端点的名字

输入

输出

帖子

<前缀>/收件人

createRecipient

RecipientInfo
(部分)

RecipientInfo

得到

<前缀>/收件人

listRecipients

没有一个

数组(RecipientInfo)

得到

<前缀>/收件人/:名字

getRecipient

没有一个

RecipientInfo

补丁

<前缀>/收件人/:名字

updateRecipient

RecipientInfo
(部分)

RecipientInfo

删除

<前缀>/收件人/:名字

deleteRecipient

没有一个

没有一个

得到

<前缀> /收件人/:名称/共享许可

getRecipientSharePermissions

没有一个

数组(ShareToPrivilegeAssignment)

帖子

<前缀> /收件人/:名称/ rotate-token

rotateRecipientToken

RotateRecipientToken

RecipientInfo

端点行为笔记

授权

createRecipient端点要求用户

  1. 是Metastore管理
  2. 在Metastore上有CREATE接收者特权

getRecipient端点要求用户:

  1. 是Metastore管理
  2. 收件人的拥有人是谁

listRecipients端点返回任意一个:

  1. 所有的收件人(在当前Metastore),当用户是一个Metastore管理员
  2. 用户是所有者的所有收件人(在当前Metastore内)

一般而言,updateRecipient端点要求:

  1. 用户是收件人的所有者
  2. 用户是Metastore管理员,只有老板字段已更改

如果收件人的名字改变,updateRecipient要求用户同时是收件人所有者和Metastore管理员。

deleteRecipient端点要求用户是接收者的所有者。

getRecipientSharePermissions端点要求用户:

  1. 是Metastore管理
  2. 收件人的拥有人是谁

rotateRecipientToken端点要求用户是接收者的所有者。

提供者CRUD API (Delta共享)

对象模型

ProviderInfo

字段名

类型

创建

更新

描述

的名字

字符串

要求的事情

选择

提供者相对于父亚metastore的名称

authentication_type

字符串

要求的事情

IGN

增量共享认证类型。可以是"TOKEN"或"DATABRICKS"

评论

字符串

选择

选择

用户提供的自由格式文本

老板

字符串

IGN[9]

选择

Povider所有者的用户名/组名

recipient_profile_str

字符串

选择

选择

仅适用于“TOKEN”认证类型。这是提供给收件人的配置文件字符串。看到https://github.com/delta-io/delta-sharing/blob/main/PROTOCOL.md#profile-file-format

在输出模式中,对承载令牌进行编校。

输出:

created_at

int64

IGN

IGN

提供商创建日期

created_by

字符串

IGN

IGN

Provider创建者的用户名

updated_at

int64

IGN

IGN

最后一次更新到提供程序的日期

updated_by

字符串

IGN

IGN

上次更新Provider的用户名

recipient_profile

RecipientProfile

IGN

IGN

收件人配置文件。该字段仅在认证类型为TOKEN时才会出现。看到https://github.com/delta-io/delta-sharing/blob/main/PROTOCOL.md#profile-file-format

字符串

IGN

IGN

提供商的UC Metastore的云供应商。

当认证类型为DATABRICKS时,该字段才会出现。

地区

字符串

IGN

IGN

提供商的UC Metastore的云区域。

当认证类型为DATABRICKS时,该字段才会出现。

metastore_id

字符串

IGN

IGN

提供商的UC Metastore的UUID。

当认证类型为DATABRICKS时,该字段才会出现。

RecipientProfile

字段名

类型

创建

更新

描述

输出:

share_credentials_version

int32

IGN

IGN

该字段仅在认证类型为TOKEN时才会出现。

配置文件的文件格式版本。每当对概要文件格式进行了不向前兼容的更改时,这个版本都会增加。当客户机运行不受支持的概要文件格式版本时,它应该显示一条错误消息,指示用户升级到客户机的新版本。

端点

字符串

IGN

IGN

共享服务器的url。

ProviderShare

字段名

类型

创建

更新

描述

输出:

的名字

字符串

IGN

IGN

提供者共享的名称。

RPC端点

HTTP方法

URI

端点的名字

输入

输出

帖子

<前缀>/供应商

createProvider

ProviderInfo
(部分)

ProviderInfo

得到

<前缀>/供应商

listProviders

没有一个

数组(ProviderInfo)

得到

<前缀>/供应商/:名字

getProvider

没有一个

ProviderInfo

补丁

<前缀>/供应商/:名字

updateProvider

ProviderInfo
(部分)

ProviderInfo

删除

<前缀>/供应商/:名字

deleteProvider

没有一个

没有一个

得到

<前缀> /供应商/:名称/股

listProviderShares

没有一个

数组(ProviderShare)

端点行为笔记

授权

createProvider端点要求用户

  1. 是Metastore管理
  2. 在Metastore上有CREATE PROVIDER特权

getProvider端点要求用户:

  1. 是Metastore管理
  2. 提供者的所有者是谁

listProviders端点返回任意一个:

  1. 所有提供者(在当前Metastore),当用户是一个Metastore管理员
  2. 用户是所有者的所有提供者(在当前Metastore内)

一般而言,updateProvider端点要求:

  1. 用户是提供者的所有者
  2. 用户是Metastore管理员,只有老板字段已更改

在这种情况下,提供者的名字改变,updateProvider要求用户同时是Provider所有者和Metastore管理员。

deleteProvider端点要求用户是提供者的所有者。

listProviderShares端点要求用户是:

  1. 是Metastore管理
  2. 提供者的所有者是谁

[1]创建,新对象的老板字段为执行操作用户的用户名。

[2]创建,新对象的老板字段为执行操作用户的用户名。

[3]创建,新对象的老板字段为执行操作用户的用户名。

[4]创建,新对象的老板字段为执行操作用户的用户名。

[5]创建,新对象的老板字段为执行操作用户的用户名。

[6]创建,新对象的老板字段为执行操作用户的用户名。

[7]创建,新对象的老板字段为执行操作用户的用户名。

[8]创建,新对象的老板字段为执行操作用户的用户名。

[9]创建,新对象的老板字段为执行操作用户的用户名。