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 Python définies par l'utilisateur.

Schéma

Une valeur ObjectRef comporte les champs suivants :

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 à 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, de la fonction OBJ.LIST 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 conserver une liste de 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'une table 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à des URI stockés dans un tableau 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 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 la fonction OBJ.LIST

Utilisez la fonction OBJ.LIST pour une découverte spontanée. La fonction OBJ.LIST renvoie un tableau de métadonnées et de valeurs ObjectRef pour les fichiers stockés dans Cloud Storage. Les données Cloud Storage peuvent inclure des documents, des images et des fichiers audio.

L'utilisation de OBJ.LIST évite d'avoir à construire manuellement des valeurs ObjectRef dans une table persistante. Vous pouvez rapidement ajouter des objets Cloud Storage à des fonctions d'IA pour créer des pipelines ETL spontanés qui gèrent la conversion de données non structurées en données structurées. Si vous avez besoin d'une table persistante et à mise à jour automatique qui suit en continu les nouveaux objets arrivant dans un bucket au fil du temps, vous devez créer une table d'objets BigQuery standard.

La requête suivante utilise le caractère générique (*) pour découvrir des types de fichiers spécifiques et la fonction AI.IF pour filtrer les données non structurées. Cette requête ne liste que les fichiers PNG contenant une image de chien.

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;

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 soit disposer d'un accès direct à l'objet, soit ajouter un autorisateur au ObjectRef pour utiliser l'accès délégué.

Authorizer 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 n'a pas d'autorisation.

L'accès direct est soumis aux 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 qu'aux buckets et objets Cloud Storage du même projet que celui 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 Agent Platform model.
SELECT AI.GENERATE(
  ("Describe this image:",
  OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg")));

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 aux ressources 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 les étapes ci-dessous pour configurer la connexion et les autorisations :

• Configuration unique : L'administrateur de données doit configurer une connexion aux ressources Cloud pour gérer le bucket Cloud Storage :
  1. Créez une connexion aux ressources Cloud BigQuery ou réutilisez-en une existante dans le projet.
  2. Recherchez le compte de service dans les métadonnées de la connexion.
  3. Accordez au compte de service l'autorisation storage.objects.get pour les lectures ou l'autorisation storage.objects.create pour les écritures, dans le projet ou dans les buckets Cloud Storage. Vous pouvez accorder ces autorisations avec les rôles Lecteur des objets Storage ou Utilisateur des objets Storage.
• Configuration par utilisateur L'administrateur de données doit accorder aux utilisateurs l'autorisation bigquery.objectRefs.read pour les lectures ou l'autorisation bigquery.objectRefs.write pour les écritures sur la connexion BigQuery. Vous pouvez accorder ces autorisations avec les rôles Lecteur ObjectRef BigQuery ou Administrateur ObjectRef BigQuery.

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

Dans un périmètre VPC Service Controls, les fonctions d'IA ne peuvent pas traiter les valeurs ObjectRef qui utilisent l'accès délégué. L'accès délégué génère une URL HTTPS signée pour l'objet, et Gemini Enterprise Agent Platform bloque les récupérations HTTP et HTTPS pour les projets situés dans un périmètre. La fonction écrit l'erreur suivante dans la colonne status du résultat :

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

Étant donné que la colonne ref d'une table d'objets utilise toujours la connexion de la table d'objets comme autorisateur, la transmission de ref à une fonction AI à l'intérieur d'un périmètre renvoie toujours cette erreur. Pour analyser l'objet, transmettez plutôt une valeur OBJ.MAKE_REF(uri) à un seul argument, qui utilise l'accès direct et envoie l'URI Cloud Storage au modèle sans générer d'URL signée.

Bonnes pratiques

Tenez compte des bonnes pratiques suivantes lorsque vous décidez d'utiliser un 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 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 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 générer un message d'erreur sans 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 présente le schéma suivant :

Voici deux types d'erreurs courantes :

• 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

• Spécifier des colonnes ObjectRef dans des schémas de table.
• Analysez les données multimodales.
• En savoir plus sur les fonctions ObjectRef