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 fait référence aux objets Cloud Storage pour l'analyse multimodale. Il peut être traité par des fonctions OBJ, des fonctions d'IA ou des fonctions définies par l'utilisateur Python.

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 Un 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 récupéré depuis 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 à partir 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 fonction OBJ.MAKE_REF ou des 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és dans une table et que vous souhaitez lister tous les objets 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'instruction CREATE EXTERNAL TABLE 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'un tableau d'objets doivent disposer d'un autorisateur pour l'accès délégué. La connexion de l'autorisation est la même que celle que vous utilisez pour créer la table d'objets.

Utiliser la fonction OBJ.MAKE_REF

Utilisez la fonction OBJ.MAKE_REF si vous avez déjà stocké des URI dans une table et que vous souhaitez créer des valeurs ObjectRef à 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 qui contient 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 les ensembles de données Cloud Storage Insights

Si vous avez configuré un ensemble de données Storage Insights, il inclut déjà une colonne ref contenant des valeurs ObjectRef. Les valeurs ObjectRef créées dans les ensembles de données Storage Insights n'ont pas d'autorisation. Pour interroger ces objets, vous devez disposer d'un accès direct à l'objet ou ajouter un autorisateur au 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 UDF Python, 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 en utilisant ses propres identifiants. L'accès direct est utilisé lorsque la valeur ObjectRef ne comporte aucun autorisateur.

L'accès direct présente les restrictions suivantes :

  • L'utilisateur doit être autorisé à accéder aux objets.
  • Un job de requête utilisant les fonctions AI.GENERATE, AI.IF, AI.SCORE ou AI.CLASSIFY sans connexion nécessite que l'utilisateur dispose d'autorisations supplémentaires. La requête ne peut accéder aux buckets et objets Cloud Storage que du même projet dans lequel le job est exécuté.

Par exemple, si vous appelez la fonction AI.GENERATE sur une valeur ObjectRef qui n'a pas d'autorisation, la fonction lit l'objet en votre nom. Si vous n'êtes pas autorisé à lire l'objet, 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 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.GET_ACCESS_URL(OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg"), 'r')));

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 aux objets à une connexion à une ressource cloud BigQuery, qui est spécifiée dans le champ authorizer de la valeur ObjectRef. L'accès délégué peut permettre d'accéder aux données de plusieurs projets.

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

Par exemple, si un utilisateur transmet des valeurs ObjectRef qui disposent d'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é. Pour ce faire, vous devez disposer des éléments suivants :

  • L'utilisateur dispose de l'autorisation bigquery.objectRefs.read sur connection1.
  • Le compte de service pour connection1 dispose de l'autorisation storage.objects.get sur l'objet.
  • Le compte de service pour connection2 dispose du rôle Utilisateur 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");

Bonnes pratiques

Tenez compte des bonnes pratiques suivantes lorsque vous décidez d'utiliser l'accès direct ou 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 de données utilise Identity and Access Management pour accorder aux utilisateurs l'accès aux données BigQuery et Cloud Storage. Les utilisateurs peuvent créer des valeurs ObjectRef à la demande sans autorisation 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 de données peut configurer des connexions et créer des valeurs ObjectRef pour l'analyse à l'avance, en utilisant une connexion comme autorisation. Cette approche fonctionne avec les tables d'objets ou en utilisant OBJ.MAKE_REF sur une liste d'URI. L'administrateur de données peut ensuite partager avec les analystes le tableau stockant les valeurs ObjectRef. 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 et afficher un message d'erreur sans résultat.
  • Valeurs d'erreur renvoyées : la requête aboutit, 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 présente 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 facile à comprendre. "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 fournis n'existent pas.
  • Erreur de l'autorisation : 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 les valeurs ObjectRef qui contiennent des erreurs à partir d'une colonne Objectref :

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

Étapes suivantes