Trabaja con valores de ObjectRef

En este documento, se describen los valores ObjectRef y cómo crearlos y usarlos en BigQuery.

Un valor ObjectRef es un tipo STRUCT con un esquema predefinido que hace referencia a objetos de Cloud Storage para el análisis multimodal. Las funciones OBJlas funciones de IA o las funciones definidas por el usuario de Python pueden procesarlo.

Esquema

Un valor ObjectRef tiene los siguientes campos:

Nombre Tipo Modo Descripción Ejemplo
uri STRING REQUIRED Es el URI del objeto de Cloud Storage. "gs://cloud-samples-data/vision/demo-img.jpg"
version STRING NULLABLE Es la generación del objeto. "1560286006357632"
authorizer STRING NULLABLE Es un ID de conexión de BigQuery para el acceso delegado o NULL para el acceso directo. El ID puede tener los siguientes formatos:
"region.connection"
o
"project.region.connection"		 "myproject.us.myconnection"
details JSON NULLABLE Son los metadatos del objeto o los errores del procesamiento del objeto. Puede incluir los campos content_type, md5_hash, size y updated para el objeto. {"gcs_metadata":{"content_type":"image/png","md5_hash":"dfbbb5cf034af026d89f2dc16930be15","size":915052,"updated":1560286006000000}}

El campo content_type en el campo gcs_metadata de la columna details se recupera de Cloud Storage. Puedes establecer el tipo de contenido de un objeto en Cloud Storage. Si lo omites en Cloud Storage, BigQuery infiere el tipo de contenido del sufijo del URI.

Crea valores ObjectRef

Puedes crear valores ObjectRef con tablas de objetos, la OBJ.MAKE_REF función, o conjuntos de datos de Cloud Storage Insights.

Usa tablas de objetos

Usa una tabla de objetos si no tienes URIs almacenados en una tabla y deseas enumerar todos los objetos de un prefijo de Cloud Storage. Una tabla de objetos almacena la referencia a un objeto en cada fila y tiene una columna ref que contiene valores ObjectRef. La siguiente consulta usa la CREATE EXTERNAL TABLE instrucción para crear una tabla de objetos:

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;

Los valores ObjectRef de una tabla de objetos deben tener un autorizador para el acceso delegado. La conexión del autorizador es la misma que usas para crear la tabla de objetos.

Usa la función OBJ.MAKE_REF

Usa la OBJ.MAKE_REF función si ya tienes URIs almacenados en una tabla y deseas crear ObjectRef valores a partir de esos URIs. En las siguientes consultas, se muestra cómo crear valores ObjectRef en la columna image_ref a partir de la columna uri que contiene URIs de 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;

Para modificar los autorizadores de un valor ObjectRef existente, puedes usar la función 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 función OBJ.MAKE_REF acepta un autorizador anulable para admitir el acceso directo y el acceso delegado.

Usa conjuntos de datos de Cloud Storage Insights

Si tienes configurado un conjunto de datos de Storage Insights, el conjunto de datos ya incluye una ref columna que contiene ObjectRef valores. Los valores ObjectRef creados en conjuntos de datos de Storage Insights no tienen un autorizador. Para consultar estos objetos, debes tener acceso directo al objeto o agregar un autorizador a la ObjectRef para usar acceso delegado.

Autorizador y permisos

Cuando pasas un valor ObjectRef a funciones de ObjectRef, funciones de IA o UDF de Python, esas funciones deben acceder al objeto almacenado en Cloud Storage. Puedes autorizar este acceso según el valor del campo authorizer de dos maneras: acceso directo y acceso delegado.

Acceso directo

Con el acceso directo, el usuario que ejecuta la consulta accede al objeto directamente con sus propias credenciales. El acceso directo se usa cuando el valor ObjectRef no tiene autorizador.

El acceso directo tiene las siguientes restricciones:

  • El usuario debe tener permiso para acceder a los objetos.
  • Un trabajo de consulta que usa las AI.GENERATE, AI.IF, AI.SCOREo AI.CLASSIFY funciones sin una conexión requiere que el usuario tenga permisos adicionales. La consulta solo puede acceder a los buckets y objetos de Cloud Storage del mismo proyecto en el que se ejecuta el trabajo.

Por ejemplo, si llamas a la función AI.GENERATE en un valor ObjectRef que no tiene un autorizador, la función lee el objeto como tú. Si no tienes permiso para leer el objeto, la función escribe un "permission denied" error en la status columna del resultado.

En el siguiente ejemplo, se muestra una consulta que usa acceso directo:

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

Acceso delegado

Con el acceso delegado, el usuario que ejecuta la consulta delega el acceso a objetos a una conexión de recursos de Cloud de BigQuery, que se especifica en el campo authorizer del valor ObjectRef. El acceso delegado puede habilitar el acceso a datos de varios proyectos.

Para usar el acceso delegado, el administrador de datos debe seguir estos pasos para configurar la conexión y los permisos:

Por ejemplo, si un usuario pasa valores ObjectRef que tienen un autorizador a una función AI.GENERATE, la función verifica que el usuario tenga el permiso bigquery.objectRefs.read y, luego, lee los objetos con la cuenta de servicio de la conexión. Si el usuario o la cuenta de servicio no tienen permisos suficientes, la función escribe un error "permission denied"en la columna statusdel resultado.

En el siguiente ejemplo, se muestra una consulta que usa acceso delegado. Requiere lo siguiente:

  • El usuario tiene el permiso bigquery.objectRefs.read en connection1.
  • La cuenta de servicio de connection1 tiene el permiso storage.objects.get en el objeto.
  • La cuenta de servicio de connection2 tiene el rol de usuario de 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");

Prácticas recomendadas

Ten en cuenta las siguientes prácticas recomendadas cuando decidas si usar acceso directo o delegado:

  • Usa el acceso directo para un equipo pequeño que opera en un solo proyecto para el almacenamiento y el análisis de datos. El administrador de datos usa Identity and Access Management para otorgar a los usuarios acceso a los datos de BigQuery y a los datos de Cloud Storage. Los usuarios pueden crear valores ObjectRef a pedido sin un autorizador para analizar objetos con sus propias credenciales.
  • Usa el acceso delegado para un equipo grande que opera en varios proyectos, en especial cuando el almacenamiento y el análisis de datos están separados. El administrador de datos puede configurar conexiones y crear valores ObjectRef para el análisis con anticipación con una conexión como su autorizador. Este enfoque funciona con tablas de objetos o con OBJ.MAKE_REF en una lista de URIs. Luego, el administrador de datos puede compartir la tabla que almacena los valores ObjectRef con los analistas. Los analistas no necesitan acceder al bucket original para analizar los objetos.

Errores

Las funciones que consumen valores ObjectRef informan errores de dos maneras:

  • Falla de la consulta: La consulta puede fallar con un mensaje de error y sin resultado.
  • Valores de error que se muestran: La consulta se realiza correctamente, pero la función puede escribir errores como parte del valor que se muestra. Para obtener información sobre el formato del valor que se muestra, consulta la página de referencia de la función que usas.

Cuando una función muestra un valor ObjectRef, el campo details de ese valor puede contener un campo errors. Si lo hace, el valor de ese campo es un array de errores. Cada error tiene el siguiente esquema:

Nombre Tipo Modo Descripción Ejemplo
code INT64 REQUIRED Es el código de error HTTP estándar. 400
message STRING REQUIRED Es un mensaje de error descriptivo y fácil de usar. "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 Es el nombre de la función que activó el error. "OBJ.MAKE_REF"

Estos son dos tipos comunes de errores:

  • Error de objeto: El URI o la versión del objeto proporcionados no existen.
  • Error del autorizador: La conexión no existe o el usuario no tiene permiso para usarla para el acceso delegado.

En la siguiente consulta, se muestra cómo seleccionar valores ObjectRef que contienen errores de una columna Objectref:

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

¿Qué sigue?