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

Recurso: IcebergCatalog

Es la información del catálogo de REST de Iceberg.

Representación 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

Es el identificador. Nombre del catálogo, projects/my-project/catalogs/my-catalog. Este campo es inmutable. Este campo se ignora para catalogs.create.
credential-mode

enum (CredentialMode)

Es opcional. Es el modo de credenciales del catálogo.
biglake-service-account

string

Solo salida. Es la cuenta de servicio que se usa para la venta de credenciales (solo salida). Puede estar vacío si nunca se habilitó la venta de credenciales para el catálogo.

En el caso de los catálogos federados, la cuenta de servicio siempre se aprovisionará y se usará para acceder al catálogo remoto para la actualización de metadatos en segundo plano. Si google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.IdentityMode se establece en IDENTITY_MODE_SERVICE_IDENTITY, también se usará para las búsquedas.
biglake-service-account-id

string

Solo salida. Es el ID único de la cuenta de servicio. Se usa para situaciones de federación.
catalog-type

enum (CatalogType)

Obligatorio. Es el tipo de catálogo. Se requiere para catalogs.create. El tipo de catálogo es inmutable, excepto en el caso de la conversión de CATALOG_TYPE_GCS_BUCKET a CATALOG_TYPE_BIGLAKE.
default-location

string

Es opcional. Ubicación de almacenamiento predeterminada del catálogo, p.ej., gs://my-bucket. En el caso de los catálogos de buckets de Google Cloud Storage, este campo es solo de salida.

En el caso de los catálogos de BigLake, se debe proporcionar este campo y apuntar a un bucket de Google Cloud Storage o a una ruta de acceso dentro de ese bucket. Esta ruta sirve como directorio base para construir la ruta completa a los directorios de datos y metadatos de una tabla cuando no se especifica una ubicación a nivel del espacio de nombres o de la tabla. La ruta completa se forma agregando los identificadores de espacio de nombres y tabla a la ubicación predeterminada.
storage-regions[]

string

Solo salida. Regiones de GCP del bucket de la ubicación predeterminada, p.ej., us-central1, nam4 o us. Este campo contendrá un valor para todas las ubicaciones, excepto para los catálogos configurados para usar buckets birregionales personalizados, en cuyo caso contendrá las dos regiones del bucket. Las regiones de este campo deben estar en la jurisdicción de la ubicación principal del catálogo o cerca de ella.
create-time

string (Timestamp format)

Solo salida. Cuándo se creó el catálogo.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
update-time

string (Timestamp format)

Solo salida. Cuándo se actualizó el catálogo por última vez.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
replicas[]

object (Replica)

Solo salida. Son las réplicas de los metadatos del catálogo.
description

string

Es opcional. Es una descripción del catálogo proporcionada por el usuario. La descripción debe ser una cadena UTF-8 con una longitud máxima de 1,024 caracteres.
restricted-locations-config

object (RestrictedLocationsConfig)

Es opcional. Es la configuración de ubicaciones restringidas. Actualmente, este campo solo se usa para los catálogos de BigLake.

Si este campo no está establecido o si restrictedLocationsConfig.restricted_locations está vacío, se permitirán todas las ubicaciones accesibles. Si restrictedLocationsConfig.restricted_locations no está vacío, solo se permiten las ubicaciones en defaultLocation y restrictedLocationsConfig.restricted_locations.
federated-catalog-options

object (FederatedCatalogOptions)

Es opcional. Son las opciones de configuración para los catálogos federados.
cross-cloud-cache-options

object (CrossCloudCacheOptions)

Es opcional. Son opciones de configuración para el almacenamiento en caché multinube de archivos de datos y metadatos.
encryption-config

object (EncryptionConfig)

Es opcional. Configuración de encriptación personalizada (p. ej., claves de Cloud KMS)

CredentialMode

Es el modo de credenciales que se usa para el catálogo.

Enums
CREDENTIAL_MODE_UNSPECIFIED Valor predeterminado o no establecido. Este valor no se usa.
CREDENTIAL_MODE_END_USER Es el modo predeterminado de credenciales del usuario final. El usuario que se autentica debe tener acceso a los recursos del catálogo y a los objetos subyacentes de Google Cloud Storage.
CREDENTIAL_MODE_VENDED_CREDENTIALS

Es el modo de venta de credenciales. El usuario que se autentica solo necesita acceso a los recursos del catálogo, y el sistema proporcionará al llamador credenciales con alcance reducido para acceder a los objetos de Google Cloud Storage. Todas las operaciones de la tabla en este modo requieren que el encabezado X-Iceberg-Access-Delegation se establezca como vended-credentials. El sistema generará una cuenta de servicio en google.cloud.biglake.v1main.IcebergCatalog.biglake_service_account a la que el administrador del catálogo debe otorgar acceso al objeto de Google Cloud Storage.

Consulta https://docs.cloud.google.com/lakehouse/docs/credential-vending para obtener más detalles.

CatalogType

Determina el tipo de catálogo.

Enums
CATALOG_TYPE_UNSPECIFIED Valor predeterminado o no establecido. Este valor no se usa.
CATALOG_TYPE_GCS_BUCKET Es el tipo de catálogo del bucket de Google Cloud Storage.
CATALOG_TYPE_BIGLAKE Es el tipo de catálogo de BigLake.
CATALOG_TYPE_FEDERATED Tipo de catálogo federado.

Réplica

Es la réplica del catálogo.

Representación JSON 
{
  "region": string,
  "state": enum (State)
}
Campos
region

string

Solo salida. Es la región de la réplica. Por ejemplo, "us-east1".
state

enum (State)

Solo salida. Es el estado actual de la réplica.

Estado

Si el catálogo se replica en varias regiones, este enum describe el estado actual de la réplica.

Enums
STATE_UNKNOWN Valor predeterminado o no establecido. Este valor no se usa.
STATE_PRIMARY La réplica es la instancia principal que admite escritura.
STATE_PRIMARY_IN_PROGRESS La réplica se asignó recientemente como principal, pero aún no se pueden escribir todos los espacios de nombres.
STATE_SECONDARY La réplica es una réplica secundaria de solo lectura.

RestrictedLocationsConfig

Es la configuración de las restricciones de ubicación.

Representación JSON 
{
  "restricted-locations": [
    string
  ]
}
Campos
restricted-locations[]

string

Es opcional. Son los buckets y las ubicaciones adicionales de Google Cloud Storage (p.ej., gs://my-other-bucket/...) que se permiten para el uso de los recursos dentro de un catálogo. Actualmente, este campo solo se usa para los catálogos de BigLake.

Si restrictedLocations está vacío y se habilita la creación de catálogos sin restricciones, se permitirán todas las ubicaciones accesibles. De lo contrario, solo se permiten defaultLocation y las ubicaciones de esta lista.

EncryptionConfig

Configuración de encriptación personalizada (p. ej., claves de Cloud KMS)

Representación JSON 
{
  "kms-key-name": string
}
Campos
kms-key-name

string

Es opcional. Es el nombre de la clave de Cloud KMS que se usa para encriptar los datos almacenados en caché que se recuperan del catálogo. Formato: projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey}

FederatedCatalogOptions

Son las opciones de configuración de un catálogo federado.

Representación 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)

Es opcional. Actualiza la configuración.
refresh-status

object (RefreshStatus)

Solo salida. Es el estado de las operaciones de actualización de metadatos en segundo plano.
Es información específica del catálogo de REST de Iceberg remoto. La siguiente es una lista de campos mutuamente excluyentes. Como máximo, se establecerá uno de los campos en una respuesta:
unity-catalog-info

object (UnityCatalogInfo)

Es opcional. Es información específica de Databricks Unity Catalog.
glue-catalog-info

object (GlueCatalogInfo)

Es opcional. Es información específica de AWS Glue Data Catalog.
snowflake-catalog-info

object (SnowflakeCatalogInfo)

Es opcional. Es información específica del catálogo de Snowflake Horizon.
workday-catalog-info

object (WorkdayCatalogInfo)

Es opcional. Es información específica de Workday Data Lake.
Fin de los campos mutuamente excluyentes.
secret-name

string

Es opcional. Nombre del recurso secreto en Secret Manager, en el formato projects/{projectId}/locations/{location}/secrets/{secret_id} o projects/{projectId}/locations/{location}/secrets/{secret_id}/versions/{version_id}.

El ID del proyecto debe coincidir con el del catálogo, y la ubicación debe coincidir con la del catálogo. Si no se especifica la versión, se usará la más reciente.

Este campo no se usa cuando se configuran google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.UnityCatalogInfo.service_principal_application_id o google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.SnowflakeCatalogInfo.snowflake_role.
service-directory-name

string

Es opcional. Es el nombre del recurso de Service Directory que se usa para enrutar el tráfico de la capa de transporte con el catálogo remoto (p.ej., acceso a archivos de datos en buckets de almacenamiento) a través de una conexión de red privada.

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

Las consultas de BigQuery usan este parámetro para resolver los extremos privados y recuperar archivos de datos (p.ej., datos de Iceberg en S3 o Azure Data Lake Storage) a través de una conexión de red privada, como Cross‑Cloud Interconnect.

UnityCatalogInfo

Es información específica de Databricks Unity Catalog. El extremo del catálogo de REST de Iceberg tiene el formato https://<instanceName>/api/2.1/unity-catalog/iceberg-rest/v1/config?warehouse=<catalogName>.

Representación JSON 
{
  "instance-name": string,
  "catalog-name": string,
  "service-principal-application-id": string
}
Campos
instance-name

string

Obligatorio. Inmutable. Es el nombre de la instancia del espacio de trabajo de Databricks. Por ejemplo, para la URL del espacio de trabajo de Databricks https://1.1.gcp.databricks.com, el nombre de la instancia es 1.1.gcp.databricks.com.
catalog-name

string

Obligatorio. Inmutable. Nombre del catálogo en Databricks Unity Catalog.
service-principal-application-id

string

Es opcional. ID de aplicación de la entidad de servicio de Databricks que se usa para acceder a Databricks Unity Catalog en el flujo de autenticación de OIDC.

GlueCatalogInfo

Es información específica de AWS Glue Data Catalog. El extremo del catálogo de REST de Iceberg tiene el formato https://glue.<awsRegion>.amazonaws.com/iceberg/v1/config?warehouse=<warehouse>.

Representación JSON 
{
  "warehouse": string,
  "aws-region": string,
  "aws-role-arn": string
}
Campos
warehouse

string

Obligatorio. Inmutable. Ubicación del almacén en AWS Glue Data Catalog.

Para el catálogo de cuentas predeterminado, usa el ID de cuenta de AWS de 12 dígitos (por ejemplo, 111222333444). Para un bucket de tabla de Amazon S3, usa el formato <account_id>:s3tablescatalog/<table_bucket_name> (por ejemplo, 111222333444:s3tablescatalog/my-table-bucket).
aws-region

string

Obligatorio. Inmutable. Región de AWS del Data Catalog de AWS Glue (por ejemplo, us-east-1). La región del catálogo federado debe estar en la misma ubicación geográfica y jurisdicción que la región de AWS para obtener el mejor rendimiento.
aws-role-arn

string

Obligatorio. Es el nombre de recurso de Amazon (ARN) del rol de IAM de AWS que asume el catálogo federado para acceder al AWS Glue Data Catalog.

SnowflakeCatalogInfo

Es información específica del catálogo de Snowflake Horizon. El extremo del catálogo de REST de Iceberg tiene el formato https://<accountIdentifier>.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<warehouse>.

Representación JSON 
{
  "account-identifier": string,
  "warehouse": string,
  "snowflake-role": string
}
Campos
account-identifier

string

Obligatorio. Inmutable. Es el identificador de la cuenta en Snowflake. Por ejemplo, para la URL de implementación de Snowflake https://myorg-myaccount.snowflakecomputing.com, el identificador de cuenta es myorg-myaccount.
warehouse

string

Obligatorio. Inmutable. Nombre de la base de datos en el catálogo de Snowflake Horizon.
snowflake-role

string

Es opcional. Nombre del rol de Snowflake que se usa para acceder al catálogo de Snowflake Horizon en el flujo de autenticación de la federación de identidades para cargas de trabajo (OIDC).

WorkdayCatalogInfo

Es información específica de Workday Data Lake. El extremo del catálogo de REST de Iceberg tiene el formato https://<baseUrl>/datalake/api/catalog/v1/config?warehouse=workday.

Representación JSON 
{
  "base-url": string,
  "tenant": string
}
Campos
base-url

string

Obligatorio. Inmutable. Es la URL base de la instancia de Workday. Por ejemplo, impl-services1.wd12.myworkday.com o wd501.myworkday.com.
tenant

string

Obligatorio. Inmutable. Es el nombre del usuario de Workday.

RefreshOptions

Actualiza la configuración.

Representación JSON 
{
  "refresh-schedule": {
    object (RefreshSchedule)
  },
  "refresh-scope": {
    object (RefreshScope)
  }
}
Campos
refresh-schedule

object (RefreshSchedule)

Es opcional. El programa define si se debe programar la actualización de metadatos y cuándo.
refresh-scope

object (RefreshScope)

Es opcional. Actualiza la configuración del alcance.

RefreshSchedule

El programa define si se debe programar la actualización de metadatos y cuándo.

Representación JSON 
{
  "refresh-interval": string
}
Campos
refresh-interval

string (Duration format)

Es opcional. Es el intervalo para actualizar los metadatos del catálogo remoto. Si no se configura o si el valor es menor o igual a 0, se inhabilitará la actualización de metadatos en segundo plano. Si se actualiza este campo para un catálogo federado existente, la actualización anterior de metadatos en segundo plano debe completarse antes de que surta efecto el nuevo intervalo de actualización.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".

RefreshScope

El alcance define un subconjunto de espacios de nombres que se actualizarán.

Representación JSON 
{
  "namespace-filters": [
    string
  ]
}
Campos
namespace-filters[]

string

Es opcional. Son los filtros para determinar qué espacios de nombres se incluyen en el proceso de actualización. - Una lista vacía significa que se incluyen todos los espacios de nombres. - "[namespaces]" significa que se incluyen los espacios de nombres especificados. ["ns1", "ns2"] : Descubre solo los espacios de nombres "ns1" y "ns2".

RefreshStatus

Es el estado de la actualización de metadatos en segundo plano del catálogo remoto.

Representación JSON 
{
  "start-time": string,
  "end-time": string,
  "status": {
    object (Status)
  }
}
Campos
start-time

string (Timestamp format)

Solo salida. Fecha y hora en que se inició la actualización del catálogo, incluidas las actualizaciones en curso.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
end-time

string (Timestamp format)

Solo salida. Cuando finaliza la actualización del catálogo, se anula la configuración para las actualizaciones en curso.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
status

object (Status)

Solo salida. Es el estado de la última operación de actualización de metadatos en segundo plano. No se establece para las actualizaciones en curso.

CrossCloudCacheOptions

Son opciones de configuración para el almacenamiento en caché multinube de archivos de datos y metadatos.

Representación JSON 
{
  "enabled": boolean
}
Campos
enabled

boolean

Es opcional. Especifica si está habilitado el almacenamiento en caché multinube de archivos de datos y metadatos. Esto solo afecta las consultas a través de BigQuery.

Si este valor es true, los datos de lectura y los metadatos se almacenan en una caché, lo que puede aumentar el rendimiento y reducir los costos de salida de red para las consultas multinube.

Si este valor es false, se inhabilita el almacenamiento en caché multinube.

Métodos

create

 Crea el catálogo de REST de Iceberg.

delete

 Borra el catálogo de REST de Iceberg.

failover

 Conmuta por error el catálogo a una nueva región de réplica principal.

get

 Devuelve las opciones de configuración del catálogo de REST de Iceberg.

list

 Enumera los catálogos de REST de Iceberg.

patch

 Actualiza las opciones de configuración del catálogo de REST de Iceberg.