Utiliser des valeurs ObjectRef

Ce document décrit les valeurs ObjectRef et explique comment les créer et les utiliser dans BigQuery.

Une valeur ObjectRef est un type STRUCT avec un schéma prédéfini qui référence des objets Cloud Storage pour l'analyse multimodale. Elle peut être traitée par OBJ fonctions, fonctions d'IA, ou fonctions Python définies par l'utilisateur.

Schéma

Une valeur ObjectRef comporte les champs suivants :

Nom Type Mode Description Exemple
uri STRING REQUIRED URI de l'objet Cloud Storage. "gs://cloud-samples-data/vision/demo-img.jpg"
version STRING NULLABLE Génération de l'objet. "1560286006357632"
authorizer STRING NULLABLE ID de connexion BigQuery pour l'accès délégué ou NULL pour l'accès direct. L'ID peut avoir les formats suivants :
"region.connection"
ou
"project.region.connection"		 "myproject.us.myconnection"
details JSON NULLABLE Métadonnées de l'objet ou erreurs liées au traitement de l'objet. Il peut inclure les champs content_type, md5_hash, size et updated pour l'objet. {"gcs_metadata":{"content_type":"image/png","md5_hash":"dfbbb5cf034af026d89f2dc16930be15","size":915052,"updated":1560286006000000}}

Le champ content_type du champ gcs_metadata de la colonne details est extrait de Cloud Storage. Vous pouvez définir le type de contenu d'un objet dans Cloud Storage. Si vous l'omettez dans Cloud Storage, BigQuery déduit le type de contenu du suffixe de l'URI.

Créer des valeurs ObjectRef

Vous pouvez créer des valeurs ObjectRef à l'aide de tables d'objets, de la OBJ.MAKE_REF fonction, ou d'ensembles de données Cloud Storage Insights.

Utiliser des tables d'objets

Utilisez une table d'objets si vous n'avez pas d'URI stockées dans une table et que vous souhaitez répertorier tous les objets à partir d'un préfixe Cloud Storage. Une table d'objets stocke la référence à un objet dans chaque ligne et comporte une colonne ref contenant des valeurs ObjectRef. La requête suivante utilise l' CREATE EXTERNAL TABLE instruction pour créer une table d'objets :

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;

Les valeurs ObjectRef d'une table d'objets doivent disposer d'un autorisateur pour l'accès délégué. La connexion de l'autorisateur est la même que celle que vous utilisez pour créer la table d'objets.

Utiliser la fonction OBJ.MAKE_REF

Utilisez la OBJ.MAKE_REF fonction si vous avez déjà des URI stockées dans une table et que vous souhaitez créer ObjectRef valeurs à partir de ces URI. Les requêtes suivantes montrent comment créer des valeurs ObjectRef dans la colonne image_ref à partir de la colonne uri contenant des 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;

Pour modifier les autorisateurs d'une valeur ObjectRef existante, vous pouvez utiliser la fonction 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 fonction OBJ.MAKE_REF accepte un autorisateur pouvant être nul pour prendre en charge l’accès direct et l’accès délégué.

Utiliser des ensembles de données Cloud Storage Insights

Si vous avez configuré un ensemble de données Storage Insights, celui-ci inclut déjà une colonne ref contenant des valeurs ObjectRef. Les valeurs ObjectRef créées dans les ensembles de données Storage Insights ne disposent pas d'autorisateur. Pour interroger ces objets, vous devez disposer d'un accès direct à l'objet ou ajouter un autorisateur à ObjectRef pour utiliser l'accès délégué.

Autorisateur et autorisations

Lorsque vous transmettez une valeur ObjectRef à des fonctions ObjectRef, des fonctions d'IA ou des fonctions Python définies par l'utilisateur, ces fonctions doivent accéder à l'objet stocké dans Cloud Storage. Vous pouvez autoriser cet accès en fonction de la valeur du champ authorizer de deux manières : accès direct et accès délégué.

Accès direct

Avec l'accès direct, l'utilisateur qui exécute la requête accède directement à l'objet à l'aide de ses propres identifiants. L'accès direct est utilisé lorsque la valeur ObjectRef ne comporte pas d'autorisateur.

L'accès direct est soumis aux restrictions suivantes :

  • L'utilisateur doit disposer de l'autorisation d'accéder aux objets.
  • Une tâche de requête utilisant les AI.GENERATE, AI.IF, AI.SCORE, ou AI.CLASSIFY fonctions sans connexion nécessite que l'utilisateur dispose d' autorisations supplémentaires. La requête ne peut accéder qu'aux buckets et objets Cloud Storage du même projet dans lequel la tâche est exécutée.

Par exemple, si vous appelez la fonction AI.GENERATE sur une valeur ObjectRef qui ne comporte pas d'autorisateur, la fonction lit l'objet comme vous. Si vous n'êtes pas autorisé à lire l'objet, la fonction écrit une "permission denied" erreur dans la colonne status du résultat.

L'exemple suivant montre une requête qui utilise l'accès direct :

-- 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.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg")),
  endpoint => 'gemini-2.5-pro');

Accès délégué

Avec l'accès délégué, l'utilisateur qui exécute la requête délègue l'accès à l'objet à une connexion de ressource Cloud BigQuery, spécifiée dans le champ authorizer de la valeur ObjectRef. L'accès délégué peut permettre l'accès aux données inter-projets.

Pour utiliser l'accès délégué, l'administrateur de vos données doit suivre ces étapes pour configurer la connexion et les autorisations :

Par exemple, si un utilisateur transmet des valeurs ObjectRef comportant un autorisateur à une fonction AI.GENERATE, la fonction vérifie que l'utilisateur dispose de l'autorisation bigquery.objectRefs.read, puis lit les objets à l'aide du compte de service de la connexion. Si l'utilisateur ou le compte de service ne dispose pas des autorisations suffisantes, la fonction écrit une erreur "permission denied" dans la colonne status du résultat.

L'exemple suivant montre une requête qui utilise l'accès délégué. Elle nécessite les éléments suivants :

  • L'utilisateur dispose de l'autorisation bigquery.objectRefs.read sur connection1.
  • Le compte de service de connection1 dispose de l'autorisation storage.objects.get sur l'objet.
  • Le compte de service de connection2 dispose du rôle Utilisateur de l'Agent Platform.
SELECT AI.GENERATE(
  ("Describe this image:",
    OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg", "us.connection1")),
  endpoint => 'gemini-2.5-pro',
  connection_id => "us.connection2");

Bonnes pratiques

Tenez compte des bonnes pratiques suivantes lorsque vous décidez d'utiliser l'accès direct ou l'accès délégué :

  • Utilisez l'accès direct pour une petite équipe travaillant sur un seul projet pour le stockage et l'analyse des données. L'administrateur des données utilise Identity and Access Management pour accorder aux utilisateurs l'accès aux données BigQuery et aux données Cloud Storage. Les utilisateurs peuvent créer des valeurs ObjectRef à la demande sans autorisateur pour analyser les objets à l'aide de leurs propres identifiants.
  • Utilisez l'accès délégué pour une grande équipe travaillant sur plusieurs projets, en particulier lorsque le stockage et l'analyse des données sont dissociés. L'administrateur des données peut configurer des connexions et créer des valeurs ObjectRef pour l'analyse à l'avance avec une connexion comme autorisateur. Cette approche fonctionne avec les tables d'objets ou en utilisant OBJ.MAKE_REF sur une liste d'URI. L'administrateur des données peut ensuite partager la table stockant les valeurs ObjectRef avec les analystes. Les analystes n'ont pas besoin d'accéder au bucket d'origine pour analyser les objets.

Erreurs

Les fonctions qui utilisent des valeurs ObjectRef signalent les erreurs de deux manières :

  • Échec de la requête : la requête peut échouer avec un message d'erreur et aucun résultat.
  • Valeurs d'erreur renvoyées : la requête réussit, mais la fonction peut écrire des erreurs dans la valeur renvoyée. Pour en savoir plus sur le format de la valeur renvoyée, consultez la page de référence de la fonction que vous utilisez.

Lorsqu'une fonction renvoie une valeur ObjectRef, le champ details de cette valeur peut contenir un champ errors. Si c'est le cas, la valeur de ce champ est un tableau d'erreurs. Chaque erreur a le schéma suivant :

Nom Type Mode Description Exemple
code INT64 REQUIRED Code d'erreur HTTP standard. 400
message STRING REQUIRED Message d'erreur descriptif et convivial. "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 Nom de la fonction qui a déclenché l'erreur. "OBJ.MAKE_REF"

Voici deux types d'erreurs courants :

  • Erreur d'objet : l'URI ou la version de l'objet fourni n'existe pas.
  • Erreur d'autorisateur : la connexion n'existe pas ou l'utilisateur n'est pas autorisé à l'utiliser pour l'accès délégué.

La requête suivante montre comment sélectionner ObjectRef valeurs qui contiennent des erreurs à partir d'une colonne Objectref:

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

Étape suivante