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

資源：IcebergCatalog

Iceberg REST 目錄資訊。

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

ID。目錄名稱，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)

這是必要旗標，目錄類型。目錄必須提供。目錄類型不可變動，但可從 CATALOG_TYPE_GCS_BUCKET 轉換為 CATALOG_TYPE_BIGLAKE。
default-location

string

選用。目錄的預設儲存位置，例如 gs://my-bucket。如果是 Google Cloud Storage bucket 目錄，這項屬性僅供輸出。

如果是 BigLake 目錄，則必須提供這個欄位，並指向 Google Cloud Storage bucket 或該 bucket 內的路徑。如果未在命名空間或資料表層級指定位置，這個路徑會做為建構資料表資料和中繼資料目錄完整路徑的基礎目錄。完整路徑是由預設位置附加命名空間和資料表 ID 所組成。
storage-regions[]

string

僅供輸出。預設位置 bucket 的 GCP 區域，例如 us-central1、nam4 或 us。除了設定使用自訂雙區域值區的目錄外，這項屬性會包含所有位置的值。如果是自訂雙區域值區，則會包含值區的兩個區域。這個欄位的區域應位於目錄主要位置的管轄範圍內或附近。
create-time

string (Timestamp format)

僅供輸出。目錄建立時間。

使用 RFC 3339，產生的輸出內容一律會經過 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 正規化，並使用 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 目錄。

如果未設定這個欄位，或 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 bucket 目錄類型。
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 bucket 和位置 (例如 gs://my-other-bucket/...)。這個欄位目前僅用於 BigLake 目錄。

如果 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 中的密鑰資源名稱，格式為 projects/{projectId}/locations/{location}/secrets/{secret_id} 或 projects/{projectId}/locations/{location}/secrets/{secret_id}/versions/{version_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 資源名稱，用於透過私人網路連線，將傳輸層流量轉送至遠端目錄 (例如儲存空間 bucket 中的資料檔案存取權)。

格式：projects/{projectId}/locations/{locationId}/namespaces/{namespace_id}/services/{serviceId}

BigQuery 查詢會使用這項設定，透過 Cross-Cloud Interconnect 等私人網路連線，解析私人端點以擷取資料檔案 (例如 S3 或 Azure Data Lake Storage 中的 Iceberg 資料)。

UnityCatalogInfo

Databricks Unity Catalog 專屬資訊。Iceberg REST 目錄端點的格式為：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

選用。Databricks 服務主體的應用程式 ID，該主體會在 OIDC 驗證流程中存取 Databricks Unity Catalog。

GlueCatalogInfo

AWS Glue Data Catalog 專屬資訊。Iceberg REST 目錄端點的格式為：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 IAM 角色存取 AWS Glue Data Catalog，請輸入該角色的 Amazon Resource Name (ARN)。

SnowflakeCatalogInfo

Snowflake Horizon Catalog 專屬資訊。Iceberg REST 目錄端點的格式為：https://<accountIdentifier>.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<warehouse>。

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

string

這是必要旗標，不可變動。Snowflake 帳戶 ID。舉例來說，假設 Snowflake 部署網址為 https://myorg-myaccount.snowflakecomputing.com，帳戶 ID 會是 myorg-myaccount。
warehouse

string

這是必要旗標，不可變動。Snowflake Horizon Catalog 中的資料庫名稱。
snowflake-role

string

選用。在 Workload Identity Federation (OIDC) 驗證流程中，用來存取 Snowflake Horizon Catalog 的 Snowflake 角色名稱。

WorkdayCatalogInfo

Workday Data Lake 專屬資訊。Iceberg REST 目錄端點的格式為：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，系統會停用中繼資料背景重新整理功能。如果更新現有聯合目錄的此欄位，系統必須先完成先前的背景中繼資料重新整理作業，新的重新整理間隔才會生效。

以秒為單位的時間長度，最多 9 個小數位數，結尾為「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 正規化，並使用 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 正規化，並使用 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 目錄。

delete

 刪除 Iceberg REST 目錄。

failover

 將目錄容錯移轉至新的主要副本區域。

get

 傳回 Iceberg REST 目錄設定選項。

list

 列出 Iceberg REST 目錄。

patch

 更新 Iceberg REST 目錄設定選項。