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

Recurso: IcebergCatalog

As informações do catálogo REST do Iceberg.

Representação 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)
  }
}
Campos
name

string

Identificador. O nome do catálogo, projects/my-project/catalogs/my-catalog. Este campo não pode ser modificado. Esse campo é ignorado para "catalogs.create".
credential-mode

enum (CredentialMode)

Opcional. O modo de credencial do catálogo.
biglake-service-account

string

Apenas saída. A conta de serviço usada para venda de credenciais, somente saída. Pode estar vazio se a venda de credenciais nunca for ativada para o catálogo.

Para catálogos federados, a conta de serviço sempre será provisionada e usada para acessar o catálogo remoto para atualização de metadados em segundo plano. Se google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.IdentityMode estiver definido como IDENTITY_MODE_SERVICE_IDENTITY, ele também será usado para consultas.
biglake-service-account-id

string

Apenas saída. O ID exclusivo da conta de serviço. Isso é usado para cenários de federação.
catalog-type

enum (CatalogType)

Obrigatório. O tipo de catálogo. Obrigatório para "catalogs.create". O tipo de catálogo é imutável, exceto no caso da conversão de CATALOG_TYPE_GCS_BUCKET para CATALOG_TYPE_BIGLAKE.
default-location

string

Opcional. O local de armazenamento padrão do catálogo, por exemplo, gs://my-bucket. Para catálogos de buckets do Google Cloud Storage, isso é somente saída.

Para catálogos do BigLake, esse campo precisa ser fornecido e apontar para um bucket do Google Cloud Storage ou um caminho dentro desse bucket. Esse caminho serve como o diretório base para construir o caminho completo para os diretórios de dados e metadados de uma tabela quando um local não é especificado no nível do namespace ou da tabela. O caminho completo é formado anexando os identificadores de namespace e tabela ao local padrão.
storage-regions[]

string

Apenas saída. As regiões do GCP do bucket do local padrão, por exemplo, us-central1, nam4 ou us. Ele vai conter um valor para todos os locais, exceto para os catálogos configurados para usar buckets birregionais personalizados, em que ele vai conter as duas regiões do bucket. As regiões desse campo precisam estar na jurisdição ou perto do local principal do catálogo.
create-time

string (Timestamp format)

Apenas saída. Quando o catálogo foi criado.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
update-time

string (Timestamp format)

Apenas saída. Quando o catálogo foi atualizado pela última vez.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
replicas[]

object (Replica)

Apenas saída. As réplicas dos metadados do catálogo.
description

string

Opcional. Uma descrição do catálogo fornecida pelo usuário. A descrição precisa ser uma string UTF-8 com um tamanho máximo de 1.024 caracteres.
restricted-locations-config

object (RestrictedLocationsConfig)

Opcional. Configuração de locais restritos. No momento, esse campo é usado apenas para catálogos do BigLake.

Se este campo não for definido ou se restrictedLocationsConfig.restricted_locations estiver vazio, todos os locais acessíveis serão permitidos. Se restrictedLocationsConfig.restricted_locations não estiver vazio, apenas locais em defaultLocation e restrictedLocationsConfig.restricted_locations serão permitidos.
federated-catalog-options

object (FederatedCatalogOptions)

Opcional. Opções de configuração para catálogos federados.
cross-cloud-cache-options

object (CrossCloudCacheOptions)

Opcional. Opções de configuração para armazenamento em cache entre nuvens de arquivos de dados e metadados.
encryption-config

object (EncryptionConfig)

Opcional. Configuração de criptografia personalizada (por exemplo, chaves do Cloud KMS).

CredentialMode

O modo de credencial usado para o catálogo.

Tipos enumerados
CREDENTIAL_MODE_UNSPECIFIED Valor padrão/não definido. Esse valor não é usado.
CREDENTIAL_MODE_END_USER Modo de credenciais do usuário final, padrão. O usuário autenticado precisa ter acesso aos recursos do catálogo e aos objetos do Google Cloud Storage.
CREDENTIAL_MODE_VENDED_CREDENTIALS

Modo de fornecimento de credenciais. O usuário autenticado só precisa de acesso aos recursos do catálogo, e o sistema vai fornecer ao caller credenciais com escopo reduzido para acessar os objetos do Google Cloud Storage. Todas as operações de tabela nesse modo exigem que o cabeçalho X-Iceberg-Access-Delegation seja definido como vended-credentials. O sistema vai gerar uma conta de serviço em google.cloud.biglake.v1main.IcebergCatalog.biglake_service_account, a que o administrador do catálogo precisa conceder acesso ao objeto do Google Cloud Storage.

Consulte https://docs.cloud.google.com/lakehouse/docs/credential-vending para mais detalhes.

CatalogType

Determina o tipo de catálogo.

Tipos enumerados
CATALOG_TYPE_UNSPECIFIED Valor padrão/não definido. Esse valor não é usado.
CATALOG_TYPE_GCS_BUCKET Tipo de catálogo do bucket do Google Cloud Storage.
CATALOG_TYPE_BIGLAKE Tipo de catálogo do BigLake.
CATALOG_TYPE_FEDERATED Tipo de catálogo federado.

Réplica

A réplica do catálogo.

Representação JSON 
{
  "region": string,
  "state": enum (State)
}
Campos
region

string

Apenas saída. A região da réplica. Por exemplo, "us-east1"
state

enum (State)

Apenas saída. O estado atual da réplica.

Estado

Se o catálogo for replicado para várias regiões, esse enum descreverá o estado atual da réplica.

Tipos enumerados
STATE_UNKNOWN Valor padrão/não definido. Esse valor não é usado.
STATE_PRIMARY A réplica é a instância primária gravável.
STATE_PRIMARY_IN_PROGRESS A réplica foi recentemente atribuída como primária, mas nem todos os namespaces ainda são graváveis.
STATE_SECONDARY A réplica é uma réplica secundária somente leitura.

RestrictedLocationsConfig

Configuração de restrições de local.

Representação JSON 
{
  "restricted-locations": [
    string
  ]
}
Campos
restricted-locations[]

string

Opcional. Outros buckets e locais do Google Cloud Storage (por exemplo, gs://my-other-bucket/...) que podem ser usados por recursos em um catálogo. No momento, esse campo é usado apenas para catálogos do BigLake.

Se restrictedLocations estiver vazio e a criação irrestrita de catálogos estiver ativada, todos os locais acessíveis serão permitidos. Caso contrário, apenas defaultLocation e os locais nesta lista são permitidos.

EncryptionConfig

Configuração de criptografia personalizada (por exemplo, chaves do Cloud KMS).

Representação JSON 
{
  "kms-key-name": string
}
Campos
kms-key-name

string

Opcional. Nome da chave do Cloud KMS usada para criptografar dados armazenados em cache extraídos do catálogo. Formato: projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey}

FederatedCatalogOptions

Opções de configuração para um catálogo federado.

Representação 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
}
Campos
refresh-options

object (RefreshOptions)

Opcional. Atualize a configuração.
refresh-status

object (RefreshStatus)

Apenas saída. O status das operações de atualização de metadados em segundo plano.
Informações específicas do catálogo REST do Iceberg remoto. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
unity-catalog-info

object (UnityCatalogInfo)

Opcional. Informações específicas do Databricks Unity Catalog.
glue-catalog-info

object (GlueCatalogInfo)

Opcional. Informações específicas do AWS Glue Data Catalog.
snowflake-catalog-info

object (SnowflakeCatalogInfo)

Opcional. Informações específicas do catálogo do Snowflake Horizon.
workday-catalog-info

object (WorkdayCatalogInfo)

Opcional. Informações específicas do Workday Data Lake.
Fim dos campos mutuamente exclusivos.
secret-name

string

Opcional. O nome do recurso secreto no Secret Manager, no formato projects/{projectId}/locations/{location}/secrets/{secret_id} ou projects/{projectId}/locations/{location}/secrets/{secret_id}/versions/{version_id}.

O ID do projeto precisa corresponder ao projeto do catálogo, e o local precisa corresponder ao local do catálogo. Se nenhuma for especificada, a versão mais recente será usada.

Esse campo não é usado quando google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.UnityCatalogInfo.service_principal_application_id ou google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.SnowflakeCatalogInfo.snowflake_role está definido.
service-directory-name

string

Opcional. O nome do recurso do Service Directory usado para rotear o tráfego da camada de transporte com o catálogo remoto (por exemplo, acesso a arquivos de dados em buckets de armazenamento) por uma conexão de rede privada.

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

Usado por consultas do BigQuery para resolver endpoints particulares e buscar arquivos de dados (por exemplo, dados do Iceberg no S3 ou no Azure Data Lake Storage) por uma conexão de rede particular, como o Interconexão entre nuvens.

UnityCatalogInfo

Informações específicas do Databricks Unity Catalog. O endpoint do catálogo REST do Iceberg tem o formato: https://<instanceName>/api/2.1/unity-catalog/iceberg-rest/v1/config?warehouse=<catalogName>.

Representação JSON 
{
  "instance-name": string,
  "catalog-name": string,
  "service-principal-application-id": string
}
Campos
instance-name

string

Obrigatório. Imutável. O nome da instância do espaço de trabalho do Databricks. Por exemplo, para o URL do espaço de trabalho do Databricks https://1.1.gcp.databricks.com, o nome da instância é 1.1.gcp.databricks.com.
catalog-name

string

Obrigatório. Imutável. O nome do catálogo no Databricks Unity Catalog.
service-principal-application-id

string

Opcional. O ID do aplicativo do principal de serviço do Databricks usado para acessar o Databricks Unity Catalog no fluxo de autenticação do OIDC.

GlueCatalogInfo

Informações específicas do AWS Glue Data Catalog. O endpoint do catálogo REST do Iceberg tem o formato: https://glue.<awsRegion>.amazonaws.com/iceberg/v1/config?warehouse=<warehouse>.

Representação JSON 
{
  "warehouse": string,
  "aws-region": string,
  "aws-role-arn": string
}
Campos
warehouse

string

Obrigatório. Imutável. O local do warehouse no AWS Glue Data Catalog.

Para o catálogo de contas padrão, use o ID da conta da AWS de 12 dígitos (por exemplo, 111222333444). Para um bucket de tabela do Amazon S3, use o formato <account_id>:s3tablescatalog/<table_bucket_name> (por exemplo, 111222333444:s3tablescatalog/my-table-bucket).
aws-region

string

Obrigatório. Imutável. A região da AWS do AWS Glue Data Catalog (por exemplo, us-east-1). Para ter o melhor desempenho, a região do catálogo federado precisa estar na mesma localização geográfica e jurisdição que a região da AWS.
aws-role-arn

string

Obrigatório. O nome de recurso da Amazon (ARN) do papel do IAM da AWS que o catálogo federado assume para acessar o AWS Glue Data Catalog.

SnowflakeCatalogInfo

Informações específicas do catálogo do Snowflake Horizon. O endpoint do catálogo REST do Iceberg tem o formato: https://<accountIdentifier>.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<warehouse>.

Representação JSON 
{
  "account-identifier": string,
  "warehouse": string,
  "snowflake-role": string
}
Campos
account-identifier

string

Obrigatório. Imutável. O identificador da conta no Snowflake. Por exemplo, para o URL de implantação do Snowflake https://myorg-myaccount.snowflakecomputing.com, o identificador da conta é myorg-myaccount.
warehouse

string

Obrigatório. Imutável. O nome do banco de dados no catálogo do Snowflake Horizon.
snowflake-role

string

Opcional. O nome da função do Snowflake usado para acessar o catálogo do Snowflake Horizon no fluxo de autenticação da federação de identidade da carga de trabalho (OIDC).

WorkdayCatalogInfo

Informações específicas do Workday Data Lake. O endpoint do catálogo REST do Iceberg tem o formato: https://<baseUrl>/datalake/api/catalog/v1/config?warehouse=workday.

Representação JSON 
{
  "base-url": string,
  "tenant": string
}
Campos
base-url

string

Obrigatório. Imutável. O URL de base da instância do Workday. Por exemplo, impl-services1.wd12.myworkday.com ou wd501.myworkday.com.
tenant

string

Obrigatório. Imutável. O nome do locatário do Workday.

RefreshOptions

Atualize a configuração.

Representação JSON 
{
  "refresh-schedule": {
    object (RefreshSchedule)
  },
  "refresh-scope": {
    object (RefreshScope)
  }
}
Campos
refresh-schedule

object (RefreshSchedule)

Opcional. A programação define se e quando a atualização de metadados deve ser programada.
refresh-scope

object (RefreshScope)

Opcional. Atualiza as configurações de escopo.

RefreshSchedule

A programação define se e quando a atualização de metadados deve ser programada.

Representação JSON 
{
  "refresh-interval": string
}
Campos
refresh-interval

string (Duration format)

Opcional. O intervalo para atualizar metadados do catálogo remoto. Se não estiver definido ou se o valor for <= 0, a atualização de metadados em segundo plano será desativada. Se esse campo for atualizado para um catálogo federado, a atualização anterior de metadados em segundo plano precisará ser concluída antes que o novo intervalo de atualização entre em vigor.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

RefreshScope

O escopo define um subconjunto de namespaces a serem atualizados.

Representação JSON 
{
  "namespace-filters": [
    string
  ]
}
Campos
namespace-filters[]

string

Opcional. Filtros para determinar quais namespaces estão incluídos no processo de atualização. - uma lista vazia significa incluir todos os namespaces. - "[namespaces]" significa incluir os namespaces especificados. ["ns1", "ns2"] : descobre apenas os namespaces "ns1" e "ns2".

RefreshStatus

Status da atualização de metadados em segundo plano do catálogo remoto.

Representação JSON 
{
  "start-time": string,
  "end-time": string,
  "status": {
    object (Status)
  }
}
Campos
start-time

string (Timestamp format)

Apenas saída. Quando a atualização do catálogo for iniciada, incluindo as atualizações em andamento.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
end-time

string (Timestamp format)

Apenas saída. Quando a atualização do catálogo terminar, desmarque para atualizações em andamento.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
status

object (Status)

Apenas saída. O status da última operação de atualização de metadados em segundo plano. Não definido para atualizações em andamento.

CrossCloudCacheOptions

Opções de configuração para armazenamento em cache entre nuvens de arquivos de dados e metadados.

Representação JSON 
{
  "enabled": boolean
}
Campos
enabled

boolean

Opcional. Especifica se o armazenamento em cache entre nuvens de arquivos de dados e metadados está ativado. Isso afeta apenas consultas pelo BigQuery.

Se esse valor for true, os dados e metadados de leitura serão armazenados em um cache, o que pode aumentar o desempenho e diminuir os custos de saída de rede para consultas entre nuvens.

Se esse valor for false, o armazenamento em cache entre nuvens será desativado.

Métodos

create

 Cria o catálogo REST do Iceberg.

delete

 Exclui o catálogo REST do Iceberg.

failover

 Faça failover do catálogo para uma nova região de réplica principal.

get

 Retorna as opções de configuração do catálogo REST do Iceberg.

list

 Lista os catálogos REST do Iceberg.

patch

 Atualize as opções de configuração do catálogo REST do Iceberg.