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

Ressource: IcebergCatalog

Informationen zum Iceberg-REST-Katalog.

JSON-Darstellung 
{
  "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)
  }
}
Felder
name

string

ID. Der Katalogname, projects/my-project/catalogs/my-catalog. Dieses Feld ist unveränderlich. Dieses Feld wird für „catalogs.create“ ignoriert.
credential-mode

enum (CredentialMode)

Optional. Der Anmeldedatenmodus für den Katalog.
biglake-service-account

string

Nur Ausgabe. Das Dienstkonto, das für die Bereitstellung von Anmeldedaten verwendet wird (nur Ausgabe). Kann leer sein, wenn die Bereitstellung von Anmeldedaten für den Katalog nie aktiviert wurde.

Bei föderierten Katalogen wird das Dienstkonto immer bereitgestellt und für den Zugriff auf den Remote-Katalog zum Aktualisieren von Hintergrundmetadaten verwendet. Wenn google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.IdentityMode auf IDENTITY_MODE_SERVICE_IDENTITY festgelegt ist, wird es auch für Abfragen verwendet.
biglake-service-account-id

string

Nur Ausgabe. Die eindeutige ID des Dienstkontos. Wird für Föderationsszenarien verwendet.
catalog-type

enum (CatalogType)

Erforderlich. Der Katalogtyp. Erforderlich für catalogs.create. Der Katalognamenstyp ist unveränderlich, mit Ausnahme der Konvertierung von CATALOG_TYPE_GCS_BUCKET zu CATALOG_TYPE_BIGLAKE.
default-location

string

Optional. Der Standardspeicherort für den Katalog, z.B. gs://my-bucket. Bei Google Cloud Storage-Bucket-Katalogen ist dies nur die Ausgabe.

Bei BigLake-Katalogen muss dieses Feld angegeben werden und auf einen Google Cloud Storage-Bucket oder einen Pfad in diesem Bucket verweisen. Dieser Pfad dient als Basisverzeichnis zum Erstellen des vollständigen Pfads zu den Daten- und Metadatenverzeichnissen einer Tabelle, wenn kein Speicherort auf Namespace- oder Tabellenebene angegeben ist. Der vollständige Pfad wird gebildet, indem die Namespace- und Tabellenkennungen an den standardmäßigen Standort angehängt werden.
storage-regions[]

string

Nur Ausgabe. Die GCP-Region(en) des Buckets des Standardspeicherorts, z.B. us-central1, nam4 oder us. Diese Spalte enthält einen Wert für alle Standorte, mit Ausnahme der Kataloge, für die benutzerdefinierte Dual-Region-Buckets konfiguriert sind. In diesem Fall enthält sie die beiden Regionen des Buckets. Die Region(en) dieses Felds sollten sich in der Gerichtsbarkeit des primären Standorts des Katalogs oder in der Nähe befinden.
create-time

string (Timestamp format)

Nur Ausgabe. Wann der Katalog erstellt wurde.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30"
update-time

string (Timestamp format)

Nur Ausgabe. Wann der Katalog zuletzt aktualisiert wurde.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30"
replicas[]

object (Replica)

Nur Ausgabe. Die Replikate für die Katalogmetadaten.
description

string

Optional. Eine vom Nutzer angegebene Beschreibung des Katalogs. Die Beschreibung muss ein UTF-8-String mit einer maximalen Länge von 1.024 Zeichen sein.
restricted-locations-config

object (RestrictedLocationsConfig)

Optional. Konfiguration eingeschränkter Standorte. Dieses Feld wird derzeit nur für BigLake-Kataloge verwendet.

Wenn dieses Feld nicht konfiguriert ist oder restrictedLocationsConfig.restricted_locations leer ist, sind alle zugänglichen Standorte zulässig. Wenn restrictedLocationsConfig.restricted_locations nicht leer ist, sind nur Standorte in defaultLocation und restrictedLocationsConfig.restricted_locations zulässig.
federated-catalog-options

object (FederatedCatalogOptions)

Optional. Konfigurationsoptionen für föderierte Kataloge.
cross-cloud-cache-options

object (CrossCloudCacheOptions)

Optional. Konfigurationsoptionen für das cloudübergreifende Caching von Daten- und Metadatendateien.
encryption-config

object (EncryptionConfig)

Optional. Benutzerdefinierte Verschlüsselungskonfiguration (z.B. Cloud KMS-Schlüssel).

CredentialMode

Der Anmeldedatenmodus, der für den Katalog verwendet wird.

Enums
CREDENTIAL_MODE_UNSPECIFIED Standardwert/nicht festgelegter Wert. Dieser Wert wird nicht verwendet.
CREDENTIAL_MODE_END_USER Standardmodus für Anmeldedaten von Endnutzern. Der authentifizierende Nutzer muss Zugriff auf die Katalogressourcen und die zugrunde liegenden Google Cloud Storage-Objekte haben.
CREDENTIAL_MODE_VENDED_CREDENTIALS

Modus für Bereitstellung von Anmeldedaten. Der authentifizierende Nutzer benötigt nur Zugriff auf die Katalogressourcen. Das System stellt dem Aufrufer eingeschränkte Anmeldedaten für den Zugriff auf die Google Cloud Storage-Objekte zur Verfügung. Für alle Tabellenvorgänge in diesem Modus muss der Header X-Iceberg-Access-Delegation auf vended-credentials festgelegt sein. Das System generiert ein Dienstkonto in google.cloud.biglake.v1main.IcebergCatalog.biglake_service_account, dem der Katalogadministrator Zugriff auf Google Cloud Storage-Objekte gewähren muss.

Weitere Informationen finden Sie unter https://docs.cloud.google.com/lakehouse/docs/credential-vending.

CatalogType

Bestimmt den Katalogtyp.

Enums
CATALOG_TYPE_UNSPECIFIED Standardwert/nicht festgelegter Wert. Dieser Wert wird nicht verwendet.
CATALOG_TYPE_GCS_BUCKET Der Katalogtyp des Google Cloud Storage-Bucket.
CATALOG_TYPE_BIGLAKE BigLake-Katalogtyp.
CATALOG_TYPE_FEDERATED Typ des föderierten Katalogs.

Replikat

Das Replikat des Katalogs.

JSON-Darstellung 
{
  "region": string,
  "state": enum (State)
}
Felder
region

string

Nur Ausgabe. Die Region des Replikats. Beispiel: „us-east1“
state

enum (State)

Nur Ausgabe. Der aktuelle Status des Replikats.

Bundesland

Wenn der Katalog in mehrere Regionen repliziert wird, beschreibt dieser Enum den aktuellen Status des Replikats.

Enums
STATE_UNKNOWN Standardwert/nicht festgelegter Wert. Dieser Wert wird nicht verwendet.
STATE_PRIMARY Das Replikat ist die beschreibbare primäre Instanz.
STATE_PRIMARY_IN_PROGRESS Das Replikat wurde vor Kurzem als primäres Replikat zugewiesen, aber noch nicht alle Namespaces sind beschreibbar.
STATE_SECONDARY Das Replikat ist ein schreibgeschütztes sekundäres Replikat.

RestrictedLocationsConfig

Konfiguration von Standortbeschränkungen.

JSON-Darstellung 
{
  "restricted-locations": [
    string
  ]
}
Felder
restricted-locations[]

string

Optional. Zusätzliche Google Cloud Storage-Buckets und ‑Standorte (z.B. gs://my-other-bucket/...), die für die Verwendung durch Ressourcen in einem Katalog zulässig sind. Dieses Feld wird derzeit nur für BigLake-Kataloge verwendet.

Wenn restrictedLocations leer ist und die uneingeschränkte Katalogerstellung aktiviert ist, sind alle zugänglichen Standorte zulässig. Andernfalls sind nur defaultLocation und Standorte in dieser Liste zulässig.

EncryptionConfig

Benutzerdefinierte Verschlüsselungskonfiguration (z.B. Cloud KMS-Schlüssel).

JSON-Darstellung 
{
  "kms-key-name": string
}
Felder
kms-key-name

string

Optional. Der Name des Cloud KMS-Schlüssels, der zum Verschlüsseln von aus dem Katalog abgerufenen Cache-Daten verwendet wird. Format: projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey}

FederatedCatalogOptions

Konfigurationsoptionen für einen föderierten Katalog.

JSON-Darstellung 
{
  "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
}
Felder
refresh-options

object (RefreshOptions)

Optional. Konfiguration aktualisieren
refresh-status

object (RefreshStatus)

Nur Ausgabe. Der Status der Hintergrundvorgänge zur Aktualisierung von Metadaten.
Informationen, die sich speziell auf den Remote-Iceberg-REST-Katalog beziehen. Im Folgenden finden Sie eine Liste von sich gegenseitig ausschließenden Feldern. In einer Antwort wird höchstens eines der Felder festgelegt:
unity-catalog-info

object (UnityCatalogInfo)

Optional. Informationen speziell zu Databricks Unity Catalog.
glue-catalog-info

object (GlueCatalogInfo)

Optional. Informationen speziell für AWS Glue Data Catalog
snowflake-catalog-info

object (SnowflakeCatalogInfo)

Optional. Informationen speziell zu Snowflake Horizon Catalog.
workday-catalog-info

object (WorkdayCatalogInfo)

Optional. Spezifische Informationen zu Workday Data Lake.
Ende der sich gegenseitig ausschließenden Felder.
secret-name

string

Optional. Der Name der Secret-Ressource in Secret Manager im Format projects/{projectId}/locations/{location}/secrets/{secret_id} oder projects/{projectId}/locations/{location}/secrets/{secret_id}/versions/{version_id}.

Die Projekt-ID muss mit dem Projekt des Katalogs und der Standort mit dem Standort des Katalogs übereinstimmen. Wenn die Version nicht angegeben ist, wird die aktuelle Version verwendet.

Dieses Feld wird nicht verwendet, wenn google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.UnityCatalogInfo.service_principal_application_id oder google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.SnowflakeCatalogInfo.snowflake_role festgelegt ist.
service-directory-name

string

Optional. Der Service Directory-Ressourcenname, der verwendet wird, um Transport Layer-Traffic mit dem Remote-Katalog (z.B. Datenfile-Zugriff in Speicher-Buckets) über eine private Netzwerkverbindung weiterzuleiten.

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

Dies wird von BigQuery-Abfragen verwendet, um private Endpunkte zum Abrufen von Datendateien (z.B. Iceberg-Daten in S3 oder Azure Data Lake Storage) über eine private Netzwerkverbindung wie Cross-Cloud Interconnect aufzulösen.

UnityCatalogInfo

Informationen speziell zu Databricks Unity Catalog. Der Iceberg-REST-Katalogendpunkt hat das Format https://<instanceName>/api/2.1/unity-catalog/iceberg-rest/v1/config?warehouse=<catalogName>.

JSON-Darstellung 
{
  "instance-name": string,
  "catalog-name": string,
  "service-principal-application-id": string
}
Felder
instance-name

string

Erforderlich. Nicht veränderbar. Der Instanzname des Databricks-Arbeitsbereichs. Lautet die URL des Databricks-Arbeitsbereichs beispielsweise https://1.1.gcp.databricks.com, so ist der Instanzname 1.1.gcp.databricks.com.
catalog-name

string

Erforderlich. Nicht veränderbar. Der Name des Katalogs in Databricks Unity Catalog.
service-principal-application-id

string

Optional. Die Anwendungs-ID des Databricks-Dienstprinzipals, der für den Zugriff auf Databricks Unity Catalog im OIDC-Authentifizierungsablauf verwendet wird.

GlueCatalogInfo

Informationen speziell für AWS Glue Data Catalog Der Iceberg-REST-Katalogendpunkt hat das Format https://glue.<awsRegion>.amazonaws.com/iceberg/v1/config?warehouse=<warehouse>.

JSON-Darstellung 
{
  "warehouse": string,
  "aws-region": string,
  "aws-role-arn": string
}
Felder
warehouse

string

Erforderlich. Nicht veränderbar. Der Warehouse-Standort in AWS Glue Data Catalog.

Verwenden Sie für den Katalog des Standardkontos die 12‑stellige AWS-Konto-ID (z. B. 111222333444). Verwenden Sie für einen Amazon S3-Tabellen-Bucket das Format <account_id>:s3tablescatalog/<table_bucket_name> (z. B. 111222333444:s3tablescatalog/my-table-bucket).
aws-region

string

Erforderlich. Nicht veränderbar. Die AWS-Region des AWS Glue Data Catalog, z. B. us-east-1. Die Region des föderierten Katalogs sollte sich zwecks optimaler Leistung am selben geografischen Standort und in derselben Gerichtsbarkeit wie die AWS-Region befinden.
aws-role-arn

string

Erforderlich. Der Amazon Resource Name (ARN) der AWS-IAM-Rolle, die der föderierte Katalog für den Zugriff auf AWS Glue Data Catalog übernimmt.

SnowflakeCatalogInfo

Informationen speziell zu Snowflake Horizon Catalog. Der Iceberg-REST-Katalogendpunkt hat das Format https://<accountIdentifier>.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<warehouse>.

JSON-Darstellung 
{
  "account-identifier": string,
  "warehouse": string,
  "snowflake-role": string
}
Felder
account-identifier

string

Erforderlich. Nicht veränderbar. Die Konto-ID in Snowflake. Lautet die URL der Snowflake-Bereitstellung beispielsweise https://myorg-myaccount.snowflakecomputing.com, so ist die Konto-ID myorg-myaccount.
warehouse

string

Erforderlich. Nicht veränderbar. Der Datenbankname in Snowflake Horizon Catalog.
snowflake-role

string

Optional. Der Name der Snowflake-Rolle, die für den Zugriff auf Snowflake Horizon Catalog im Authentifizierungsvorgang der Workload Identity-Föderation (OIDC) verwendet wird.

WorkdayCatalogInfo

Spezifische Informationen zu Workday Data Lake. Der Iceberg-REST-Katalogendpunkt hat das Format https://<baseUrl>/datalake/api/catalog/v1/config?warehouse=workday.

JSON-Darstellung 
{
  "base-url": string,
  "tenant": string
}
Felder
base-url

string

Erforderlich. Nicht veränderbar. Die Basis-URL der Workday-Instanz. Beispiel: impl-services1.wd12.myworkday.com oder wd501.myworkday.com.
tenant

string

Erforderlich. Nicht veränderbar. Der Name des Workday-Mandanten.

RefreshOptions

Konfiguration aktualisieren

JSON-Darstellung 
{
  "refresh-schedule": {
    object (RefreshSchedule)
  },
  "refresh-scope": {
    object (RefreshScope)
  }
}
Felder
refresh-schedule

object (RefreshSchedule)

Optional. Der Zeitplan definiert, ob und wann die Metadatenaktualisierung geplant werden soll.
refresh-scope

object (RefreshScope)

Optional. Bereichskonfigurationen aktualisieren.

RefreshSchedule

Der Zeitplan definiert, ob und wann die Metadatenaktualisierung geplant werden soll.

JSON-Darstellung 
{
  "refresh-interval": string
}
Felder
refresh-interval

string (Duration format)

Optional. Das Intervall für die Aktualisierung von Metadaten aus dem Remote-Katalog. Wenn der Wert nicht festgelegt ist oder kleiner oder gleich 0 ist, wird die Aktualisierung der Hintergrundmetadaten deaktiviert. Wenn dieses Feld für einen vorhandenen föderierten Katalog aktualisiert wird, muss die vorherige Aktualisierung der Hintergrundmetadaten abgeschlossen sein, bevor das neue Aktualisierungsintervall wirksam wird.

Die Dauer in Sekunden mit bis zu neun Nachkommastellen und am Ende mit „s“. Beispiel: "3.5s".

RefreshScope

Der Bereich definiert eine Teilmenge der Namespaces, die aktualisiert werden sollen.

JSON-Darstellung 
{
  "namespace-filters": [
    string
  ]
}
Felder
namespace-filters[]

string

Optional. Filter, mit denen festgelegt wird, welche Namespaces in den Aktualisierungsprozess einbezogen werden. – Eine leere Liste bedeutet, dass alle Namespaces berücksichtigt werden. – „[namespaces]“ bedeutet, dass die angegebenen Namespaces eingeschlossen werden. ['ns1', 'ns2'] : Nur die Namespaces „ns1“ und „ns2“ werden erkannt.

RefreshStatus

Status der Aktualisierung von Hintergrundmetadaten für den Remote-Katalog.

JSON-Darstellung 
{
  "start-time": string,
  "end-time": string,
  "status": {
    object (Status)
  }
}
Felder
start-time

string (Timestamp format)

Nur Ausgabe. Wenn die Katalogaktualisierung gestartet wurde, einschließlich laufender Aktualisierungen.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30"
end-time

string (Timestamp format)

Nur Ausgabe. Wenn die Katalogaktualisierung abgeschlossen ist, heben Sie die Einstellung für laufende Aktualisierungen auf.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30"
status

object (Status)

Nur Ausgabe. Der Status des letzten Vorgangs zum Aktualisieren von Metadaten im Hintergrund. Bei laufenden Aktualisierungen ist der Wert nicht festgelegt.

CrossCloudCacheOptions

Konfigurationsoptionen für das cloudübergreifende Caching von Daten- und Metadatendateien.

JSON-Darstellung 
{
  "enabled": boolean
}
Felder
enabled

boolean

Optional. Gibt an, ob das cloudübergreifende Caching von Daten- und Metadatendateien aktiviert ist. Dies betrifft nur Abfragen über BigQuery.

Wenn dieser Wert true ist, werden Lese- und Metadaten in einem Cache gespeichert. Das kann die Leistung steigern und die Kosten für ausgehenden Netzwerktraffic bei cloudübergreifenden Abfragen senken.

Wenn dieser Wert false ist, ist das cloudübergreifende Caching deaktiviert.

Methoden

create

 Erstellt den Iceberg-REST-Katalog.

delete

 Löscht den Iceberg-REST-Katalog.

failover

 Führen Sie ein Failover des Katalogs in eine neue primäre Replikatregion durch.

get

 Gibt die Konfigurationsoptionen für den Iceberg-REST-Katalog zurück.

list

 Listet die Iceberg-REST-Kataloge auf.

patch

 Aktualisieren Sie die Konfigurationsoptionen für den Iceberg-REST-Katalog.