前提条件 已参考元数据迁移完成元数据迁移。 当前用户具有OBS相关操作权限，且已创建用于存储数据的OBS并行文件系统。 已将待迁移的权限策略文件导出，并上传至OBS并行文件系统中。权限导出操作可联系对应服务支持人员。 权限策略中授权主体（除角色外）需要提前创建，且名称需保持一致；权限策略中包含的元数据已存在，且名称一致。 如果迁移类型为DLF，其对应关系及迁移策略如下： RAM用户：IAM用户（如果对应的IAM用户不存在，该权限策略不进行迁移） RAM角色：IAM用户组（如果对应的IAM用户组不存在，该权限策略不进行迁移） DLF角色：LakeFormation角色（不存在会自动创建） 如果迁移类型为Ranger，则仅支持Ranger的allow权限迁移，不支持deny权限迁移。

前提条件 当前实例已创建存储迁移元数据的Catalog。 且待操作用户具有OBS相关操作权限、具有已创建存储迁移元数据的Catalog的操作权限。 已创建了用于存储迁移数据的OBS并行文件系统。 表的Owner只能包含字母、数字和下划线(_)，且长度为1~49个字符。不能包含中划线(-)等其他字符。 如果需要迁移多个MRS集群中的元数据到同一个LakeFormation实例，MRS集群之间的Database名称不能重复。

约束与限制 IAM用户组被删除后，LakeFormation云服务数据权限中的相关权限策略，需要用户手动清理删除。 建库时路径不能为所在Catalog父路径或相同路径，不能为同一Catalog下其他数据库（除default外）路径的父路径、子路径或相同路径。 创建数据库的存储位置必须在所属Catalog的存储位置之下。 用户自定义创建的Catalog对象及其子元数据对象，暂不支持授权和细粒度权限控制。 LakeFormation数据权限单次授权，授权主体不能超过20个，元数据对象不能超过10个。 LakeFormation中，总分区数量不超过1,000,000,000。 LakeFormation不支持跨Region的元数据和权限统一管理。 LakeFormation不支持跨实例的元数据和权限统一管理。 一个数据表中，每个分区所对应的Partition Value组合必须在全表唯一。 由Partition Keys和Partition Values组合构成的Partition Name，总长度不能超过1000字符。 元数据的参数描述中，1个中文字符对应3个字节。 LakeFormation依赖OBS服务的并行文件系统，OBS需要基于大数据存算分离场景进行分离部署；LakeFormation元数据的存储位置对应OBS路径，与存算分离架构的MRS等大数据集群对接。OBS并行文件系统需要支持AccessLabel特性。 LakeFormation中，不同实例的同名角色在授权时对应的OBS AccessLabel相同，不建议在同一个区域中的不同实例创建同名角色。

操作步骤 调用创建实例接口，创建LakeFormation实例，同时记录接口返回的实例Id。 请求示例： POST https://{endpoint}/v1/{project_id}/instances Body: { "name": "lakeformation", "charge_mode": "postPaid", "shared": "false", "specs": [ { "spec_code": "lakeformation.unit.basic.qps", "stride_num": 1 } ], "enterprise_project_id": "0" } 响应示例： { "instance_id": "13677734-a4ee-43e2-9d11-30b8b2e32a95", "name": "lakeformation", "description": "", "enterprise_project_id": "0", "shared": false, "default_instance": false, "create_time": "2023-06-29T09:08:33.000+00:00", "update_time": "2023-06-29T09:08:34.000+00:00", "status": "RESOURCE_PREPARATION", "resource_progress": 25, "resource_expected_duration": 15, "in_recycle_bin": false, "tags": [], "specs": [ { "spec_code": "lakeformation.unit.basic.qps", "stride_num": 1 }, { "spec_code": "lakeformation.unit.basic.metadata", "stride_num": 0 } ] } 调用查询实例详情接口，查询实例状态，等待实例状态变为RUNNING运行中，表示实例创建完成。 请求示例： GET https://{endpoint}/v1/{project_id}/instances/{instance_id} instance_id：1响应信息中的“instance_id”参数值。 响应示例： { "instance_id": "13677734-a4ee-43e2-9d11-30b8b2e32a95", "name": "lakeformation", "description": "", "enterprise_project_id": "0", "shared": false, "default_instance": false, "create_time": "2023-06-29T09:08:33.000+00:00", "update_time": "2023-06-29T09:08:34.000+00:00", "status": "RUNNING", "in_recycle_bin": false, "tags": [], "specs": [ { "spec_code": "lakeformation.unit.basic.qps", "stride_num": 1 }, { "spec_code": "lakeformation.unit.basic.metadata", "stride_num": 0 } ] } （可选）如果当前租户首次创建LakeFormation实例，该实例将自动作为默认实例（default）。客户端可以直接访问默认实例，或通过指定具体的实例ID来访问对应的实例。非默认实例可以通过调用设为默认实例接口将非默认实例设为默认实例。 请求示例： POST https://{endpoint}/v1/{project_id}/instances/{instance_id}/default instance_id：1响应信息中的“instance_id”参数值。 调用创建服务接入客户端接口，选择客户端对应的VPC相关信息创建接入客户端，LakeFormation服务将自动为其创建终端节点和DNS内网域名，用于打通网络连接。 请求示例： POST https://{endpoint}/v1/{project_id}/instances/{instance_id}/access-clients instance_id：1响应信息中的“instance_id”参数值。 Body: { "name": "access-client", "vpc_id": "131fb837-37ae-4aa6-9e87-312919df659f", "subnet_id": "2fa7ec47-c7f6-4a81-8e77-1dd41121b726" } 响应示例： { "id": "b73a9311-1ce9-48fe-b714-21bc41ce7b82", "name": "access-client", "access_mode": "SYSTEM", "status": "CREATING", "vpc_id": "131fb837-37ae-4aa6-9e87-312919df659f", "subnet_id": "2fa7ec47-c7f6-4a81-8e77-1dd41121b726" } 调用获取服务接入客户端详情接口，查询接入客户端状态，等待状态变为RUNNING，表示接入客户端创建完成，同时可以在详情中查看接入IP、域名等详细信息。 请求示例： GET https://{endpoint}/v1/{project_id}/instances/{instance_id}/access-clients/{client_id} instance_id：1响应信息中的“instance_id”参数值。 client_id：4响应信息中的“id”参数值。 响应示例： { "id": "b73a9311-1ce9-48fe-b714-21bc41ce7b82", "name": "access-client", "access_mode": "SYSTEM", "status": "RUNNING", "vpc_id": "131fb837-37ae-4aa6-9e87-312919df659f", "subnet_id": "2fa7ec47-c7f6-4a81-8e77-1dd41121b726", "access_connections": [ { "vpcep_id": "f72c8034-df38-4dbc-bd5d-2f50531ba104", "ip": "10.0.0.6", "owner": "555d9e8999c94705be3d7edb70a3199a", "domain": "xxx.dalf-ed1c-b3070cba-baae-4220-b7ff-9b2bca043efb.apig-lakeformation.com" } ], "create_time": "2023-06-29T12:12:12.000+00:00" } 参考目录管理相关接口，使用上述步骤获取的接入IP与实例ID访问元数据管理相关接口，获取目录列表。 请求示例： GET https://{endpoint}/v1/{project_id}/instances/{instance_id}/catalogs endpoint：{instance_id}.lakeformation.lakecat.com，如果已经将实例设为默认实例可以使用default-{project_id}.lakeformation.lakecat.com。 instance_id：1响应信息中的“instance_id”参数值，如果已经将实例设为默认实例可以直接使用default作为实例ID。 请求头示例 Host：lakeformation.lakecat.com 响应示例： [ { "catalog_name": "hive", "description": "Default catalog, for Hive", "location": "obs://lakeformation-555d9e8999c94705-xxx/ed1ce787-1671-4ce4-b84f-6f40ccb26752" } ]

URI GET /v1/{project_id}/instances/{instance_id}/access-clients 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目编号。获取方法，请参见获取项目ID。 instance_id 是 String LakeFormation实例ID。创建实例时自动生成。例如：2180518f-42b8-4947-b20b-adfc53981a25。 表2 Query参数 参数 是否必选 参数类型 描述 id 否 String ID搜索。根据ID进行搜索。 name 否 String 名称关键字搜索。只能包含字母、数字、下划线和中划线，且最大长度为32个字符。 offset 是 Integer 分页查询时的偏移量。默认值为0。最小值为0，最大值为1000。 limit 否 Integer 分页一页显示数。默认值为10。最小值为1，最大值为1000。

响应参数 状态码： 200 表4 响应Body参数 参数 参数类型 描述 access_client_infos Array of AccessClientInfo objects 接入客户端信息列表。 total Integer 接入客户端信息总数。 表5 AccessClientInfo 参数 参数类型 描述 id String 客户端ID。 name String 客户端名称。 access_mode String 接入模式：YSTEM、CUSTOM、AUTO。 枚举值： SYSTEM CUSTOM AUTO status String 客户端状态：CREATING、RUNNING、DELETING、DELETED、CREATE_FAIL、DELETE_FAIL。 枚举值： CREATING RUNNING DELETING DELETED CREATE_FAIL DELETE_FAIL vpc_id String VPC ID。 subnet_id String 子网ID。 access_connections Array of AccessConnectionInfo objects 接入连接列表。 create_time String 实例创建时间戳。 表6 AccessConnectionInfo 参数 参数类型 描述 vpcep_id String 虚拟私有云终端节点ID。在接入管理-创建客户端-前往VPC创建-VPC终端节点 创建和查看。 ip String 接入IP。 owner String 拥有者。 domain String 接入域名，通过IP接入访问Lakeformation API时，需在请求头中添加HOST参数并传入该域名。

响应示例 状态码： 200 OK { "total" : 1, "access_client_infos" : [ { "id" : "gs23xxxxxxxxxxxxxxxxxxxxxxxxxxxxfgs2", "name" : "lakeformation_client", "access_mode" : "SYSTEM", "vpc_id" : "d3fcxxxxxxxxxxxxxxxxxxxxxxxxxxxx8f1e", "subnet_id" : "d3fcxxxxxxxxxxxxxxxxxxxxxxxxxxxx8f1e", "status" : "RUNNING", "access_connections" : [ { "vpcep_id" : "0612xxxxxxxxxxxxxxxxxxxxxxxxxxxxa8fb", "ip" : "10.1.0.1", "domain" : "xxxxxx.com" }, { "vpcep_id" : "0612xxxxxxxxxxxxxxxxxxxxxxxxxxxxa8fb", "ip" : "10.1.0.2", "domain" : "xxxxxx.com" } ] } ] }

URI GET /v1/{project_id}/instances/{instance_id}/access 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目编号。获取方法，请参见获取项目ID。 instance_id 是 String LakeFormation实例ID。创建实例时自动生成。例如：2180518f-42b8-4947-b20b-adfc53981a25。 表2 Query参数 参数 是否必选 参数类型 描述 offset 是 Integer 分页查询时的偏移量。默认值为0。最小值为0，最大值为1000。 limit 否 Integer 分页一页显示数。默认值为10，最大值为1000。

响应示例 状态码： 200 OK { "total" : 1, "access_infos" : [ { "vpcep_service_name" : "xxxxxx.apig.3ab1xxxxxxxxxxxxxxxxxxxxxxxxxxxxf524", "domain" : "xxxxxxxxxxxxxxxxxxxxxxxxxxxx.com" } ] } 状态码： 400 Bad Request { "error_code" : "common.01000001", "error_msg" : "failed to read http request, please check your input, code: 400, reason: Type mismatch., cause: TypeMismatchException" } 状态码： 401 Unauthorized { "error_code": 'APIG.1002', "error_msg": 'Incorrect token or token resolution failed' } 状态码： 403 Forbidden { "error" : { "code" : "403", "message" : "X-Auth-Token is invalid in the request", "error_code" : null, "error_msg" : null, "title" : "Forbidden" }, "error_code" : "403", "error_msg" : "X-Auth-Token is invalid in the request", "title" : "Forbidden" } 状态码： 404 Not Found { "error_code" : "common.01000001", "error_msg" : "response status exception, code: 404" } 状态码： 408 Request Timeout { "error_code" : "common.00000408", "error_msg" : "timeout exception occurred" } 状态码： 500 Internal Server Error { "error_code" : "common.00000500", "error_msg" : "internal error" }

响应参数 状态码： 200 表4 响应Body参数 参数 参数类型 描述 access_infos Array of AccessInfo objects accessinfo列表。 total Integer accessinfo总数。 表5 AccessInfo 参数 参数类型 描述 vpcep_service_name String 服务名称。 domain String 分组独立域名。 状态码： 400 表6 响应Body参数 参数 参数类型 描述 error_code String 错误码。 error_msg String 错误描述。 common_error_code String CBC公共错误码。 solution_msg String 解决方案描述。 状态码： 404 表7 响应Body参数 参数 参数类型 描述 error_code String 错误码。 error_msg String 错误描述。 common_error_code String CBC公共错误码。 solution_msg String 解决方案描述。 状态码： 500 表8 响应Body参数 参数 参数类型 描述 error_code String 错误码。 error_msg String 错误描述。 common_error_code String CBC公共错误码。 solution_msg String 解决方案描述。

URI GET /v1/{project_id}/instances/{instance_id}/catalogs 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目编号。获取方法，请参见获取项目ID。 instance_id 是 String LakeFormation实例ID。创建实例时自动生成。例如：2180518f-42b8-4947-b20b-adfc53981a25。 表2 Query参数 参数 是否必选 参数类型 描述 branch_name 否 String 分支名称。只能包含字母、数字和下划线，且长度为1~32个字符。默认值为main。 version 否 Long 版本。 deleted 否 Boolean 是否查询被删除元数据。

响应示例 状态码： 200 OK [ { "catalog_name" : "hive", "description" : "Default catalog, for Hive", "location" : "obs://lakeformation/test", "database_location_list" : null, "owner" : "admin", "owner_type" : "USER", "owner_source" : "IAM" } ] 状态码： 400 Bad Request { "error_code" : "common.01000001", "error_msg" : "failed to read http request, please check your input, code: 400, reason: Type mismatch., cause: TypeMismatchException" } 状态码： 401 Unauthorized { "error_code": 'APIG.1002', "error_msg": 'Incorrect token or token resolution failed' } 状态码： 403 Forbidden { "error" : { "code" : "403", "message" : "X-Auth-Token is invalid in the request", "error_code" : null, "error_msg" : null, "title" : "Forbidden" }, "error_code" : "403", "error_msg" : "X-Auth-Token is invalid in the request", "title" : "Forbidden" } 状态码： 404 Not Found { "error_code" : "common.01000001", "error_msg" : "response status exception, code: 404" } 状态码： 408 Request Timeout { "error_code" : "common.00000408", "error_msg" : "timeout exception occurred" } 状态码： 500 Internal Server Error { "error_code" : "common.00000500", "error_msg" : "internal error" }

响应参数 状态码： 200 表4 响应Body参数 参数 参数类型 描述 [数组元素] Array of Catalog objects OK 表5 Catalog 参数 参数类型 描述 catalog_name String catalog名称。 catalog_id String catalogID。 description String 描述信息。 location String 路径地址。例如obs://location/uri/。 database_location_list Array of strings 数据库路径列表。当值为null时，响应Body无该参数。 owner String catalog所有者。LakeFormation服务分为一期和二期，一期响应Body无该参数。 owner_type String 所有者类型，USER-用户，GROUP-组，ROLE-角色。LakeFormation服务分为一期和二期，一期响应Body无该参数。 枚举值： USER ROLE GROUP owner_source String 所有者来源：IAM-云用户、SAML-联邦、LDAP-ld用户、LOCAL-本地用户、AGENTTENANT-委托、OTHER-其它。LakeFormation服务分为一期和二期，一期响应Body无该参数。 枚举值： IAM SAML LDAP LOCAL AGENTTENANT OTHER type String catalog类型，可选值为DEFAULT（代表默认的元数据类型）、CLICKHOUSE（代表CH类型），不设置时默认为DEFAULT。 创建时指定，不可修改。 枚举值： DEFAULT CLICKHOUSE update_time String catalog元数据最后一次修改时间。 状态码： 400 表6 响应Body参数 参数 参数类型 描述 error_code String 错误码。 error_msg String 错误描述。 solution_msg String 解决方案描述。 状态码： 404 表7 响应Body参数 参数 参数类型 描述 error_code String 错误码。 error_msg String 错误描述。 solution_msg String 解决方案描述。 状态码： 500 表8 响应Body参数 参数 参数类型 描述 error_code String 错误码。 error_msg String 错误描述。 solution_msg String 解决方案描述。

响应示例 状态码： 200 租户协议查询响应体 { "agreements" : [ { "agreement_name" : "agreement AAA", "agreement_version" : "v1" }, { "agreement_name" : "agreement BBB", "agreement_version" : "v1" } ], "is_agency" : true } 状态码： 400 Bad Request { "error_code" : "common.01000001", "error_msg" : "failed to read http request, please check your input, code: 400, reason: Type mismatch., cause: TypeMismatchException" } 状态码： 401 Unauthorized { "error_code": 'APIG.1002', "error_msg": 'Incorrect token or token resolution failed' } 状态码： 403 Forbidden { "error" : { "code" : "403", "message" : "X-Auth-Token is invalid in the request", "error_code" : null, "error_msg" : null, "title" : "Forbidden" }, "error_code" : "403", "error_msg" : "X-Auth-Token is invalid in the request", "title" : "Forbidden" } 状态码： 404 Not Found { "error_code" : "common.01000001", "error_msg" : "response status exception, code: 404" } 状态码： 408 Request Timeout { "error_code" : "common.00000408", "error_msg" : "timeout exception occurred" } 状态码： 500 Internal Server Error { "error_code" : "common.00000500", "error_msg" : "internal error" }

响应参数 状态码： 200 表3 响应Header参数 参数 参数类型 描述 X-request-id String 请求ID，定位辅助信息。 表4 响应Body参数 参数 参数类型 描述 agreements Array of TenantAgreement objects 租户协议列表。 is_agency Boolean 是否绑定了委托。 表5 TenantAgreement 参数 参数类型 描述 agreement_name String 协议名称。只能包含字母、数字、下划线和中划线，且长度为1到64个字符。 agreement_version String 协议版本号。只能包含字母和数字，且长度为1到32个字符。 状态码： 400 表6 响应Body参数 参数 参数类型 描述 error_code String 错误码。 error_msg String 错误描述。 common_error_code String CBC公共错误码。 solution_msg String 解决方案描述。 状态码： 404 表7 响应Body参数 参数 参数类型 描述 error_code String 错误码。 error_msg String 错误描述。 common_error_code String CBC公共错误码。 solution_msg String 解决方案描述。 状态码： 500 表8 响应Body参数 参数 参数类型 描述 error_code String 错误码。 error_msg String 错误描述。 common_error_code String CBC公共错误码。 solution_msg String 解决方案描述。