REST Resource: iceberg.v1.restcatalog.extensions.projects.catalogs

资源：IcebergCatalog

Iceberg REST Catalog 信息。

JSON 表示法 
{
  "name": string,
  "credential-mode": enum (CredentialMode),
  "biglake-service-account": string,
  "biglake-service-account-id": string,
  "catalog-type": enum (CatalogType),
  "default-location": string,
  "storage-regions": [
    string
  ],
  "create-time": string,
  "update-time": string,
  "replicas": [
    {
      object (Replica)
    }
  ],
  "description": string,
  "restricted-locations-config": {
    object (RestrictedLocationsConfig)
  },
  "federated-catalog-options": {
    object (FederatedCatalogOptions)
  }
}
字段
name

string

标识符。目录名称，projects/my-project/catalogs/my-catalog。该字段不可更改。 对于 catalogs.create，此字段会被忽略。
credential-mode

enum (CredentialMode)

可选。目录的凭据模式。
biglake-service-account

string

仅限输出。用于凭据自动售卖的服务账号，仅限输出。如果从未为目录启用凭据自动售卖，则可能为空。对于联合目录，系统将始终预配服务账号，并使用该账号通过访问 Secret Manager 密文或身份联合来访问远程 Iceberg REST 目录。
biglake-service-account-id

string

仅限输出。服务账号的唯一 ID。这用于联合场景。
catalog-type

enum (CatalogType)

必需。目录类型。对于 catalogs.create 而言必填。目录类型是不可变的，但从 CATALOG_TYPE_GCS_BUCKET 转换为 CATALOG_TYPE_BIGLAKE 的情况除外。
default-location

string

可选。目录的默认存储位置，例如 gs://my-bucket。对于 Google Cloud Storage 存储桶目录，此属性仅为输出。

对于 BigLake 目录，必须提供此字段，并且该字段必须指向 Google Cloud Storage 存储桶或该存储桶中的路径。此路径用作构建表的数据和元数据目录完整路径的基本目录，前提是在命名空间或表级别未指定位置。完整路径是通过将命名空间和表标识符附加到默认位置来形成的。
storage-regions[]

string

仅限输出。默认位置的存储桶的 Google Cloud 区域，例如 us-central1、nam4 或 us。此属性将包含所有位置的一个值，但配置为使用自定义双区域存储桶的目录除外，在这种情况下，此属性将包含存储桶的两个区域。此字段的区域应位于目录主要位置的管辖范围内或附近。
create-time

string (Timestamp format)

仅限输出。目录的创建时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
update-time

string (Timestamp format)

仅限输出。目录的上次更新时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
replicas[]

object (Replica)

仅限输出。目录元数据的副本数。
description

string

可选。用户提供的目录说明。说明必须是 UTF-8 字符串，长度上限为 1024 个字符。
restricted-locations-config

object (RestrictedLocationsConfig)

可选。受限位置配置。此字段目前仅用于 BigLake Catalog。

如果未设置此字段，或者 restrictedLocationsConfig.restricted_locations 为空，则允许所有可访问的位置。如果 restrictedLocationsConfig.restricted_locations 不为空，则仅允许使用 defaultLocation 和 restrictedLocationsConfig.restricted_locations 中的位置。
federated-catalog-options

object (FederatedCatalogOptions)

可选。联合目录的配置选项。

CredentialMode

目录所用的凭据模式。

枚举
CREDENTIAL_MODE_UNSPECIFIED 默认值。此值未使用。
CREDENTIAL_MODE_END_USER 最终用户凭据，默认。进行身份验证的用户必须有权访问目录资源和相应的 Google Cloud Storage 文件。
CREDENTIAL_MODE_VENDED_CREDENTIALS

使用凭据自动售卖。进行身份验证的用户必须有权访问目录资源，并且系统会向调用方提供降级凭据，以访问 Google Cloud Storage 文件。在此模式下，所有表操作都需要包含值为 vended-credentials 的 X-Iceberg-Access-Delegation 标头。系统将生成一个服务账号，目录管理员必须向该服务账号授予适当的权限。

如需了解详情，请参阅：https://github.com/apache/iceberg/blob/931865ecaf40a827f9081dddb675bf1c95c05461/open-api/rest-catalog-open-api.yaml#L1854。

CatalogType

确定目录类型。

枚举
CATALOG_TYPE_UNSPECIFIED 默认值。此值未使用。
CATALOG_TYPE_GCS_BUCKET Google Cloud Storage 存储桶目录类型。
CATALOG_TYPE_BIGLAKE BigLake 目录类型。
CATALOG_TYPE_FEDERATED 联合目录类型。

副本

目录的副本。

JSON 表示法 
{
  "region": string,
  "state": enum (State)
}
字段
region

string

仅限输出。副本的区域。例如“us-east1”
state

enum (State)

仅限输出。复制的当前状态。

州

如果目录复制到多个区域，此枚举会描述副本的当前状态。

枚举
STATE_UNKNOWN 副本状态未知。
STATE_PRIMARY 副本是可写的主副本。
STATE_PRIMARY_IN_PROGRESS 副本最近被分配为主副本，但并非所有命名空间都可写入。
STATE_SECONDARY 相应副本是只读的次要副本。

RestrictedLocationsConfig

位置限制的配置。

JSON 表示法 
{
  "restricted-locations": [
    string
  ]
}
字段
restricted-locations[]

string

可选。目录中资源允许使用的其他 Google Cloud Storage 存储分区和位置（例如 gs://my-other-bucket/...）。此字段目前仅用于 BigLake Catalog。

如果 restrictedLocations 为空且启用了不受限制的目录创建，则允许所有可访问的位置。否则，仅允许使用 defaultLocation 和此列表中的位置。

FederatedCatalogOptions

联邦目录的配置选项。

JSON 表示法 
{
  "refresh-options": {
    object (RefreshOptions)
  },
  "refresh-status": {
    object (RefreshStatus)
  },

  // Union field remote_catalog_info can be only one of the following:
  "unity-catalog-info": {
    object (UnityCatalogInfo)
  },
  "glue-catalog-info": {
    object (GlueCatalogInfo)
  },
  "snowflake-catalog-info": {
    object (SnowflakeCatalogInfo)
  }
  // End of list of possible types for union field remote_catalog_info.
  "secret-name": string,
  "service-directory-name": string
}
字段
refresh-options

object (RefreshOptions)

可选。刷新配置。
refresh-status

object (RefreshStatus)

仅限输出。后台刷新操作的状态。
联合字段 remote_catalog_info。特定于远程 Iceberg REST Catalog 的信息。remote_catalog_info 只能是下列其中一项：
unity-catalog-info

object (UnityCatalogInfo)

可选。Databricks Unity Catalog 特有的信息。
glue-catalog-info

object (GlueCatalogInfo)

可选。特定于 AWS Glue Catalog 的信息。
snowflake-catalog-info

object (SnowflakeCatalogInfo)

可选。特定于 Snowflake Catalog 的信息。
secret-name

string

可选。Secret Manager 中的 Secret 资源名称，格式为 projects/{projectId}/locations/{location}/secrets/{secret_id} 或 projects/{projectId}/locations/{location}/secrets/{secret_id}/versions/{version_id}。

项目 ID 必须与目录的项目 ID 一致，位置必须与目录的位置一致。如果未指定版本，则使用最新版本。

如果设置了 google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.UnityCatalogInfo.service_principal_application_id 或 google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.SnowflakeCatalogInfo.snowflake_role，则不会使用此字段。
service-directory-name

string

可选。用于通过跨云互连经由专用网络连接路由流量的 Service Directory 资源名称，格式为 projects/{projectId}/locations/{locationId}/namespaces/{namespace_id}/services/{serviceId}。

UnityCatalogInfo

Unity Catalog 信息。

JSON 表示法 
{
  "instance-name": string,
  "catalog-name": string,
  "service-principal-application-id": string
}
字段
instance-name

string

必需。实例名称是登录 Databricks 部署时网址的第一部分。例如，对于 Databricks on Google Cloud 工作区网址 https://1.1.Google Cloud.databricks.com，实例名称为 1.1.Google Cloud.databricks.com。
catalog-name

string

必需。Unity Catalog 中的目录名称。
service-principal-application-id

string

可选。在 OIDC 身份验证流程中用于访问 Unity Catalog 的 Databricks 服务主账号的应用 ID。

GlueCatalogInfo

AWS Glue Catalog 信息。我们支持区域性 AWS Glue 默认账号目录和 S3 表存储分区。

JSON 表示法 
{
  "warehouse": string,
  "aws-region": string,
  "aws-role-arn": string
}
字段
warehouse

string

必需。不可变。要连接到区域 AWS Glue Iceberg REST 目录的数据仓库。如需顶级访问权限，请使用 AWS 账号 ID（例如 111222333444）。对于 S3 表存储桶，数据仓库的格式为：111222333444:s3tablescatalog/。用于访问目录的网址将为 https://glue.{awsRegion}.amazonaws.com/iceberg/v1?warehouse={warehouse}。必须为非空，且不可变。
aws-region

string

必需。不可变。要连接的 Glue 目录的 AWS 区域。该区域应与联合目录位于同一地理区域和管辖区。不得为空，且不可变。
aws-role-arn

string

必需。联合目录将承担的 Glue 目录的 AWS 角色 ARN，以访问该目录。不得为空。可以更新。

SnowflakeCatalogInfo

Snowflake 目录信息。

JSON 表示法 
{
  "account-identifier": string,
  "warehouse": string,
  "snowflake-role": string
}
字段
account-identifier

string

必需。Snowflake 中的账号标识符（请参阅：https://docs.snowflake.com/en/user-guide/admin-account-identifier)）。它是登录 Snowflake 部署网址的前缀。例如：https://.snowflakecomputing.com。
warehouse

string

必需。要连接的 Snowflake REST 目录中的仓库。https://.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=.

这是包含要联合的 Iceberg 元数据的 Snowflake 数据库名称。

不得为空。
snowflake-role

string

可选。要在 Iceberg REST Catalog 会话的 OAuth 令牌范围中请求的特定 Snowflake 角色名称（通过 session:role:$ROLE）。此角色授予 Google Cloud BigLake 服务账号与 Iceberg 目录、命名空间和表进行交互所需的权限。

注意：此处提供的角色必须是 DEFAULT_ROLE，或者必须授予给映射到 BigLake 服务账号的 Snowflake 服务用户。

RefreshOptions

刷新配置。

JSON 表示法 
{
  "refresh-schedule": {
    object (RefreshSchedule)
  },
  "refresh-scope": {
    object (RefreshScope)
  }
}
字段
refresh-schedule

object (RefreshSchedule)

可选。时间表用于定义是否应安排元数据刷新以及何时安排。
refresh-scope

object (RefreshScope)

可选。刷新范围配置。

RefreshSchedule

时间表用于定义是否应安排元数据刷新以及何时安排。

JSON 表示法 
{
  "refresh-interval": string
}
字段
refresh-interval

string (Duration format)

可选。从远程目录刷新元数据的间隔。如果未设置或值小于等于 0，则会停用后台刷新。如果为现有联邦目录更新此字段，则必须先完成之前的后台刷新，新的刷新间隔才会生效。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

RefreshScope

范围定义了要刷新的命名空间子集。

JSON 表示法 
{
  "namespace-filters": [
    string
  ]
}
字段
namespace-filters[]

string

可选。用于确定哪些命名空间包含在刷新过程中的过滤器。- 空列表表示包含所有命名空间。- “[namespaces]”表示包含指定的命名空间。['ns1', 'ns2']：仅发现命名空间“ns1”和“ns2”。允许的命名空间过滤器数量上限为 32。

RefreshStatus

远程目录后台刷新状态。

JSON 表示法 
{
  "start-time": string,
  "end-time": string,
  "status": {
    object (Status)
  }
}
字段
start-time

string (Timestamp format)

仅限输出。目录刷新已开始（包括正在进行的刷新）。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
end-time

string (Timestamp format)

仅限输出。当目录刷新结束时，取消设置正在进行的刷新。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
status

object (Status)

仅限输出。上次后台刷新操作的状态，对于正在进行的刷新，此字段未设置。

方法

create

 创建 Iceberg REST Catalog。

delete

 删除 Iceberg REST Catalog。

failover

 将目录故障切换到新的主副本区域。

get

 返回 Iceberg REST Catalog 配置选项。

list

 列出 Iceberg REST Catalog。

patch

 更新 Iceberg REST Catalog 配置选项。