Utiliser des valeurs ObjectRef

Ce document décrit les valeurs ObjectRef, ainsi que la façon de les créer et de 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. Elles peuvent être traitées par des fonctions OBJ, des fonctions AI ou des 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 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é à partir 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 fonction OBJ.MAKE_REF, de la fonction OBJ.LIST 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é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 qui contient 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'auteur 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 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 nullable 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 une table 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 remplace la nécessité de construire manuellement des valeurs ObjectRef dans une table permanente. Vous pouvez rapidement ajouter des objets Cloud Storage aux fonctions 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 qui se met à jour automatiquement et qui suit en continu les nouveaux objets qui arrivent 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 l'image d'un 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, 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 n'ont 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 AI 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 : l'accès direct et l'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 n'a pas d'autorisateur.

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 projet dans lequel la tâche est exécutée.

Par exemple, si vous appelez la fonction AI.GENERATE sur une valeur ObjectRef qui n'a pas d'autorisateur, la fonction lit l'objet en tant que vous. 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 l'accès aux données entre 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 disposant 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 de 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 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 les URL signées ne peuvent pas franchir les limites du périmètre. La fonction écrit l'une des erreurs suivantes dans la colonne status du résultat :

  • INVALID_ARGUMENT: HTTP links are not supported for requests restricted by VPCSC. Cette erreur se produit si votre périmètre limite Agent Platform.
  • Cannot fetch content from the provided URL Cette erreur se produit si votre périmètre limite Cloud Storage.

Étant donné que la colonne ref d'une table d'objets utilise toujours la connexion de la table d'objets comme autorisateur, transmettre ref à une fonction AI dans un périmètre renvoie toujours cette erreur. Pour analyser l'objet, transmettez plutôt une seule valeur d'argument OBJ.MAKE_REF(uri), 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 l'accès direct ou délégué :

  • Utilisez l'accès direct pour une petite équipe opérant dans 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 autorisateur pour analyser des objets à l'aide de leurs propres identifiants.
  • Utilisez l'accès délégué pour une grande équipe opérant 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 autorisateur. 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 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. Étant donné que l'accès délégué accorde l'accès à tous les objets auxquels le compte de service de la connexion peut accéder, quelles que soient les stratégies d'accès au niveau des lignes sur les tables d'objets ou les tables standards, limitez les autorisations Cloud Storage de chaque connexion aux buckets ou aux dossiers gérés auxquels ses utilisateurs sont autorisés à accéder.

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 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 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 fournis n'existent pas.
  • Erreur de l'outil d'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 des valeurs ObjectRef contenant des erreurs dans une colonne Objectref :

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

Étapes suivantes