Mit ObjectRef-Werten arbeiten

In diesem Dokument werden ObjectRef-Werte beschrieben und es wird erläutert, wie Sie sie in BigQuery erstellen und verwenden.

Ein ObjectRef-Wert ist ein STRUCT-Typ mit einem vordefinierten Schema, das auf Cloud Storage-Objekte für die multimodale Analyse verweist. Sie kann mit OBJ-Funktionen, KI-Funktionen oder benutzerdefinierten Python-Funktionen verarbeitet werden.

Schema

Ein ObjectRef-Wert hat die folgenden Felder:

Das Feld content_type im Feld gcs_metadata aus der Spalte details wird aus Cloud Storage abgerufen. Sie können den Inhaltstyp eines Objekts in Cloud Storage festlegen. Wenn Sie ihn in Cloud Storage weglassen, leitet BigQuery den Inhaltstyp aus dem Suffix des URI ab.

ObjectRef-Werte erstellen

Sie können ObjectRef-Werte mit Objekttabellen, der Funktion OBJ.MAKE_REF, der Funktion OBJ.LIST oder Cloud Storage Insights-Datasets erstellen.

Objekttabellen verwenden

Verwenden Sie eine Objekttabelle, wenn Sie keine URIs in einer Tabelle gespeichert haben und eine Liste aller Objekte aus einem Cloud Storage-Präfix beibehalten möchten. In einer Objekttabelle wird in jeder Zeile der Verweis auf ein Objekt gespeichert. Sie hat eine ref-Spalte, die ObjectRef-Werte enthält. In der folgenden Abfrage wird mit der Anweisung CREATE EXTERNAL TABLE eine Objekttabelle erstellt:

CREATE EXTERNAL TABLE mydataset.images
WITH CONNECTION `us.myconnection`
OPTIONS (uris=["gs://mybucket/images/*"], object_metadata="SIMPLE");

SELECT ref AS image_ref FROM mydataset.images;

ObjectRef-Werte aus einer Objekttabelle müssen einen Autor für delegierten Zugriff haben. Die Autorisiererverbindung ist dieselbe Verbindung, die Sie zum Erstellen der Objekttabelle verwenden.

OBJ.MAKE_REF-Funktion verwenden

Verwenden Sie die Funktion OBJ.MAKE_REF, wenn Sie bereits URIs in einer Tabelle gespeichert haben und ObjectRef-Werte aus diesen URIs erstellen möchten. Die folgenden Abfragen zeigen, wie Sie ObjectRef-Werte in der Spalte image_ref aus der Spalte uri erstellen, die Cloud Storage-URIs enthält:

-- Specify only the URI
SELECT *, OBJ.MAKE_REF(uri) AS image_ref FROM mydataset.images;
-- Specify the URI and the connection
SELECT *, OBJ.MAKE_REF(uri, "us.myconnection") AS image_ref FROM mydataset.images;

Wenn Sie die Autorisierer eines vorhandenen ObjectRef-Werts ändern möchten, können Sie die Funktion OBJ.MAKE_REF verwenden:

-- Remove the authorizer
SELECT *, OBJ.MAKE_REF(ref, authorizer=>NULL) AS image_ref FROM mydataset.images;
-- Change the authorizer
SELECT *, OBJ.MAKE_REF(ref, authorizer=>"us.myconnection2") AS image_ref FROM mydataset.images;

Die Funktion OBJ.MAKE_REF akzeptiert einen nullable Authorizer, um direkten Zugriff und delegierten Zugriff zu unterstützen.

OBJ.LIST-Funktion verwenden

Verwenden Sie die Funktion OBJ.LIST für spontane Entdeckungen. Die Funktion OBJ.LIST gibt eine Tabelle mit Metadaten und ObjectRef-Werten für in Cloud Storage gespeicherte Dateien zurück. Die Cloud Storage-Daten können Dokumente, Bilder und Audioinhalte enthalten.

Durch die Verwendung von OBJ.LIST müssen ObjectRef-Werte in einer persistenten Tabelle nicht mehr manuell erstellt werden. Sie können schnell Cloud Storage-Objekte in KI-Funktionen einfügen, um spontane ETL-Pipelines zu erstellen, mit denen unstrukturierte Daten in strukturierte Daten umgewandelt werden. Wenn Sie eine dauerhafte, sich selbst aktualisierende Tabelle benötigen, in der neue Objekte, die im Laufe der Zeit in einem Bucket eingehen, kontinuierlich erfasst werden, sollten Sie stattdessen eine Standard-BigQuery-Objekttabelle erstellen.

In der folgenden Abfrage wird das Platzhalterzeichen (*) verwendet, um bestimmte Dateitypen zu ermitteln, und die Funktion AI.IF, um unstrukturierte Daten zu filtern. Mit dieser Anfrage werden nur die PNG-Dateien aufgelistet, die ein Bild eines Hundes enthalten.

SELECT
  uri,
  content_type,
  size
FROM
  OBJ.LIST('gs://mybucket/images/*.png')
WHERE
  AI.IF(('Does this image contain a dog?', ref))
ORDER BY
  uri;

Cloud Storage Insights-Datasets verwenden

Wenn Sie ein Storage Insights-Dataset konfiguriert haben, enthält es bereits eine ref-Spalte mit ObjectRef-Werten. Für alle ObjectRef-Werte, die in Storage Insights-Datasets erstellt wurden, ist kein Autorizer vorhanden. Wenn Sie diese Objekte abfragen möchten, benötigen Sie entweder direkten Zugriff auf das Objekt oder Sie müssen dem ObjectRef einen Authorizer hinzufügen, um delegierten Zugriff zu verwenden.

Autorisierung und Berechtigungen

Wenn Sie einen ObjectRef-Wert an ObjectRef-Funktionen, KI-Funktionen oder Python-UDFs übergeben, müssen diese Funktionen auf das in Cloud Storage gespeicherte Objekt zugreifen. Sie können diesen Zugriff basierend auf dem Wert des Felds authorizer auf zwei Arten autorisieren: direkter Zugriff und delegierter Zugriff.

Direktzugriff

Beim direkten Zugriff greift der Nutzer, der die Abfrage ausführt, mit seinen eigenen Anmeldedaten direkt auf das Objekt zu. Der direkte Zugriff wird verwendet, wenn der ObjectRef-Wert keinen Authorizer hat.

Für den direkten Zugriff gelten die folgenden Einschränkungen:

• Der Nutzer muss die Berechtigung haben, auf die Objekte zuzugreifen.
• Für einen Abfragejob, der die Funktionen AI.GENERATE, AI.IF, AI.SCORE oder AI.CLASSIFY ohne Verbindung verwendet, muss der Nutzer zusätzliche Berechtigungen haben. Die Abfrage kann nur auf Cloud Storage-Buckets und -Objekte aus demselben Projekt zugreifen, in dem der Job ausgeführt wird.

Wenn Sie beispielsweise die Funktion AI.GENERATE für einen ObjectRef-Wert aufrufen, der keinen Authorizer hat, liest die Funktion das Objekt als Sie. Wenn Sie nicht berechtigt sind, das Objekt zu lesen, schreibt die Funktion einen "permission denied"-Fehler in die Spalte status im Ergebnis.

Das folgende Beispiel zeigt eine Abfrage, die direkten Zugriff verwendet:

-- Requires that the end user can read the object "gs://cloud-samples-data/vision/demo-img.jpg" and use the Agent Platform model.
SELECT AI.GENERATE(
  ("Describe this image:",
  OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg")));

Delegierter Zugriff

Beim delegierten Zugriff delegiert der Nutzer, der die Abfrage ausführt, den Objektzugriff an eine BigQuery Cloud-Ressourcenverbindung, die im Feld authorizer des Werts ObjectRef angegeben ist. Durch delegierten Zugriff kann projektübergreifender Datenzugriff ermöglicht werden.

Damit Sie den delegierten Zugriff verwenden können, muss Ihr Datenadministrator die folgenden Schritte ausführen, um die Verbindung und die Berechtigungen einzurichten:

• Einmalige Einrichtung: Der Datenadministrator muss eine Cloud-Ressourcenverbindung einrichten, um den Cloud Storage-Bucket zu verwalten:
  1. Erstellen Sie eine neue BigQuery-Cloud-Ressourcenverbindung oder verwenden Sie eine vorhandene im Projekt wieder.
  2. Suchen Sie das Dienstkonto in den Metadaten der Verbindung.
  3. Gewähren Sie dem Dienstkonto die Berechtigung storage.objects.get für Lesezugriff oder die Berechtigung storage.objects.create für Schreibzugriff im Projekt oder in den Cloud Storage-Buckets. Sie können diese Berechtigungen mit den Rollen Storage Object Viewer oder Storage Object User gewähren.
• Einrichtung pro Nutzer Der Datenadministrator muss Nutzern die Berechtigung bigquery.objectRefs.read für Lesezugriffe oder die Berechtigung bigquery.objectRefs.write für Schreibzugriffe für die BigQuery-Verbindung gewähren. Sie können diese Berechtigungen mit den Rollen BigQuery ObjectRef Reader oder BigQuery ObjectRef Admin gewähren.

Wenn ein Nutzer beispielsweise ObjectRef-Werte mit einem Authorizer an eine AI.GENERATE-Funktion übergibt, prüft die Funktion, ob der Nutzer die Berechtigung bigquery.objectRefs.read hat, und liest dann die Objekte mit dem Dienstkonto der Verbindung. Wenn der Nutzer oder das Dienstkonto nicht über ausreichende Berechtigungen verfügt, wird in der Spalte status des Ergebnisses ein "permission denied"-Fehler ausgegeben.

Das folgende Beispiel zeigt eine Abfrage, die den delegierten Zugriff verwendet. Dazu ist Folgendes erforderlich:

• Der Nutzer hat die Berechtigung bigquery.objectRefs.read für connection1.
• Das Dienstkonto für connection1 hat die Berechtigung storage.objects.get für das Objekt.
• Das Dienstkonto für connection2 hat die Rolle „Agent Platform User“.

SELECT AI.GENERATE(
  ("Describe this image:",
    OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg", "us.connection1")),
  connection_id => "us.connection2");

Innerhalb eines VPC Service Controls-Perimeters können KI-Funktionen keine ObjectRef-Werte verarbeiten, für die delegierter Zugriff verwendet wird. Durch den delegierten Zugriff wird eine signierte HTTPS-URL für das Objekt generiert und die Gemini Enterprise Agent Platform blockiert HTTP- und HTTPS-Abrufe für Projekte innerhalb eines Perimeters. Die Funktion schreibt den folgenden Fehler in die Spalte status im Ergebnis:

INVALID_ARGUMENT: HTTP links are not supported for requests restricted by VPCSC.

Da in der Spalte ref einer Objekttabelle immer die Verbindung der Objekttabelle als Autorisierer verwendet wird, wird dieser Fehler immer zurückgegeben, wenn ref an eine KI-Funktion innerhalb eines Perimeters übergeben wird. Um das Objekt zu analysieren, übergeben Sie stattdessen einen OBJ.MAKE_REF(uri)-Wert mit einem Argument, der direkten Zugriff verwendet und die Cloud Storage-URI an das Modell sendet, ohne eine signierte URL zu generieren.

Best Practices

Berücksichtigen Sie die folgenden Best Practices, wenn Sie entscheiden, ob Sie direkten oder delegierten Zugriff verwenden möchten:

• Verwenden Sie direkten Zugriff für ein kleines Team, das in einem einzelnen Projekt sowohl für die Datenspeicherung als auch für die Analyse arbeitet. Der Datenadministrator verwendet Identity and Access Management, um Nutzern Zugriff auf BigQuery- und Cloud Storage-Daten zu gewähren. Nutzer können ObjectRef-Werte bei Bedarf ohne Autorisierer erstellen, um Objekte mit ihren eigenen Anmeldedaten zu analysieren.
• Verwenden Sie delegierten Zugriff für ein großes Team, das in mehreren Projekten arbeitet, insbesondere wenn Datenspeicherung und ‑analyse entkoppelt sind. Der Datenadministrator kann Verbindungen einrichten und ObjectRef-Werte für die Analyse im Voraus erstellen. Dabei wird eine Verbindung als Autorisierung verwendet. Dieser Ansatz funktioniert mit Objekttabellen oder mit OBJ.MAKE_REF für eine Liste von URIs. Anschließend kann der Datenadministrator die Tabelle mit den ObjectRef-Werten für Analysten freigeben. Die Analysten benötigen keinen Zugriff auf den ursprünglichen Bucket, um die Objekte zu analysieren.

Fehler

Funktionen, die ObjectRef-Werte verwenden, melden Fehler auf zwei Arten:

• Fehler bei der Abfrage: Die Abfrage schlägt möglicherweise mit einer Fehlermeldung fehl und es wird kein Ergebnis zurückgegeben.
• Zurückgegebene Fehlerwerte: Die Abfrage wird erfolgreich ausgeführt, aber die Funktion schreibt möglicherweise Fehler als Teil des Rückgabewerts. Informationen zum Format des Rückgabewerts finden Sie auf der Referenzseite der verwendeten Funktion.

Wenn eine Funktion einen ObjectRef-Wert zurückgibt, kann das Feld details dieses Werts ein Feld errors enthalten. Wenn dies der Fall ist, ist der Wert dieses Felds ein Array von Fehlern. Jeder Fehler hat das folgende Schema:

Hier sind zwei häufige Arten von Fehlern:

• Objektfehler: Der angegebene Objekt-URI oder die angegebene Version ist nicht vorhanden.
• Autorisierungsfehler: Die Verbindung ist nicht vorhanden oder der Nutzer hat keine Berechtigung, sie für den delegierten Zugriff zu verwenden.

Die folgende Abfrage zeigt, wie Sie ObjectRef-Werte mit Fehlern aus einer Objectref-Spalte auswählen:

SELECT ref
FROM mydataset.images
WHERE ref.details.errors IS NOT NULL;

Nächste Schritte

• ObjectRef-Spalten in Tabellenschemas angeben
• Multimodale Daten analysieren:
• Weitere Informationen zu ObjectRef-Funktionen