Mit ObjectRef-Werten arbeiten

In diesem Dokument werden ObjectRef-Werte beschrieben und 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 können mit 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 Der URI des Cloud Storage-Objekts. "gs://cloud-samples-data/vision/demo-img.jpg"
version STRING NULLABLE Die Objektgenerierung. "1560286006357632"
authorizer STRING NULLABLE Eine BigQuery-Verbindungs-ID für den delegierten Zugriff oder NULL für den 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. Es kann 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 des URI ab.

ObjectRef-Werte erstellen

Sie können ObjectRef-Werte mit Objekttabellen, der OBJ.MAKE_REF-Funktion, der OBJ.LIST-Funktion 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 persistent speichern möchten. In einer Objekttabelle wird der Verweis auf ein Objekt in jeder Zeile gespeichert. Sie enthält eine ref-Spalte mit ObjectRef-Werten. In der folgenden Abfrage wird die Anweisung CREATE EXTERNAL TABLE verwendet, um eine Objekttabelle zu erstellen:

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 Autorisierungsverbindung ist dieselbe Verbindung, die Sie zum Erstellen der Objekttabelle verwenden.

Verwenden Sie die Funktion OBJ.MAKE_REF.

Verwenden Sie die Funktion OBJ.MAKE_REF, wenn Sie bereits URIs in einer Tabelle gespeichert haben und aus diesen URIs ObjectRef-Werte 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 nullfähigen Autorisierer, um den direkten Zugriff und den delegierten Zugriff zu unterstützen.

Verwenden Sie die Funktion OBJ.LIST.

Verwenden Sie die Funktion OBJ.LIST für die spontane Erkennung. 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.

Wenn Sie OBJ.LIST verwenden, müssen Sie ObjectRef-Werte in einer persistenten Tabelle nicht manuell erstellen. Sie können Cloud Storage-Objekte schnell in KI-Funktionen einfügen, um spontane ETL-Pipelines zu erstellen, die unstrukturierte Daten in strukturierte Daten umwandeln. Wenn Sie eine persistente, sich selbst aktualisierende Tabelle benötigen, die neue Objekte, die im Laufe der Zeit in einem Bucket eingehen, kontinuierlich verfolgt, sollten Sie stattdessen eine BigQuery-Standardobjekttabelle erstellen.

In der folgenden Abfrage wird das Platzhalterzeichen (*) verwendet, um bestimmte Dateitypen zu finden. Außerdem wird die Funktion AI.IF verwendet, um unstrukturierte Daten zu filtern. Diese Abfrage listet nur die PNG-Dateien auf, 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 das Dataset bereits eine Spalte ref mit ObjectRef-Werten. Alle ObjectRef-Werte, die in Storage Insights-Datasets erstellt werden, haben keinen Autorisierer. Wenn Sie diese Objekte abfragen möchten, müssen Sie entweder direkten Zugriff auf das Objekt haben oder der ObjectRef einen Autorisierer hinzufügen, um delegierten Zugriff zu verwenden.

Autorisierer 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 Wert ObjectRef 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 Funktionen AI.GENERATE, AI.IF, AI.SCORE oder AI.CLASSIFY ohne Verbindung verwendet, benötigt der Nutzer zusätzliche Berechtigungen. Die Abfrage kann nur auf Cloud Storage-Buckets und -Objekte aus dem 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 Leseberechtigung für das Objekt haben, 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. 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 mithilfe des Dienstkontos der Verbindung. Wenn der Nutzer oder das Dienstkonto nicht über ausreichende Berechtigungen verfügt, schreibt die Funktion einen "permission denied"-Fehler in die Spalte status im Ergebnis.

Das folgende Beispiel zeigt eine Abfrage, die delegierten Zugriff verwendet. Hierfür 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, die delegierten Zugriff verwenden. Der delegierte Zugriff generiert eine signierte HTTPS-URL für das Objekt. Signierte URLs können jedoch keine Perimetergrenzen überschreiten. Die Funktion schreibt einen der folgenden Fehler in die Spalte status im Ergebnis:

  • INVALID_ARGUMENT: HTTP links are not supported for requests restricted by VPCSC. Dieser Fehler tritt auf, wenn Ihr Perimeter die Agent Platform einschränkt.
  • Cannot fetch content from the provided URL Dieser Fehler tritt auf, wenn Ihr Perimeter Cloud Storage einschränkt.

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

Best Practices

Beachten Sie die folgenden Best Practices, wenn Sie entscheiden, ob Sie direkten oder 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 Identity and Access Management, um Nutzern Zugriff auf BigQuery- und Cloud Storage-Daten zu gewähren. Nutzer können ObjectRef-Werte bei Bedarf ohne Autorisierung erstellen, um Objekte mit ihren eigenen Anmeldedaten zu analysieren.
  • Verwenden Sie den delegierten Zugriff für ein großes Team, das an 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 durch Verwendung von 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. Da der delegierte Zugriff Zugriff auf alle Objekte gewährt, die das Dienstkonto der Verbindung erreichen kann, unabhängig von Zugriffsrichtlinien auf Zeilenebene für Objekttabellen oder Standardtabellen, sollten Sie die Cloud Storage-Berechtigungen jeder Verbindung nur auf die Buckets oder verwalteten Ordner beschränken, auf die die Nutzer zugreifen dürfen.

Fehler

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

  • Abfragefehler: Die Abfrage schlägt möglicherweise mit einer Fehlermeldung und ohne Ergebnis fehl.
  • Zurückgegebene Fehlerwerte: Die Abfrage ist erfolgreich, aber die Funktion schreibt möglicherweise Fehler als Teil des Rückgabewerts. Informationen zum Format des Rückgabewerts finden Sie auf der Referenzseite für die von Ihnen verwendete Funktion.

Wenn eine Funktion einen ObjectRef-Wert zurückgibt, kann das Feld details dieses Werts ein errors-Feld enthalten. Wenn ja, 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: Der angegebene Objekt-URI oder die angegebene Version ist nicht vorhanden.
  • Autorisierungsfehler: Die Verbindung ist nicht vorhanden oder der Nutzer ist nicht berechtigt, 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