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. Este 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 de 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, esse campo é 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 pela anexação dos identificadores de namespace e tabela ao local padrão.

storage-regions[]

string

Apenas saída. As regiões do Google Cloud 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. Nesse caso, ele vai conter as duas regiões do bucket. As regiões desse campo precisam estar na jurisdição ou próximas ao 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 no máximo 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 esse 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, somente os 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 que está se autenticando 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 autor da chamada 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, e o administrador do catálogo precisa conceder a ela 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 de buckets do Google Cloud Storage.
CATALOG_TYPE_BIGLAKE Tipo de catálogo do BigLake.
CATALOG_TYPE_FEDERATED Tipo de catálogo federado.
CATALOG_TYPE_ALLOYDB_AGENT_MODE Catálogo para consultar tabelas do AlloyDB no modo agente.

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 tipo enumerado 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 principal gravável.
STATE_PRIMARY_IN_PROGRESS A réplica foi atribuída recentemente como primária, mas nem todos os namespaces são graváveis ainda.
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 de catálogo irrestrita estiver ativada, todos os locais acessíveis serão permitidos. Caso contrário, somente defaultLocation e os locais nesta lista serã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 em cache buscados no 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
{
  "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)
  }
}
Campos
identity-mode

enum (IdentityMode)

Opcional. O modo de identidade do catálogo federado.

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.

Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
identity-federation-organization-service-account

object (IdentityFederationOrganizationServiceAccount)

Apenas saída. A conta de serviço no nível da organização usada para federação de identidade.

Fim dos campos mutuamente exclusivos.
Informações específicas do catálogo REST remoto do Iceberg. 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 do secret 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 a versão não for especificada, a versão mais recente será usada.

Este campo não é usado quando google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.UnityCatalogInfo.service_principal_application_id, google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.SnowflakeCatalogInfo.snowflake_role ou google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.WorkdayCatalogInfo.api_client_client_id está definido.

service-directory-name

string

Opcional. O nome do recurso do Diretório de Serviços 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 particular.

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

Ele é usado por consultas do BigQuery para resolver endpoints particulares ao 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.

metadata-service-directory-name

string

Opcional. O nome do recurso do Diretório de Serviços usado para rotear o tráfego da camada de metadados com o catálogo remoto por uma conexão de rede particular.

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

Usado para recuperar metadados de catálogo (como configurações, namespaces e tabelas do Iceberg) em uma conexão de rede particular, como o Interconexão entre nuvens. Também é usado para buscar tokens OAuth quando oauth2ServerUrl não está definido. Se esse campo não for definido, as solicitações serão enviadas pela Internet pública.

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

object (UserIdentityFederationOidcClaims)

Apenas saída. Descontinuado: use google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.user_identity_federation_oidc.

As declarações do OIDC emitidas no token de ID para a federação de identidade do usuário.

user-identity-federation-oidc

object (UserIdentityFederationOidc)

Apenas saída. A configuração do OIDC para a federação de identidade do usuário.

IdentityFederationOrganizationServiceAccount

A conta de serviço no nível da organização usada para federação de identidade, somente saída. Pode estar vazio se a federação de identidade nunca for ativada para o catálogo.

Representação JSON
{
  "service-account": string,
  "service-account-unique-id": string
}
Campos
service-account

string

Apenas saída. E-mail da conta de serviço no nível da organização.

service-account-unique-id

string

Apenas saída. O ID exclusivo da conta de serviço no nível da organização.

UnityCatalogInfo

Informações específicas do Databricks Unity Catalog. O endpoint do catálogo REST do Iceberg tem o seguinte 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 da entidade 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 seguinte 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, na sigla em inglês) 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 seguinte 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.

O identificador da conta pode conter letras, dígitos e sublinhados, com segmentos separados por hifens (-) ou pontos (.). Isso é compatível com o formato de conta da organização (por exemplo, myorg-myaccount), o formato de localizador de conta legado (por exemplo, xy12345.us-east-1) e os formatos de conectividade privada (PrivateLink) (por exemplo, myorg-myaccount.privatelink ou xy12345.us-east-1.privatelink). Para mais informações, consulte https://docs.snowflake.com/en/user-guide/admin-account-identifier.

warehouse

string

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

snowflake-role

string

Opcional. O papel do Snowflake usado para definir o escopo do acesso ao 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 seguinte formato: https://<baseUrl>/datalake/api/catalog/v1/config?warehouse=workday.

Representação JSON
{
  "base-url": string,
  "tenant": string,
  "api-client-client-id": 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.

api-client-client-id

string

Opcional. O ID do cliente da API Workday usado para acessar o Workday Data Lake no fluxo de autenticação do OIDC.

IdentityMode

O modo de identidade usado pelo catálogo para consultas.

Tipos enumerados
IDENTITY_MODE_UNSPECIFIED Valor padrão/não definido. Esse valor é tratado da mesma forma que IDENTITY_MODE_SERVICE_IDENTITY.
IDENTITY_MODE_SERVICE_IDENTITY As consultas são executadas usando a conta de serviço em google.cloud.biglake.v1main.IcebergCatalog.biglake_service_account.
IDENTITY_MODE_USER_IDENTITY_FEDERATION

As consultas são executadas usando a identidade do usuário final e são propagadas para o catálogo remoto. A federação de identidade precisa ser configurada no catálogo remoto.

Consulte https://docs.cloud.google.com/lakehouse/docs/about-cross-cloud-data-access#identity-mode para mais detalhes.

UserIdentityFederationOidcClaims

Declarações do OIDC emitidas no token de ID quando IDENTITY_MODE_USER_IDENTITY_FEDERATION está ativado.

Esses valores identificam o provedor de identidade (emissor) e o destinatário pretendido (público-alvo) do token. Para ativar a federação de identidade do usuário, os usuários precisam configurar o catálogo remoto para confiar nesse emissor e esperar esse público-alvo.

Representação JSON
{
  "issuer-url": string,
  "audience": string
}
Campos
issuer-url

string

Apenas saída. O URL do emissor do provedor de identidade.

audience

string

Apenas saída. O público-alvo que esse catálogo espera no token.

UserIdentityFederationOidc

Configuração do OIDC usada quando IDENTITY_MODE_USER_IDENTITY_FEDERATION está ativado.

Para ativar a federação de identidade do usuário, os usuários precisam configurar o catálogo remoto para confiar em tokens com esses parâmetros.

Representação JSON
{
  "issuer-url": string,
  "audience": string,
  "jwks-url": string
}
Campos
issuer-url

string

Apenas saída. O URL do emissor do provedor de identidade.

audience

string

Apenas saída. O público-alvo que esse catálogo espera no token.

jwks-url

string

Apenas saída. O URL do conjunto de chaves Web JSON (JWKS) que disponibiliza as chaves públicas usadas para verificar o token. Definido apenas para catálogos federados do Snowflake Horizon, em que é usado como EXTERNAL_OAUTH_JWS_KEYS_URL na integração de segurança do Snowflake.

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. Atualize 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 os metadados do catálogo remoto. Se não for 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 dos 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 sã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 de 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 começou, incluindo as que estão 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, desative 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".

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 as consultas pelo BigQuery.

Se esse valor for true, os dados e metadados lidos 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 o 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.