Objekttabellen erstellen
In diesem Dokument wird beschrieben, wie Sie durch Erstellen einer Objekttabelle unstrukturierte Daten in Cloud Storage in BigQuery zugänglich machen.
Zum Erstellen einer Objekttabelle müssen Sie die folgenden Schritte ausführen:
- Erstellen Sie ein Dataset, das die Objekttabelle enthält.
- Erstellen Sie eine Verbindung, um Objektinformationen aus Cloud Storage zu lesen.
- Weisen Sie dem Dienstkonto, das der Verbindung zugeordnet ist, die Rolle „Storage-Objekt-Betrachter“ (
roles/storage.objectViewer) zu. - Erstellen Sie die Objekttabelle und verknüpfen Sie sie mit der Anweisung
CREATE EXTERNAL TABLE.
Hinweise
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the BigQuery and BigQuery Connection API APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles. -
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the BigQuery and BigQuery Connection API APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles. - Zum Erstellen von Datasets und Tabellen benötigen Sie die Rolle „BigQuery-Datenbearbeiter“ (
roles/bigquery.dataEditor). - Zum Erstellen einer Verbindung benötigen Sie die Rolle „BigQuery-Verbindungsadministrator“ (
roles/bigquery.connectionAdmin). - Wenn Sie dem Dienstkonto der Verbindung eine Rolle zuweisen möchten, benötigen Sie die Rolle „Project IAM Admin“ (
roles/resourcemanager.projectIamAdmin). - Rolle „BigQuery-Datenbetrachter“ (
roles/bigquery.dataViewer) - Rolle „BigQuery-Verbindungsnutzer“ (
roles/bigquery.connectionUser) bigquery.datasets.createbigquery.tables.createbigquery.tables.updatebigquery.connections.createbigquery.connections.getbigquery.connections.listbigquery.connections.updatebigquery.connections.usebigquery.connections.deletebigquery.connections.delegatestorage.bucket.*storage.object.*bigquery.jobs.createbigquery.tables.getbigquery.tables.getDatabigquery.readsessions.createÖffnen Sie in der Google Cloud Console die Seite BigQuery.
Klicken Sie im linken Bereich auf Explorer:

Wenn Sie den linken Bereich nicht sehen, klicken Sie auf Linken Bereich maximieren, um ihn zu öffnen.
Klicken Sie im Bereich Explorer auf den Namen Ihres Projekts.
Klicken Sie auf Aktionen ansehen > Dataset erstellen.
Führen Sie auf der Seite Dataset erstellen die folgenden Schritte aus:
Geben Sie für die Dataset-ID einen Namen für das Dataset ein.
Wählen Sie als Standorttyp die Option Region oder Mehrere Regionen aus.
- Wenn Sie Region ausgewählt haben, wählen Sie einen Standort aus der Liste Region aus.
- Wenn Sie Mehrere Regionen ausgewählt haben, wählen Sie in der Liste Mehrere Regionen die Option USA oder Europa aus.
Klicken Sie auf Dataset erstellen.
Rufen Sie die Seite BigQuery auf.
Klicken Sie im linken Bereich auf Explorer:

Klicken Sie im Bereich Explorer auf Daten hinzufügen.
Das Dialogfeld Daten hinzufügen wird geöffnet.
Wählen Sie im Bereich Filtern nach im Abschnitt Datenquellentyp die Option Geschäftsanwendungen aus.
Alternativ können Sie im Feld Nach Datenquellen suchen
Vertex AIeingeben.Klicken Sie im Abschnitt Empfohlene Datenquellen auf Vertex AI.
Klicken Sie auf die Lösungsübersichtskarte Vertex AI-Modelle: BigQuery Federation.
Wählen Sie in der Liste Verbindungstyp die Option Vertex AI-Remote-Modelle, Remote-Funktionen, BigLake und Cloud Spanner (Cloud-Ressource) aus.
Geben Sie im Feld Verbindungs-ID einen Namen für die Verbindung ein.
Wählen Sie als Standorttyp die Option Region oder Mehrere Regionen aus.
- Wenn Sie Region ausgewählt haben, wählen Sie einen Standort aus der Liste Region aus.
- Wenn Sie Mehrere Regionen ausgewählt haben, wählen Sie in der Liste Mehrere Regionen die Option USA oder Europa aus.
Klicken Sie auf Verbindung erstellen.
Klicken Sie auf Zur Verbindung.
Kopieren Sie im Bereich Verbindungsinformationen die Dienstkonto-ID zur Verwendung in einem folgenden Schritt.
Zur Seite IAM & Verwaltung.
Klicken Sie auf Hinzufügen.
Das Dialogfeld Principals hinzufügen wird geöffnet.
Geben Sie im Feld Neue Hauptkonten die Dienstkonto-ID ein, die Sie zuvor kopiert haben.
Wählen Sie im Feld Rolle auswählen die Option Cloud Storage und dann Storage-Objekt-Betrachter aus.
Klicken Sie auf Speichern.
PROJECT_NUMBER: die Projektnummer des Projekts, in dem die Rolle gewährt werden soll.MEMBER: Die Dienstkonto-ID, die Sie zuvor kopiert haben.Öffnen Sie in der Google Cloud Console die Seite BigQuery.
Geben Sie im Abfrageeditor die folgende Anweisung ein:
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME` WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT} OPTIONS( object_metadata = 'SIMPLE', uris = ['BUCKET_PATH'[,...]], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE');
Dabei gilt:
PROJECT_IDist Ihre Projekt-ID.DATASET_ID: die ID des Datasets, das die Objekttabelle enthalten soll.TABLE_NAME: der Name der ObjekttabelleREGION: die Region oder Multiregion, die die Verbindung enthält.CONNECTION_ID: die ID der Cloud-Ressourcenverbindung, die mit dieser Objekttabelle verwendet werden soll. Die Verbindung bestimmt, welches Dienstkonto zum Lesen von Daten aus Cloud Storage verwendet wird.Wenn Sie sich Verbindungsdetails in der Google Cloud Console ansehen, ist die Verbindungs-ID der Wert im letzten Abschnitt der voll qualifizierten Verbindungs-ID, der unter Verbindungs-ID angezeigt wird, z. B.
projects/myproject/locations/connection_location/connections/myconnection.Wenn Sie eine Standardverbindung verwenden möchten, geben Sie
DEFAULTanstelle des Verbindungsstrings mit PROJECT_ID.REGION.CONNECTION_ID an.BUCKET_PATH: der Pfad zum Cloud Storage-Bucket, der die von der Objekttabelle dargestellten Objekte im Format['gs://bucket_name/[folder_name/]*']enthält.Sie können in jedem Pfad ein Sternchen (
*) als Platzhalterzeichen verwenden, um die in der Objekttabelle enthaltenen Objekte zu begrenzen. Beispiel: Wenn der Bucket mehrere Arter unstrukturierten Daten enthält, können Sie bestimmen, dass für die Erstellung der Objekttabelle nur PDF-Objekte genutzt werden. Dazu geben Sie['gs://bucket_name/*.pdf']an. Weitere Informationen finden Sie unter Unterstützung von Platzhaltern für Cloud Storage-URIs.Sie können mehrere Buckets für die Option
urisangeben. Dazu geben Sie mehrere Pfade an, z. B.['gs://mybucket1/*', 'gs://mybucket2/folder5/*'].Weitere Informationen zur Verwendung von Cloud Storage-URIs in BigQuery finden Sie unter Cloud Storage-Ressourcenpfad.
STALENESS_INTERVAL: gibt an, ob im Cache gespeicherte Metadaten von Vorgängen für die Objekttabelle verwendet werden und wie aktuell die im Cache gespeicherten Metadaten sein müssen, damit sie vom Vorgang verwendet werden können. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.Geben Sie 0 an, um das Caching von Metadaten zu deaktivieren. Das ist die Standardeinstellung.
Geben Sie zum Aktivieren des Metadaten-Cachings für das Intervallliteral einen Wert zwischen 30 Minuten und 7 Tagen an. Beispiel: Geben Sie
INTERVAL 4 HOURfür ein Veralterungsintervall von vier Stunden an. Mit diesem Wert verwenden Vorgänge im Zusammenhang mit der Tabelle im Cache gespeicherte Metadaten, wenn sie innerhalb der letzten vier Stunden aktualisiert wurden. Sind die im Cache gespeicherten Metadaten älter, werden für den Vorgang stattdessen Metadaten aus Cloud Storage abgerufen.CACHE_MODE: gibt an, ob der Metadaten-Cache automatisch oder manuell aktualisiert wird. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.Legen Sie
AUTOMATICfest, damit der Metadaten-Cache in einem systemdefinierten Intervall aktualisiert wird, normalerweise zwischen 30 und 60 Minuten.Legen Sie
MANUALfest, wenn Sie den Metadaten-Cache nach einem von Ihnen bestimmten Zeitplan aktualisieren möchten. In diesem Fall können Sie den SystemvorgangBQ.REFRESH_EXTERNAL_METADATA_CACHEaufrufen, um den Cache zu aktualisieren.Sie müssen
CACHE_MODEfestlegen, wennSTALENESS_INTERVALauf einen Wert größer als 0 festgelegt ist.
Klicken Sie auf Ausführen.
PROJECT_IDist Ihre Projekt-ID.DATASET_ID: die ID des Datasets, das die Objekttabelle enthalten soll.TABLE_NAME: der Name der ObjekttabelleREGION: die Region oder Multiregion, die die Verbindung enthält.CONNECTION_ID: die ID der Cloud-Ressourcenverbindung, die mit dieser externen Tabelle verwendet werden soll. Die Verbindung bestimmt, welches Dienstkonto zum Lesen von Daten aus Cloud Storage verwendet wird.Wenn Sie sich Verbindungsdetails in der Google Cloud Console ansehen, ist die Verbindungs-ID der Wert im letzten Abschnitt der voll qualifizierten Verbindungs-ID, der unter Verbindungs-ID angezeigt wird, z. B.
projects/myproject/locations/connection_location/connections/myconnection.BUCKET_PATH: der Pfad zum Cloud Storage-Bucket, der die von der Objekttabelle dargestellten Objekte im Formatgs://bucket_name/[folder_name/]*enthält.Sie können in jedem Pfad ein Sternchen (
*) als Platzhalterzeichen verwenden, um die in der Objekttabelle enthaltenen Objekte zu begrenzen. Beispiel: Wenn der Bucket mehrere Arter unstrukturierten Daten enthält, können Sie bestimmen, dass für die Erstellung der Objekttabelle nur PDF-Objekte genutzt werden. Dazu geben Siegs://bucket_name/*.pdfan. Weitere Informationen finden Sie unter Unterstützung von Platzhaltern für Cloud Storage-URIs.Sie können mehrere Buckets für die Option
urisangeben. Dazu geben Sie mehrere Pfade an, z. B.gs://mybucket1/*,gs://mybucket2/folder5/*.Weitere Informationen zur Verwendung von Cloud Storage-URIs in BigQuery finden Sie unter Cloud Storage-Ressourcenpfad.
STALENESS_INTERVAL: gibt an, ob im Cache gespeicherte Metadaten von Vorgängen für die Objekttabelle verwendet werden und wie aktuell die im Cache gespeicherten Metadaten sein müssen, damit sie vom Vorgang verwendet werden können. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.Geben Sie 0 an, um das Caching von Metadaten zu deaktivieren. Das ist die Standardeinstellung.
Geben Sie zum Aktivieren des Metadaten-Cachings einen Intervallwert zwischen 30 Minuten und 7 Tagen unter Verwendung des in der
INTERVAL-Datentypdokumentation beschriebenen FormatsY-M D H:M:S. Beispiel: Geben Sie0-0 0 4:0:0für ein Veralterungsintervall von vier Stunden an. Mit diesem Wert verwenden Vorgänge im Zusammenhang mit der Tabelle im Cache gespeicherte Metadaten, wenn sie innerhalb der letzten vier Stunden aktualisiert wurden. Sind die im Cache gespeicherten Metadaten älter, werden für den Vorgang stattdessen Metadaten aus Cloud Storage abgerufen.CACHE_MODE: gibt an, ob der Metadaten-Cache automatisch oder manuell aktualisiert wird. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.Legen Sie
AUTOMATICfest, damit der Metadaten-Cache in einem systemdefinierten Intervall aktualisiert wird, normalerweise zwischen 30 und 60 Minuten.Legen Sie
MANUALfest, wenn Sie den Metadaten-Cache nach einem von Ihnen bestimmten Zeitplan aktualisieren möchten. In diesem Fall können Sie den SystemvorgangBQ.REFRESH_EXTERNAL_METADATA_CACHEaufrufen, um den Cache zu aktualisieren.Sie müssen
CACHE_MODEfestlegen, wennSTALENESS_INTERVALauf einen Wert größer als 0 festgelegt ist.- Rufen Sie Cloud Shell auf.
-
Legen Sie das Standardprojekt Google Cloud fest, auf das Sie Ihre Terraform-Konfigurationen anwenden möchten.
Sie müssen diesen Befehl nur einmal pro Projekt und in jedem beliebigen Verzeichnis ausführen.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
Umgebungsvariablen werden überschrieben, wenn Sie in der Terraform-Konfigurationsdatei explizite Werte festlegen.
-
Erstellen Sie in Cloud Shell ein Verzeichnis und eine neue Datei in diesem Verzeichnis. Der Dateiname muss die Erweiterung
.tfhaben, z. B.main.tf. In dieser Anleitung wird die Datei alsmain.tfbezeichnet.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
Wenn Sie einer Anleitung folgen, können Sie den Beispielcode in jedem Abschnitt oder Schritt kopieren.
Kopieren Sie den Beispielcode in das neu erstellte
main.tf.Kopieren Sie optional den Code aus GitHub. Dies wird empfohlen, wenn das Terraform-Snippet Teil einer End-to-End-Lösung ist.
- Prüfen und ändern Sie die Beispielparameter, die auf Ihre Umgebung angewendet werden sollen.
- Speichern Sie die Änderungen.
-
Initialisieren Sie Terraform. Dies ist nur einmal für jedes Verzeichnis erforderlich.
terraform init
Fügen Sie optional die Option
-upgradeein, um die neueste Google-Anbieterversion zu verwenden:terraform init -upgrade
-
Prüfen Sie die Konfiguration und prüfen Sie, ob die Ressourcen, die Terraform erstellen oder aktualisieren wird, Ihren Erwartungen entsprechen:
terraform plan
Korrigieren Sie die Konfiguration nach Bedarf.
-
Wenden Sie die Terraform-Konfiguration an. Führen Sie dazu den folgenden Befehl aus und geben Sie
yesan der Eingabeaufforderung ein:terraform apply
Warten Sie, bis Terraform die Meldung „Apply complete“ anzeigt.
- Öffnen Sie Ihr Google Cloud Projekt, um die Ergebnisse aufzurufen. Rufen Sie in der Google Cloud Console Ihre Ressourcen in der Benutzeroberfläche auf, um sicherzustellen, dass Terraform sie erstellt oder aktualisiert hat.
Erforderliche Rollen
Zum Erstellen von Objekttabellen benötigen Sie die folgenden Rollen für das Projekt:
Zum Abfragen von Objekttabellen benötigen Sie die folgenden Rollen für das Projekt:
Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:
Erforderliche Berechtigungen
Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.
Dataset erstellen
Erstellen Sie ein BigQuery-Dataset für die Objekttabelle:
Verbindung herstellen
Sie können diesen Schritt überspringen, wenn Sie entweder eine Standardverbindung konfiguriert haben oder die Rolle „BigQuery-Administrator“ haben.
Erstellen Sie eine Cloud-Ressourcenverbindung für die Objekttabelle und rufen Sie das Dienstkonto der Verbindung ab.
Dem Dienstkonto Zugriff gewähren
Weisen Sie dem Dienstkonto der Verbindung die Rolle „Storage-Objekt-Betrachter“ zu:
Console
gcloud
Führen Sie den Befehl gcloud projects add-iam-policy-binding aus.
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None
Ersetzen Sie Folgendes:
Objekttabelle erstellen
So erstellen Sie eine Objekttabelle:
SQL
Verwenden Sie die Anweisung CREATE EXTERNAL TABLE.
Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.
Beispiele
Im folgenden Beispiel wird eine Objekttabelle mit einem Veralterungsintervall eines Metadaten-Cache von 1 Tag erstellt:
CREATE EXTERNAL TABLE `my_dataset.object_table` WITH CONNECTION `us.my-connection` OPTIONS( object_metadata = 'SIMPLE', uris = ['gs://mybucket/*'], max_staleness = INTERVAL 1 DAY, metadata_cache_mode = 'AUTOMATIC' );
Im folgenden Beispiel wird eine Objekttabelle über die Objekte in drei Cloud Storage-Buckets erstellt:
CREATE EXTERNAL TABLE `my_dataset.object_table` WITH CONNECTION `us.my-connection` OPTIONS( object_metadata = 'SIMPLE', uris = ['gs://bucket1/*','gs://bucket2/folder1/*','gs://bucket3/*'] );
Im folgenden Beispiel wird eine Objekttabelle über die PDF-Objekte in einem Cloud Storage-Bucket erstellt:
CREATE EXTERNAL TABLE `my_dataset.object_table` WITH CONNECTION `us.my-connection` OPTIONS( object_metadata = 'SIMPLE', uris = ['gs://bucket1/*.pdf'] );
bq
Führen Sie den Befehl bq mk aus.
bq mk --table \ --external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \ --object_metadata=SIMPLE \ --max_staleness=STALENESS_INTERVAL \ --metadata_cache_mode=CACHE_MODE \ PROJECT_ID:DATASET_ID.TABLE_NAME
Dabei gilt:
Beispiele
Im folgenden Beispiel wird eine Objekttabelle mit einem Veralterungsintervall eines Metadaten-Cache von 1 Tag erstellt:
bq mk --table \ --external_table_definition=gs://mybucket/*@us.my-connection \ --object_metadata=SIMPLE \ --max_staleness=0-0 1 0:0:0 \ --metadata_cache_mode=AUTOMATIC \ my_dataset.object_table
Im folgenden Beispiel wird eine Objekttabelle über die Objekte in drei Cloud Storage-Buckets erstellt:
bq mk --table \ --external_table_definition=gs://bucket1/*,gs://bucket2/folder1/*,gs://bucket3/*@us.my-connection \ --object_metadata=SIMPLE \ my_dataset.object_table
Im folgenden Beispiel wird eine Objekttabelle über die PDF-Objekte in einem Cloud Storage-Bucket erstellt:
bq mk --table \ --external_table_definition=gs://bucket1/*.pdf@us.my-connection \ --object_metadata=SIMPLE \ my_dataset.object_table
API
Rufen Sie die Methode tables.insert auf.
Fügen Sie ein ExternalDataConfiguration-Objekt ein, bei dem das Feld objectMetadata in der Table-Ressource auf SIMPLE gesetzt ist. die Sie übergeben.
Das folgende Beispiel zeigt, wie diese Methode mithilfe von curl aufgerufen wird:
ACCESS_TOKEN=$(gcloud auth print-access-token) curl \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST \
-d '{"tableReference": {"projectId": "my_project", "datasetId": "my_dataset", "tableId": "object_table_name"}, "externalDataConfiguration": {"objectMetadata": "SIMPLE", "sourceUris": ["gs://mybucket/*"]}}' \
https://www.googleapis.com/bigquery/v2/projects/my_project/datasets/my_dataset/tables
Terraform
In diesem Beispiel wird eine Objekttabelle mit aktiviertem Metadaten-Caching und manueller Aktualisierung erstellt.
Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Die Schlüsselfelder, die für eine Objekttabelle angegeben werden sollen, sind: google_bigquery_table.external_data_configuration.object_metadata, google_bigquery_table.external_data_configuration.metadata_cache_mode und google_bigquery_table.max_staleness. Weitere Informationen zu den einzelnen Ressourcen finden Sie in der Terraform-Dokumentation zu BigQuery.
Führen Sie die Schritte in den folgenden Abschnitten aus, um Ihre Terraform-Konfiguration auf ein Google Cloud -Projekt anzuwenden.
Cloud Shell vorbereiten
Verzeichnis vorbereiten
Jede Terraform-Konfigurationsdatei muss ein eigenes Verzeichnis haben (auch als Stammmodul bezeichnet).
Änderungen anwenden
Objekttabellen abfragen
Sie können eine Objekttabelle wie jede andere BigQuery-Abfrage abfragen. Beispiel:
SELECT * FROM mydataset.myobjecttable;
Beim Abfragen einer Objekttabelle werden Metadaten für die zugrunde liegenden Objekte zurückgegeben. Weitere Informationen finden Sie unter Objekttabellenschema.