Diese Seite wurde von der Cloud Translation API übersetzt.

BigLake Metastore mit dem Iceberg REST-Katalog verwenden

Der verwaltete Apache Iceberg REST-Katalog in BigLake Metastore sorgt für Interoperabilität zwischen allen Ihren Abfrage-Engines, da er eine einzige Quelle der Wahrheit für alle Ihre Iceberg-Daten bietet. Damit können Abfrage-Engines wie Apache Spark Iceberg-Tabellen auf konsistente Weise erkennen, Metadaten daraus lesen und sie verwalten.

Die Iceberg-Tabellen, die Sie mit dem Iceberg REST-Katalog verwenden, werden als BigLake-Tabellen für Apache Iceberg (Vorabversion) bezeichnet. Das sind Iceberg-Tabellen, die Sie mit Open-Source-Engines erstellen und in Cloud Storage speichern. Sie können von Open-Source-Engines oder BigQuery gelesen werden. Schreibvorgänge werden nur von Open-Source-Engines unterstützt. In diesem Dokument werden diese Tabellen als BigLake-Iceberg-Tabellen bezeichnet.

Hinweise

Verify that billing is enabled for your Google Cloud project.
So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist
Enable the BigLake API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API
Optional: Bitten Sie einen Administrator, die Bereitstellung von Anmeldedaten zum ersten Mal einzurichten.
Optional: Funktionsweise von BigLake Metastore und Gründe für die Verwendung.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zur Verwendung des Iceberg-REST-Katalogs im BigLake-Metastore benötigen:

Administrativen Aufgaben ausführen, z. B. den Nutzerzugriff auf den Katalog, den Speicherzugriff und den Anmeldedatenmodus des Katalogs verwalten:
- BigLake-Administrator (roles/biglake.admin) für das Projekt
- Storage-Administrator (roles/storage.admin) für den Cloud Storage-Bucket
Tabellendaten im Credential Vending-Modus lesen: BigLake-Betrachter (roles/biglake.viewer) für das Projekt
Tabellendaten im Credential Vending-Modus schreiben: BigLake-Editor (roles/biglake.editor) für das Projekt
Katalogressourcen und Tabellendaten im Modus ohne Bereitstellung von Anmeldedaten lesen:
- BigLake-Betrachter (roles/biglake.viewer) für das Projekt
- Storage-Objekt-Betrachter (roles/storage.objectViewer) für den Cloud Storage-Bucket
Katalogressourcen verwalten und Tabellendaten im Modus ohne Bereitstellung von Anmeldedaten schreiben:
- BigLake Editor (roles/biglake.editor) für das Projekt
- Storage Object User (roles/storage.objectUser) für den Cloud Storage-Bucket

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Modus für Bereitstellung von Anmeldedaten einrichten

Der Modus für die Bereitstellung von Anmeldedaten ist ein Mechanismus zur Delegierung des Speicherzugriffs, mit dem BigLake Metastore-Administratoren Berechtigungen direkt für BigLake Metastore-Ressourcen steuern können. Dadurch ist es nicht erforderlich, dass Katalog-Nutzer direkten Zugriff auf Cloud Storage-Buckets haben. Damit können BigLake-Administratoren Nutzern Berechtigungen für bestimmte Datendateien erteilen.

Ein Katalogadministrator aktiviert die Bereitstellung von Anmeldedaten für den Iceberg REST-Katalogclient.

Als Katalognutzer können Sie dann den Iceberg REST-Katalog anweisen, herabgestufte Speicheranmeldedaten zurückzugeben, indem Sie die Zugriffsdelegierung angeben, die Teil der Iceberg REST Catalog API-Spezifikation ist. Weitere Informationen finden Sie unter Abfrage-Engine mit dem Iceberg-REST-Katalog konfigurieren.

So initialisieren Sie den Katalog und aktivieren den Modus für die Bereitstellung von Anmeldedaten:

Initialisieren Sie den Katalog mit dem folgenden Befehl:

curl -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1beta/restcatalog/v1/config?warehouse=gs://CLOUD_STORAGE_BUCKET_NAME

Ersetzen Sie Folgendes:

PROJECT_ID: die ID Ihres Google Cloud Projekts.
CLOUD_STORAGE_BUCKET_NAME: Der Name des Cloud Storage-Bucket, in dem die Iceberg-Tabelle gespeichert ist.

Die Ausgabe des curl-Befehls sieht in etwa so aus: Der Wert für das Katalogpräfix befindet sich in der Antwort im Feld overrides.prefix:

{
  "overrides": {
    "catalog_credential_mode": "CREDENTIAL_MODE_END_USER",
    "prefix": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME"
  },
  "endpoints": [
    "GET /v1/{prefix}/namespaces",
    "POST /v1/{prefix}/namespaces",
    "GET /v1/{prefix}/namespaces/{namespace}",
    "HEAD /v1/{prefix}/namespaces/{namespace}",
    "DELETE /v1/{prefix}/namespaces/{namespace}",
    "POST /v1/{prefix}/namespaces/{namespace}/properties",
    "GET /v1/{prefix}/namespaces/{namespace}/tables",
    "POST /v1/{prefix}/namespaces/{namespace}/tables",
    "GET /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "POST /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}"
  ]
}

Aktivieren Sie den Modus für die Bereitstellung von Anmeldedaten und extrahieren Sie das Dienstkonto, dem Sie Berechtigungen erteilen möchten, mit dem folgenden Befehl:

curl -X PATCH -H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1beta/restcatalog/extensions/PREFIX?update_mask=credential_mode -d '{"credential_mode":"CREDENTIAL_MODE_VENDED_CREDENTIALS"}'

Ersetzen Sie PREFIX durch das Feld prefix aus der Ausgabe des vorherigen Befehls.

Die Ausgabe des Befehls curl enthält das Dienstkonto, das in etwa so aussieht:

{
  "name": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME",
  "credential_mode": "CREDENTIAL_MODE_VENDED_CREDENTIALS",
  "biglake-service-account": "BIGLAKE_SERVICE_ACCOUNT"
}

Damit das BigLake-Dienstkonto, das Sie im vorherigen Schritt extrahiert haben, die erforderlichen Berechtigungen zur Verwendung des Anmeldedaten-Vending-Modus hat, bitten Sie Ihren Administrator, ihm die Rolle „Storage-Objekt-Nutzer“ (roles/storage.objectUser) für den Speicher-Bucket zuzuweisen.

Wichtig :Sie müssen diese Rolle dem BigLake-Dienstkonto zuweisen, das Sie im vorherigen Schritt extrahiert haben, nicht Ihrem Nutzerkonto. Wenn die Rolle nicht dem richtigen Hauptkonto zugewiesen wird, kann das zu Berechtigungsfehlern führen.

Beschränkungen

Für den Iceberg-REST-Katalog gelten die folgenden Einschränkungen:

Multiregionale Buckets, biregionale Buckets und Buckets mit benutzerdefinierter Regionsplatzierung werden nicht unterstützt.
Wenn Sie den Modus für die Bereitstellung von Anmeldedaten verwenden, müssen Sie das Attribut io-impl auf org.apache.iceberg.gcp.gcs.GCSFileIO festlegen. Der Standardwert org.apache.iceberg.hadoop.HadoopFileIO wird nicht unterstützt.

Abfrage-Engine mit dem Iceberg REST-Katalog konfigurieren

Iceberg 1.10 oder höher

Iceberg 1.10 und nachfolgende Releases bieten integrierte Unterstützung für Google-Autorisierungsabläufe in GoogleAuthManager. Dataproc Spark unterstützt GoogleAuthManager auch in den folgenden Releases:

Dataproc in Compute Engine 2.2-Laufzeitversionen 2.2.65 und höher
Serverless for Apache Spark 2.2-Images 2.2.60 und höher
Dataproc in Compute Engine-Laufzeitversionen 2.3.11 und höher
Serverless for Apache Spark 2.3-Images 2.3.10 und höher

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1beta/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ersetzen Sie Folgendes:

CATALOG_NAME: Ein Name für Ihren Iceberg-REST-Katalog.
APP_NAME: Ein Name für Ihre Spark-Sitzung.
CLOUD_STORAGE_BUCKET_NAME: Der Name des Cloud Storage-Bucket, in dem die BigLake Iceberg-Tabellen gespeichert sind.
PROJECT_ID: Das Projekt, das für die Verwendung des Iceberg REST-Katalogs abgerechnet wird. Dies kann sich vom Projekt unterscheiden, dem der Cloud Storage-Bucket gehört. Weitere Informationen zur Projektkonfiguration bei Verwendung einer REST API finden Sie unter Systemparameter.

Im vorherigen Beispiel wird keine Bereitstellung von Anmeldedaten verwendet. Wenn Sie die Bereitstellung von Anmeldedaten verwenden möchten, müssen Sie den X-Iceberg-Access-Delegation-Header mit dem Wert vended-credentials zu Iceberg REST-Kataloganfragen hinzufügen. Fügen Sie dazu die folgende Zeile zum SparkSession-Builder hinzu: .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials').

Beispiel mit Bereitstellung von Anmeldedaten

Im folgenden Beispiel wird die Abfrage-Engine mit der Bereitstellung von Anmeldedaten konfiguriert:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1beta/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Weitere Informationen finden Sie in der Iceberg-Dokumentation im Abschnitt Header in RESTCatalog.

Frühere Iceberg-Releases

Für Iceberg-Releases vor Version 1.10, die nicht in Dataproc-Images enthalten sind, können Sie die standardmäßige OAuth-Authentifizierung konfigurieren, indem Sie eine Sitzung mit Folgendem konfigurieren:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1beta/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ersetzen Sie Folgendes:

CATALOG_NAME: Ein Name für Ihren Iceberg-REST-Katalog.
APP_NAME: Ein Name für Ihre Spark-Sitzung.
CLOUD_STORAGE_BUCKET_NAME: Der Name des Cloud Storage-Bucket, in dem die BigLake Iceberg-Tabellen gespeichert sind.
PROJECT_ID: Das Projekt, das für die Verwendung des Iceberg REST-Katalogs abgerechnet wird. Dies kann sich vom Projekt unterscheiden, dem der Cloud Storage-Bucket gehört. Weitere Informationen zur Projektkonfiguration bei Verwendung einer REST API finden Sie unter Systemparameter.
TOKEN: Ihr Authentifizierungstoken, das eine Stunde lang gültig ist, z. B. ein mit gcloud auth application-default print-access-token generiertes Token.

Beispiel mit Bereitstellung von Anmeldedaten

Im folgenden Beispiel wird die Abfrage-Engine mit der Bereitstellung von Anmeldedaten konfiguriert:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1beta/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Weitere Informationen finden Sie in der Iceberg-Dokumentation im Abschnitt Header in RESTCatalog.

Namespace erstellen

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME;")

spark.sql("USE NAMESPACE_NAME;")

Ersetzen Sie NAMESPACE_NAME durch einen Namen für den Namespace.

Tabelle erstellen

spark.sql("CREATE TABLE TABLE_NAME (id int, data string) USING ICEBERG;")

spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Ersetzen Sie Folgendes:

NAMESPACE_NAME ist der Name Ihres Namespace
TABLE_NAME: Ein Name für Ihre Tabelle

Tabellen auflisten

spark.sql("SHOW TABLES").show()

Daten in die Tabelle einfügen

Im folgenden Beispiel werden Beispieldaten in die Tabelle eingefügt:

spark.sql("INSERT INTO TABLE_NAME VALUES (1, \"first row\"), (2, \"second row\"), (3, \"third row\");")

Tabelle abfragen

Im folgenden Beispiel werden alle Daten aus der Tabelle ausgewählt:

spark.sql("SELECT * FROM TABLE_NAME;").show()

Im folgenden Beispiel wird dieselbe Tabelle aus BigQuery abgefragt:

SELECT * FROM `CLOUD_STORAGE_BUCKET_NAME>NAMESPACE_NAME.TABLE_NAME`;

Ersetzen Sie CLOUD_STORAGE_BUCKET_NAME durch den Namen des Cloud Storage-Bucket für Ihren Iceberg-REST-Katalog. Wenn Ihr URI beispielsweise gs://iceberg_bucket lautet, verwenden Sie iceberg_bucket.

Tabellenschema ändern

Im folgenden Beispiel wird der Tabelle eine Spalte hinzugefügt:

spark.sql("ALTER TABLE TABLE_NAME ADD COLUMNS ( desc string);")
spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Tabelle löschen

Im folgenden Beispiel wird die Tabelle aus dem angegebenen Namespace gelöscht:

spark.sql("DROP TABLE TABLE_NAME;")

Preise

Preisdetails finden Sie unter BigLake-Preise.

BigLake Metastore mit dem Iceberg REST-Katalog verwenden

Hinweise

Erforderliche Rollen

Modus für Bereitstellung von Anmeldedaten einrichten

Beschränkungen

Abfrage-Engine mit dem Iceberg REST-Katalog konfigurieren

Iceberg 1.10 oder höher

Beispiel mit Bereitstellung von Anmeldedaten

Frühere Iceberg-Releases

Beispiel mit Bereitstellung von Anmeldedaten

Namespace erstellen

Tabelle erstellen

Tabellen auflisten

Daten in die Tabelle einfügen

Tabelle abfragen

Tabellenschema ändern

Tabelle löschen

Preise

Nächste Schritte