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)

必須。カタログタイプ。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 など)。これには、カスタム デュアルリージョン バケットを使用するように構成されたカタログを除き、すべてのロケーションに 1 つの値が含まれます。カスタム デュアルリージョン バケットを使用するように構成されたカタログの場合は、バケットの 2 つのリージョンが含まれます。このフィールドのリージョンは、カタログのプライマリ ロケーションの管轄区域内またはその近くにある必要があります。

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

省略可。ユーザーが指定したカタログの説明。説明は 1,024 文字以内の UTF-8 文字列にする必要があります。

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 バケットのカタログタイプ。
CATALOG_TYPE_BIGLAKE BigLake カタログのタイプ。
CATALOG_TYPE_FEDERATED 連携カタログのタイプ。
CATALOG_TYPE_ALLOYDB_AGENT_MODE エージェント モードで AlloyDB テーブルをクエリするためのカタログ。

レプリカ

カタログのレプリカ。

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 カタログでのみ使用されています。

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 表現
{
  "identity-mode": enum (IdentityMode),
  "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:
  "identity-federation-organization-service-account": {
    object (IdentityFederationOrganizationServiceAccount)
  }
  // End of mutually exclusive fields.

  // 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,
  "metadata-service-directory-name": string,
  "user-identity-federation-oidc-claims": {
    object (UserIdentityFederationOidcClaims)
  },
  "user-identity-federation-oidc": {
    object (UserIdentityFederationOidc)
  }
}
フィールド
identity-mode

enum (IdentityMode)

省略可。連携カタログの ID モード。

refresh-options

object (RefreshOptions)

省略可。構成を更新します。

refresh-status

object (RefreshStatus)

出力専用。バックグラウンド メタデータ更新オペレーションのステータス。

相互に排他的なフィールドのリストは次のとおりです。レスポンスに設定されるフィールドは、最大 1 つです。
identity-federation-organization-service-account

object (IdentityFederationOrganizationServiceAccount)

出力専用。ID 連携に使用される組織レベルのサービス アカウント。

相互に排他的なフィールドの終了。
リモート Iceberg REST カタログに固有の情報。相互に排他的なフィールドのリストは次のとおりです。レスポンスに設定されるフィールドは、最大 1 つです。
unity-catalog-info

object (UnityCatalogInfo)

省略可。Databricks Unity Catalog に固有の情報。

glue-catalog-info

object (GlueCatalogInfo)

省略可。AWS Glue Data Catalog に固有の情報。

snowflake-catalog-info

object (SnowflakeCatalogInfo)

省略可。Snowflake Horizon カタログに固有の情報。

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 はカタログのプロジェクトと一致し、ロケーションはカタログのロケーションと一致する必要があります。バージョンが指定されていない場合は、最新バージョンが使用されます。

このフィールドは、google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.UnityCatalogInfo.service_principal_application_id、google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.SnowflakeCatalogInfo.snowflake_role、google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.WorkdayCatalogInfo.api_client_client_id が設定されている場合は使用されません。

service-directory-name

string

省略可。プライベート ネットワーク接続を介してリモート カタログ(ストレージ バケット内のデータファイル アクセスなど)と通信するトランスポート層トラフィックをルーティングするために使用される Service Directory リソース名。

形式: projects/{projectId}/locations/{locationId}/namespaces/{namespace_id}/services/{serviceId}

このリソース名は、BigQuery クエリが Cross-Cloud Interconnect などのプライベート ネットワーク接続を介してデータファイル(S3 や Azure データレイク ストレージの Iceberg データなど)を取得する際に、プライベート エンドポイントの名前を解決するために使用されます。

metadata-service-directory-name

string

省略可。プライベート ネットワーク接続を介してリモート カタログと通信するメタデータ レイヤ トラフィックをルーティングするために使用される Service Directory リソース名。

形式: projects/{projectId}/locations/{locationId}/namespaces/{namespace_id}/services/{serviceId}

Cross-Cloud Interconnect などのプライベート ネットワーク接続を介してカタログ メタデータ(Iceberg 構成、名前空間、テーブルなど)を取得するために使用されます。oauth2ServerUrl が設定されていない場合に OAuth トークンを取得するためにも使用されます。このフィールドが設定されていない場合、リクエストは公共のインターネット経由で送信されます。

user-identity-federation-oidc-claims
(deprecated)

object (UserIdentityFederationOidcClaims)

出力専用。非推奨: 代わりに、google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.user_identity_federation_oidc を使用してください。

ユーザー ID 連携の ID トークンで出力される OIDC クレーム。

user-identity-federation-oidc

object (UserIdentityFederationOidc)

出力専用。ユーザー ID 連携の OIDC 構成。

IdentityFederationOrganizationServiceAccount

ID 連携に使用される組織レベルのサービス アカウント(出力専用)。カタログで ID 連携が有効になっていない場合は、空になることがあります。

JSON 表現
{
  "service-account": string,
  "service-account-unique-id": string
}
フィールド
service-account

string

出力専用。組織レベルのサービス アカウントのメールアドレス。

service-account-unique-id

string

出力専用。組織レベルのサービス アカウントの一意の ID。

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 ワークスペースの URL が 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 カタログのエンドポイントの形式は 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 カタログに固有の情報。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 デプロイ URL が https://myorg-myaccount.snowflakecomputing.com の場合、アカウント ID は myorg-myaccount です。

アカウント ID には、英字、数字、アンダースコアを使用できます。セグメントはハイフン(-)またはドット(.)で区切ります。これは、組織アカウント形式(例: myorg-myaccount)、以前のアカウント ロケータ形式(例: xy12345.us-east-1)、プライベート接続(PrivateLink)形式(例: myorg-myaccount.privatelink、xy12345.us-east-1.privatelink)をサポートしています。詳細については、https://docs.snowflake.com/en/user-guide/admin-account-identifier をご覧ください。

warehouse

string

必須。変更不可。Snowflake Horizon カタログのデータベース名。

snowflake-role

string

省略可。Workload Identity 連携(OIDC)認証フローで Snowflake Horizon カタログへのアクセスをスコープするために使用される Snowflake ロール。

WorkdayCatalogInfo

Workday Data Lake に固有の情報。Iceberg REST カタログのエンドポイントの形式は https://<baseUrl>/datalake/api/catalog/v1/config?warehouse=workday です。

JSON 表現
{
  "base-url": string,
  "tenant": string,
  "api-client-client-id": string
}
フィールド
base-url

string

必須。変更不可。Workday インスタンスのベース URL。たとえば、impl-services1.wd12.myworkday.com や、wd501.myworkday.com です。

tenant

string

必須。変更不可。Workday のテナント名。

api-client-client-id

string

省略可。OIDC 認証フローで Workday Data Lake へのアクセスに使用される Workday API クライアントのクライアント ID。

IdentityMode

カタログがクエリに使用する ID モード。

列挙型
IDENTITY_MODE_UNSPECIFIED デフォルト値 / 未設定値。この値は IDENTITY_MODE_SERVICE_IDENTITY と同じように扱われます。
IDENTITY_MODE_SERVICE_IDENTITY クエリは、google.cloud.biglake.v1main.IcebergCatalog.biglake_service_account のサービス アカウントを使用して実行されます。
IDENTITY_MODE_USER_IDENTITY_FEDERATION

クエリをエンドユーザー ID で実行し、リモート カタログに伝播します。リモート カタログに ID 連携が構成されている必要があります。

詳細については、https://docs.cloud.google.com/lakehouse/docs/about-cross-cloud-data-access#identity-mode をご覧ください。

UserIdentityFederationOidcClaims

IDENTITY_MODE_USER_IDENTITY_FEDERATION が有効になっているときに ID トークンで出力される OIDC クレーム。

これらの値は、トークンの ID プロバイダ(発行者)と対象の受信者(オーディエンス)を識別します。ユーザー ID 連携を有効にするには、この発行者を信頼し、このオーディエンスを想定するようにリモート カタログを構成する必要があります。

JSON 表現
{
  "issuer-url": string,
  "audience": string
}
フィールド
issuer-url

string

出力専用。ID プロバイダの発行元 URL。

audience

string

出力専用。このカタログがトークンで想定するオーディエンス。

UserIdentityFederationOidc

IDENTITY_MODE_USER_IDENTITY_FEDERATION が有効になっているときに使用される OIDC 構成。

ユーザー ID 連携を有効にするには、これらのパラメータを持つトークンを信頼するようにリモート カタログを構成する必要があります。

JSON 表現
{
  "issuer-url": string,
  "audience": string,
  "jwks-url": string
}
フィールド
issuer-url

string

出力専用。ID プロバイダの発行元 URL。

audience

string

出力専用。このカタログがトークンで想定するオーディエンス。

jwks-url

string

出力専用。トークンの検証に使用される公開鍵を提供する JSON Web Key Set(JWKS)の URL。Snowflake Horizon 連携カタログにのみ設定されます。Snowflake セキュリティ統合で EXTERNAL_OAUTH_JWS_KEYS_URL として使用されます。

RefreshOptions

構成を更新します。

JSON 表現
{
  "refresh-schedule": {
    object (RefreshSchedule)
  },
  "refresh-scope": {
    object (RefreshScope)
  }
}
フィールド
refresh-schedule

object (RefreshSchedule)

省略可。schedule は、メタデータの更新をスケジュールするかどうか、およびスケジュールする場合のタイミングを定義します。

refresh-scope

object (RefreshScope)

省略可。スコープ構成を更新します。

RefreshSchedule

schedule は、メタデータの更新をスケジュールするかどうか、およびスケジュールする場合のタイミングを定義します。

JSON 表現
{
  "refresh-interval": string
}
フィールド
refresh-interval

string (Duration format)

省略可。リモート カタログからメタデータを更新する間隔。未設定の場合、または値が 0 以下の場合は、バックグラウンドでのメタデータの更新が無効になります。既存の連携カタログでこのフィールドが更新された場合、新しい更新間隔が有効になる前に、以前のバックグラウンド メタデータの更新が完了している必要があります。

s で終わる小数 9 桁までの秒単位の期間。例: "3.5s"。

RefreshScope

スコープは、更新する名前空間のサブセットを定義します。

JSON 表現
{
  "namespace-filters": [
    string
  ]
}
フィールド
namespace-filters[]

string

省略可。更新プロセスに含める名前空間を決定するフィルタ。- 空のリストは、すべての Namespace を含めることを意味します。- "[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 カタログの構成オプションを更新します。