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

식별자. 카탈로그 이름 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)

출력 전용입니다. 카탈로그가 생성된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
update-time

string (Timestamp format)

출력 전용입니다. 카탈로그가 마지막으로 업데이트된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
replicas[]

object (Replica)

출력 전용입니다. 카탈로그 메타데이터의 복제본입니다.
description

string

(선택사항) 사용자가 제공한 카탈로그 설명입니다. 설명은 최대 길이가 1024자(영문 기준)인 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 페더레이션 카탈로그 유형입니다.

복제본

카탈로그의 복제본입니다.

JSON 표현 
{
  "region": string,
  "state": enum (State)
}
필드
region

string

출력 전용입니다. 복제본의 리전입니다. 예: 'us-east1'
state

enum (State)

출력 전용입니다. 복제본의 현재 상태입니다.

주

카탈로그가 여러 리전에 복제된 경우 이 enum은 복제본의 현재 상태를 설명합니다.

열거형
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 표현 
{
  "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

(선택사항) 비공개 네트워크 연결을 통해 원격 카탈로그 (예: 스토리지 버킷의 데이터 파일 액세스)로 전송 계층 트래픽을 라우팅하는 데 사용되는 서비스 디렉터리 리소스 이름입니다.

형식: 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 작업공간 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 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의 계정 식별자입니다. 예를 들어 Snowflake 배포 URL 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 카탈로그 엔드포인트는 https://<baseUrl>/datalake/api/catalog/v1/config?warehouse=workday 형식입니다.

JSON 표현 
{
  "base-url": string,
  "tenant": string
}
필드
base-url

string

필수 항목. 변경할 수 없습니다. Workday 인스턴스의 기준 URL입니다. 예를 들면 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)

출력 전용입니다. 카탈로그 새로고침이 시작된 시간입니다(진행 중인 새로고침 포함).

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
end-time

string (Timestamp format)

출력 전용입니다. 카탈로그 새로고침이 종료되면 진행 중인 새로고침에 대해 설정 해제합니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. '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 카탈로그 구성 옵션을 업데이트합니다.