Utilizzare i valori ObjectRef

Questo documento descrive i valori di ObjectRef e come crearli e utilizzarli in BigQuery.

Un valore ObjectRef è un tipo STRUCT con uno schema predefinito che fa riferimento agli oggetti Cloud Storage per l'analisi multimodale. Può essere elaborato da funzioni OBJ, funzioni AI o funzioni definite dall'utente Python.

Schema

Un valore ObjectRef ha i seguenti campi:

Nome Tipo Modalità Descrizione Esempio
uri STRING REQUIRED L'URI dell'oggetto Cloud Storage. "gs://cloud-samples-data/vision/demo-img.jpg"
version STRING NULLABLE La generazione dell'oggetto. "1560286006357632"
authorizer STRING NULLABLE Un ID connessione BigQuery per l'accesso delegato o NULL per l'accesso diretto. L'ID può avere i seguenti formati:
"region.connection"
o
"project.region.connection"		 "myproject.us.myconnection"
details JSON NULLABLE I metadati dell'oggetto o gli errori durante l'elaborazione dell'oggetto. Può includere i campi content_type, md5_hash, size e updated per l'oggetto. {"gcs_metadata":{"content_type":"image/png","md5_hash":"dfbbb5cf034af026d89f2dc16930be15","size":915052,"updated":1560286006000000}}

Il campo content_type nel campo gcs_metadata della colonna details viene recuperato da Cloud Storage. Puoi impostare il tipo di contenuto di un oggetto in Cloud Storage. Se lo ometti in Cloud Storage, BigQuery deduce il tipo di contenuto dal suffisso dell'URI.

Crea valori ObjectRef

Puoi creare valori ObjectRef utilizzando le tabelle degli oggetti, la funzione OBJ.MAKE_REF, la funzione OBJ.LIST o i set di dati Cloud Storage Insights.

Utilizzare le tabelle di oggetti

Utilizza una tabella di oggetti se non hai URI archiviati in una tabella e vuoi rendere persistente un elenco di tutti gli oggetti di un prefisso Cloud Storage. Una tabella degli oggetti memorizza il riferimento a un oggetto in ogni riga e ha una colonna ref che contiene valori ObjectRef. La seguente query utilizza l'istruzione CREATE EXTERNAL TABLE per creare una tabella di oggetti:

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;

I valori ObjectRef di una tabella di oggetti devono avere un autorizzatore per l'accesso delegato. La connessione dell'autorizzatore è la stessa che utilizzi per creare la tabella degli oggetti.

Utilizzare la funzione OBJ.MAKE_REF

Utilizza la funzione OBJ.MAKE_REF se hai già URI memorizzati in una tabella e vuoi creare valori ObjectRef da questi URI. Le seguenti query mostrano come creare valori ObjectRef nella colonna image_ref dalla colonna uri che contiene URI Cloud Storage:

-- 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;

Per modificare gli autori di un valore ObjectRef esistente, puoi utilizzare la funzione OBJ.MAKE_REF:

-- 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;

La funzione OBJ.MAKE_REF accetta un autorizzatore nullable per supportare l'accesso diretto e l'accesso delegato.

Utilizzare la funzione OBJ.LIST

Utilizza la funzione OBJ.LIST per la scoperta spontanea. La funzione OBJ.LIST restituisce una tabella di metadati e valori ObjectRef per i file archiviati in Cloud Storage. I dati di Cloud Storage possono includere documenti, immagini e audio.

L'utilizzo di OBJ.LIST elimina la necessità di creare manualmente i valori ObjectRef in una tabella persistente. Puoi aggiungere rapidamente oggetti Cloud Storage alle funzioni AI per creare pipeline ETL spontanee che gestiscono la conversione di dati non strutturati in dati strutturati. Se hai bisogno di una tabella persistente e autoaggiornante che monitori continuamente i nuovi oggetti che arrivano in un bucket nel tempo, devi creare una tabella degli oggetti BigQuery standard.

La seguente query utilizza il carattere jolly (*) per rilevare tipi di file specifici e la funzione AI.IF per filtrare i dati non strutturati. Questa query elenca solo i file PNG che contengono un'immagine di un cane.

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;

Utilizzare i set di dati di Cloud Storage Insights

Se hai configurato un set di dati Storage Insights, il set di dati include già una colonna ref che contiene valori ObjectRef. I valori di ObjectRef creati nei set di dati di Storage Insights non hanno un autorizzatore. Per eseguire query su questi oggetti, devi disporre dell'accesso diretto all'oggetto o aggiungere un autorizzatore a ObjectRef per utilizzare l'accesso delegato.

Autorizzatore e autorizzazioni

Quando passi un valore ObjectRef alle funzioni ObjectRef, alle funzioni AI o alle UDF Python, queste funzioni devono accedere all'oggetto archiviato in Cloud Storage. Puoi autorizzare questo accesso in base al valore del campo authorizer in due modi: accesso diretto e accesso delegato.

Accesso diretto

Con l'accesso diretto, l'utente che esegue la query accede direttamente all'oggetto utilizzando le proprie credenziali. L'accesso diretto viene utilizzato quando il valore ObjectRef non ha un autorizzatore.

L'accesso diretto presenta le seguenti limitazioni:

  • L'utente deve disporre dell'autorizzazione per accedere agli oggetti.
  • Un job di query che utilizza le funzioni AI.GENERATE, AI.IF, AI.SCORE o AI.CLASSIFY senza una connessione richiede che l'utente disponga di autorizzazioni aggiuntive. La query può accedere solo a bucket e oggetti Cloud Storage dello stesso progetto in cui viene eseguito il job.

Ad esempio, se chiami la funzione AI.GENERATE su un valore ObjectRef che non ha un autorizzatore, la funzione legge l'oggetto come se fossi tu. Se non hai l'autorizzazione per leggere l'oggetto, la funzione scrive un errore "permission denied" nella colonna status del risultato.

L'esempio seguente mostra una query che utilizza l'accesso diretto:

-- 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")));

Accesso delegato

Con l'accesso delegato, l'utente che esegue la query delega l'accesso all'oggetto a una connessione alla risorsa BigQuery Cloud, specificata nel campo authorizer del valore ObjectRef. L'accesso delegato può consentire l'accesso ai dati tra progetti.

Per utilizzare l'accesso delegato, l'amministratore dei dati deve seguire questi passaggi per configurare la connessione e le autorizzazioni:

Ad esempio, se un utente trasmette valori ObjectRef con un autorizzatore a una funzione AI.GENERATE, la funzione verifica che l'utente disponga dell'autorizzazione bigquery.objectRefs.read e poi legge gli oggetti utilizzando il account di servizio della connessione. Se l'utente o il account di servizio non dispone di autorizzazioni sufficienti, la funzione scrive un errore "permission denied" nella colonna status del risultato.

L'esempio seguente mostra una query che utilizza l'accesso delegato. Richiede quanto segue:

  • L'utente dispone dell'autorizzazione bigquery.objectRefs.read per connection1.
  • Il account di servizio per connection1 dispone dell'autorizzazione storage.objects.get per l'oggetto.
  • Il account di servizio per connection2 ha il ruolo Utente di Agent Platform.
SELECT AI.GENERATE(
  ("Describe this image:",
    OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg", "us.connection1")),
  connection_id => "us.connection2");

All'interno di un perimetro dei Controlli di servizio VPC, le funzioni di AI non possono elaborare i valori ObjectRef che utilizzano l'accesso delegato. L'accesso delegato genera un URL HTTPS firmato per l'oggetto e Gemini Enterprise Agent Platform blocca i recuperi HTTP e HTTPS per i progetti all'interno di un perimetro. La funzione scrive il seguente errore nella colonnastatus del risultato:

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

Poiché la colonna ref di una tabella degli oggetti utilizza sempre la connessione della tabella degli oggetti come autorizzatore, il passaggio di ref a una funzione AI all'interno di un perimetro restituisce sempre questo errore. Per analizzare l'oggetto, passa un valore OBJ.MAKE_REF(uri) con un solo argomento, che utilizza l'accesso diretto e invia l'URI Cloud Storage al modello senza generare un URL firmato.

Best practice

Quando decidi se utilizzare l'accesso diretto o delegato, tieni presente le seguenti best practice:

  • Utilizza l'accesso diretto per un piccolo team che opera in un singolo progetto per l'archiviazione e l'analisi dei dati. L'amministratore dei dati utilizza Identity and Access Management per concedere agli utenti l'accesso ai dati BigQuery e Cloud Storage. Gli utenti possono creare valori ObjectRef on demand senza un autorizzatore per analizzare gli oggetti utilizzando le proprie credenziali.
  • Utilizza l'accesso delegato per un team numeroso che opera su più progetti, soprattutto quando l'archiviazione e l'analisi dei dati sono disaccoppiate. L'amministratore dei dati può configurare le connessioni e creare valori ObjectRef per l'analisi in anticipo con una connessione come autorizzatore. Questo approccio funziona con le tabelle degli oggetti o utilizzando OBJ.MAKE_REF in un elenco di URI. A questo punto, l'amministratore dei dati può condividere la tabella che memorizza i valori di ObjectRef con gli analisti. Gli analisti non devono accedere al bucket originale per analizzare gli oggetti.

Errori

Le funzioni che utilizzano valori ObjectRef segnalano gli errori in due modi:

  • Errore della query: la query potrebbe non riuscire con un messaggio di errore e nessun risultato.
  • Valori di errore restituiti: la query ha esito positivo, ma la funzione potrebbe scrivere gli errori come parte del valore restituito. Per informazioni sul formato del valore restituito, consulta la pagina di riferimento della funzione che stai utilizzando.

Quando una funzione restituisce un valore ObjectRef, il campo details di questo valore potrebbe contenere un campo errors. In questo caso, il valore del campo è un array di errori. Ogni errore ha il seguente schema:

Nome Tipo Modalità Descrizione Esempio
code INT64 REQUIRED Codice di errore HTTP standard. 400
message STRING REQUIRED Un messaggio di errore descrittivo e di facile comprensione. "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 Il nome della funzione che ha attivato l'errore. "OBJ.MAKE_REF"

Questi sono due tipi comuni di errori:

  • Errore oggetto: l'URI o la versione dell'oggetto forniti non esistono.
  • Errore di autorizzazione: la connessione non esiste o l'utente non dispone dell'autorizzazione per utilizzarla per l'accesso delegato.

La seguente query mostra come selezionare i valori ObjectRef che contengono errori da una colonna Objectref:

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

Passaggi successivi