Utilizzare i valori ObjectRef

Questo documento descrive i valori 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 OBJ funzioni, 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 di connessione BigQuery per l'accesso delegato o NULL per l'accesso diretto. L'ID può avere i seguenti formati:
"region.connection"
or
"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 contenuti di un oggetto in Cloud Storage. Se lo ometti in Cloud Storage, BigQuery deduce il tipo di contenuti dal suffisso dell'URI.

Creare valori ObjectRef

Puoi creare valori ObjectRef utilizzando tabelle di oggetti, la OBJ.MAKE_REF funzione, o set di dati di Storage Insights.

Utilizzare le tabelle di oggetti

Utilizza una tabella di oggetti se non hai URI archiviati in una tabella e vuoi elencare tutti gli oggetti da un prefisso Cloud Storage. Una tabella di oggetti archivia il riferimento a un oggetto in ogni riga e ha una colonna ref che contiene valori ObjectRef. La seguente query utilizza l' CREATE EXTERNAL TABLE istruzione 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 connessione che utilizzi per creare la tabella di oggetti.

Utilizzare la funzione OBJ.MAKE_REF

Utilizza la OBJ.MAKE_REF funzione se hai già URI archiviati in una tabella e vuoi creare ObjectRef valori da questi URI. Le seguenti query mostrano come creare valori ObjectRef nella colonna image_ref dalla colonna uri che contiene gli URI di 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 autorizzatori 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 i set di dati di Storage Insights

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

Autorizzatore e autorizzazioni

Quando passi un valore ObjectRef a funzioni ObjectRef, funzioni AI o 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 avere l'autorizzazione per accedere agli oggetti.
  • Un job di query che utilizza le AI.GENERATE, AI.IF, AI.SCORE o AI.CLASSIFY funzioni senza una connessione richiede che l'utente disponga di autorizzazioni aggiuntive. La query può accedere solo ai bucket e agli 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 "permission denied" errore nella status colonna del risultato.

Il seguente esempio 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 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')));

Accesso delegato

Con accesso delegato, l'utente che esegue la query delega l'accesso all'oggetto a una connessione alle risorse Cloud di BigQuery, 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 passa 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 dispongono di autorizzazioni sufficienti, la funzione scrive un errore "permission denied" nella colonna status del risultato.

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

  • L'utente ha l'autorizzazione bigquery.objectRefs.read su connection1.
  • Il account di servizio per connection1 ha l'autorizzazione storage.objects.get sull'oggetto.
  • Il account di servizio per connection2 ha il ruolo Utente Vertex AI.
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 practice

Prendi in esame queste best practice quando decidi se utilizzare l'accesso diretto o delegato:

  • Utilizza l'accesso diretto per un piccolo team che opera in un singolo progetto sia per l'archiviazione che per l'analisi dei dati. L'amministratore dei dati utilizza Identity and Access Management per concedere agli utenti l'accesso ai dati BigQuery e ai dati di 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 di grandi dimensioni 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 in anticipo valori ObjectRef per l'analisi con una connessione come autorizzatore. Questo approccio funziona con le tabelle di oggetti o utilizzando OBJ.MAKE_REF su un elenco di URI. L'amministratore dei dati può quindi condividere la tabella che memorizza i valori ObjectRef con gli analisti. Gli analisti non devono accedere al bucket originale per analizzare gli oggetti.

Errori

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

  • Errore di 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 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 di questo 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 utilizzo. "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 dell'oggetto: l'URI o la versione dell'oggetto forniti non esistono.
  • Errore dell'autorizzatore: la connessione non esiste o l'utente non ha l'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