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)
  },
  "cross-cloud-cache-options": {
    object (CrossCloudCacheOptions)
  },
  "encryption-config": {
    object (EncryptionConfig)
  }
}
字段
name

string

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

enum (CredentialMode)

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

string

仅限输出。用于凭据自动售卖的服务账号，仅限输出。如果从未为目录启用凭证分发，则可能为空。

对于联合目录，系统将始终预配服务账号，并使用该账号访问远程目录以进行后台元数据刷新。如果 google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.IdentityMode 设置为 IDENTITY_MODE_SERVICE_IDENTITY，则也会用于查询。
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

仅限输出。默认位置的存储桶的 GCP 区域，例如 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)

可选。联合目录的配置选项。
cross-cloud-cache-options

object (CrossCloudCacheOptions)

可选。用于跨云缓存数据和元数据文件的配置选项。
encryption-config

object (EncryptionConfig)

可选。自定义加密配置（例如，Cloud KMS 密钥）。

CredentialMode

目录所用的凭据模式。

枚举
CREDENTIAL_MODE_UNSPECIFIED 默认值/未设置的值。此值未使用。
CREDENTIAL_MODE_END_USER 最终用户凭证模式，默认值。进行身份验证的用户必须有权访问目录资源和底层 Google Cloud Storage 对象。
CREDENTIAL_MODE_VENDED_CREDENTIALS

凭证分发模式。进行身份验证的用户只需有权访问目录资源，系统就会为调用方提供降级后的凭据，以便其访问 Google Cloud Storage 对象。在此模式下，所有表操作都需要将 X-Iceberg-Access-Delegation 标头设置为 vended-credentials。系统将在 google.cloud.biglake.v1main.IcebergCatalog.biglake_service_account 中生成一个服务账号，目录管理员必须向该账号授予 Google Cloud Storage 对象访问权限。

如需了解详情，请参阅 https://docs.cloud.google.com/lakehouse/docs/credential-vending。

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 和此列表中的位置。

EncryptionConfig

自定义加密配置（例如，Cloud KMS 密钥）。

JSON 表示法 
{
  "kms-key-name": string
}
字段
kms-key-name

string

可选。用于加密从目录中提取的缓存数据的 Cloud KMS 密钥名称。格式：projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey}

FederatedCatalogOptions

联合目录的配置选项。

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

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "unity-catalog-info": {
    object (UnityCatalogInfo)
  },
  "glue-catalog-info": {
    object (GlueCatalogInfo)
  },
  "snowflake-catalog-info": {
    object (SnowflakeCatalogInfo)
  },
  "workday-catalog-info": {
    object (WorkdayCatalogInfo)
  }
  // End of mutually exclusive fields.
  "secret-name": string,
  "service-directory-name": string
}
字段
refresh-options

object (RefreshOptions)

可选。刷新配置。
refresh-status

object (RefreshStatus)

仅限输出。后台元数据刷新操作的状态。
远程 Iceberg REST 目录的特定信息。以下是互斥字段的列表。在响应中，最多只能设置以下字段之一：
unity-catalog-info

object (UnityCatalogInfo)

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

object (GlueCatalogInfo)

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

object (SnowflakeCatalogInfo)

可选。特定于 Snowflake Horizon Catalog 的信息。
workday-catalog-info

object (WorkdayCatalogInfo)

可选。Workday Data Lake 的特定信息。
互斥字段的结束。
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}

BigQuery 查询使用此属性通过专用网络连接（例如跨云互连）解析专用端点，以提取数据文件（例如 S3 或 Azure Data Lake Storage 中的 Iceberg 数据）。

UnityCatalogInfo

特定于 Databricks Unity Catalog 的信息。Iceberg REST Catalog 端点的格式为：https://<instanceName>/api/2.1/unity-catalog/iceberg-rest/v1/config?warehouse=<catalogName>。

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

string

必需。不可变。Databricks 工作区的实例名称。例如，对于 Databricks 工作区网址 https://1.1.gcp.databricks.com，实例名称为 1.1.gcp.databricks.com。
catalog-name

string

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

string

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

GlueCatalogInfo

AWS Glue Data Catalog 的特定信息。Iceberg REST Catalog 端点的格式为：https://glue.<awsRegion>.amazonaws.com/iceberg/v1/config?warehouse=<warehouse>。

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

string

必需。不可变。AWS Glue Data Catalog 中的仓库位置。

对于默认账号目录，请使用 12 位数的 AWS 账号 ID（例如 111222333444）。对于 Amazon S3 表存储桶，请使用格式 <account_id>:s3tablescatalog/<table_bucket_name>（例如 111222333444:s3tablescatalog/my-table-bucket）。
aws-region

string

必需。不可变。AWS Glue Data Catalog 的 AWS 区域（例如 us-east-1）。为获得最佳性能，联合目录的区域应与 AWS 区域位于同一地理位置和管辖区。
aws-role-arn

string

必需。联合目录用于访问 AWS Glue Data Catalog 的 AWS IAM 角色的 Amazon 资源名称 (ARN)。

SnowflakeCatalogInfo

特定于 Snowflake Horizon Catalog 的信息。Iceberg REST Catalog 端点的格式为：https://<accountIdentifier>.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<warehouse>。

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

string

必需。不可变。Snowflake 中的账号标识符。例如，对于 Snowflake 部署网址 https://myorg-myaccount.snowflakecomputing.com，账号标识符为 myorg-myaccount。
warehouse

string

必需。不可变。Snowflake Horizon Catalog 中的数据库名称。
snowflake-role

string

可选。在工作负载身份联合 (OIDC) 身份验证流程中用于访问 Snowflake Horizon Catalog 的 Snowflake 角色名称。

WorkdayCatalogInfo

Workday Data Lake 的特定信息。Iceberg REST Catalog 端点的格式为：https://<baseUrl>/datalake/api/catalog/v1/config?warehouse=workday。

JSON 表示法 
{
  "base-url": string,
  "tenant": string
}
字段
base-url

string

必需。不可变。Workday 实例的基础网址。例如 impl-services1.wd12.myworkday.com 或 wd501.myworkday.com。
tenant

string

必需。不可变。Workday 租户名称。

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”。

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)

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

CrossCloudCacheOptions

用于跨云缓存数据和元数据文件的配置选项。

JSON 表示法 
{
  "enabled": boolean
}
字段
enabled

boolean

可选。指定是否启用数据和元数据文件的跨云缓存。这只会影响通过 BigQuery 进行的查询。

如果此值为 true，则读取的数据和元数据会存储在缓存中，这可以提高性能并降低跨云查询的网络出站流量费用。

如果此值为 false，则停用跨云缓存。

方法

create

 创建 Iceberg REST Catalog。

delete

 删除 Iceberg REST Catalog。

failover

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

get

 返回 Iceberg REST Catalog 配置选项。

list

 列出 Iceberg REST Catalog。

patch

 更新 Iceberg REST Catalog 配置选项。