Mit ObjectRef-Werten arbeiten

In diesem Dokument werden ObjectRef-Werte und ihre Verwendung in BigQuery beschrieben.

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

Schema

Ein ObjectRef-Wert hat die folgenden Felder:

Name Typ Mode Beschreibung Beispiel
uri STRING REQUIRED Die URI des Cloud Storage-Objekts. "gs://cloud-samples-data/vision/demo-img.jpg"
version STRING NULLABLE Die Objektgeneration. "1560286006357632"
authorizer STRING NULLABLE Eine BigQuery-Verbindungs-ID für delegierten Zugriff oder NULL für direkten Zugriff. Die ID kann die folgenden Formate haben:
"region.connection"
oder
"project.region.connection"		 "myproject.us.myconnection"
details JSON NULLABLE Die Objektmetadaten oder Fehler bei der Verarbeitung des Objekts. Sie können die Felder content_type, md5_hash, size und updated für das Objekt enthalten. {"gcs_metadata":{"content_type":"image/png","md5_hash":"dfbbb5cf034af026d89f2dc16930be15","size":915052,"updated":1560286006000000}}

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 der URI ab.

ObjectRef-Werte erstellen

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

Objekttabellen verwenden

Verwenden Sie eine Objekttabelle, wenn Sie keine URIs in einer Tabelle gespeichert haben und alle Objekte aus einem Cloud Storage-Präfix auflisten möchten. In einer Objekttabelle wird der Verweis auf ein Objekt in jeder Zeile gespeichert. Sie hat eine Spalte ref mit ObjectRef-Werten. Die folgende Abfrage verwendet die CREATE EXTERNAL TABLE Anweisung zum Erstellen einer Objekttabelle:

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 Autorisierer für delegierten Zugriff haben. Die Autorisiererverbindung ist dieselbe Verbindung, die Sie zum Erstellen der Objekttabelle verwenden.

Funktion OBJ.MAKE_REF verwenden

Verwenden Sie die OBJ.MAKE_REF Funktion, 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 OBJ.MAKE_REF Funktion akzeptiert einen nullable-Autorisierer, um den direkten Zugriff und den delegierten Zugriff zu unterstützen.

Cloud Storage Insights-Datasets verwenden

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

Autorisierer und Berechtigungen

Wenn Sie einen ObjectRef-Wert an ObjectRef-Funktionen, KI-Funktionen oder benutzerdefinierte Python-Funktionen übergeben, müssen diese Funktionen auf das in Cloud Storage gespeicherte Objekt zugreifen können. 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 Autorisierer 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 AI.GENERATE, AI.IF, AI.SCORE oder AI.CLASSIFY Funktionen ohne Verbindung verwendet, muss der Nutzer zusätzliche Berechtigungenhaben. 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 Autorisierer hat, liest die Funktion das Objekt als Sie. Wenn Sie keine Berechtigung zum Lesen des Objekts haben, schreibt die Funktion einen "permission denied" Fehler in die status Spalte im Ergebnis.

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

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

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. Der delegierte Zugriff kann den projektübergreifenden Datenzugriff ermöglichen.

Wenn Sie den delegierten Zugriff verwenden möchten, muss Ihr Datenadministrator die folgenden Schritte ausführen, um die Verbindung und die Berechtigungen einzurichten:

Wenn ein Nutzer beispielsweise ObjectRef-Werte mit einem Autorisierer 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 die erforderlichen Berechtigungen hat, schreibt die Funktion einen "permission denied" Fehler in die Spalte status im Ergebnis.

Das folgende Beispiel zeigt eine Abfrage, die den delegierten Zugriff verwendet. Dafür sind folgende Voraussetzungen 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 „Vertex AI-Nutzer“.
SELECT AI.GENERATE(
  ("Describe this image:",
    OBJ.GET_ACCESS_RUL(OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg", "us.connection1"), 'r')),
  connection_id => "us.connection2");

Best Practices

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

  • Verwenden Sie den 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 die Identitäts- und Zugriffsverwaltung (Identity and Access Management, IAM), um Nutzern Zugriff auf BigQuery-Daten 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 den 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 mit einer Verbindung als Autorisierer erstellen. 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 müssen nicht auf den ursprünglichen Bucket zugreifen, um die Objekte zu analysieren.

Fehler

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

  • Abfragefehler: Die Abfrage kann mit einer Fehlermeldung fehlschlagen und kein Ergebnis zurückgeben.
  • Zurückgegebene Fehlerwerte: Die Abfrage wird erfolgreich ausgeführt, aber die Funktion kann Fehler als Teil des Rückgabewerts schreiben. Informationen zum Format des Rückgabewerts finden Sie auf der Referenzseite für die verwendete Funktion.

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

Name Typ Mode Beschreibung Beispiel
code INT64 REQUIRED Standard-HTTP-Fehlercode. 400
message STRING REQUIRED Eine beschreibende, nutzerfreundliche Fehlermeldung. "Connection credential for myproject.us.nonexistent_connection cannot be used. Either the connection does not exist, or the user does not have sufficient permissions (bigquery.objectRefs.read)"
source STRING REQUIRED Der Name der Funktion, die den Fehler ausgelöst hat. "OBJ.MAKE_REF"

Dies sind zwei häufige Fehlertypen:

  • Objektfehler: Die angegebene Objekt-URI oder ‑version ist nicht vorhanden.
  • Autorisiererfehler: 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