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. Se puede procesar con funciones de OBJ, funciones de IA o funciones definidas por el usuario de Python.

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 La generación del objeto. "1560286006357632"
authorizer STRING NULLABLE 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 Los metadatos del objeto o los errores que se produjeron durante el 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 a partir del sufijo del URI.

Crea valores ObjectRef

Puedes crear valores ObjectRef con tablas de objetos, la función OBJ.MAKE_REF, la función OBJ.LIST o los 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 quieres conservar una lista de 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. En la siguiente consulta, se usa la declaración CREATE EXTERNAL TABLE 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 función OBJ.MAKE_REF si ya tienes URIs almacenados en una tabla y quieres crear valores ObjectRef 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 los 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 que puede ser nulo para admitir el acceso directo y el acceso delegado.

Usa la función OBJ.LIST

Usa la función OBJ.LIST para el descubrimiento espontáneo. La función OBJ.LIST devuelve una tabla de metadatos y valores ObjectRef para los archivos almacenados en Cloud Storage. Los datos de Cloud Storage pueden incluir documentos, imágenes y audio.

El uso de OBJ.LIST reemplaza la necesidad de construir manualmente valores ObjectRef en una tabla persistente. Puedes agregar objetos de Cloud Storage a las funciones de IA con rapidez para crear canalizaciones de ETL espontáneas que se encarguen de convertir datos no estructurados en datos estructurados. Si necesitas una tabla persistente que se actualice automáticamente y que realice un seguimiento continuo de los objetos nuevos que llegan a un bucket con el tiempo, debes crear una tabla de objetos de BigQuery estándar.

En la siguiente consulta, se usa el carácter comodín (*) para descubrir tipos de archivos específicos y la función AI.IF para filtrar datos no estructurados. Esta consulta solo muestra los archivos PNG que contienen una imagen de un perro.

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;

Usa conjuntos de datos de Cloud Storage Insights

Si tienes un conjunto de datos de Storage Insights configurado, este ya incluye una columna ref que contiene valores ObjectRef. Los valores ObjectRef que se crean en los 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 ObjectRef para usar el acceso delegado.

Autorizador y permisos

Cuando pasas un valor ObjectRef a funciones 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 use las funciones AI.GENERATE, AI.IF, AI.SCORE o AI.CLASSIFY 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 leerá el objeto como tú. Si no tienes permiso para leer el objeto, la función escribe un error "permission denied" en la columna status del resultado.

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

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

Acceso delegado

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

Para usar el acceso delegado, tu 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 status del resultado.

En el siguiente ejemplo, se muestra una consulta que usa el acceso delegado. Se 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 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");

Dentro de un perímetro de Controles del servicio de VPC, las funciones de IA no pueden procesar valores de ObjectRef que usen acceso delegado. El acceso delegado genera una URL HTTPS firmada para el objeto, y las URLs firmadas no pueden cruzar los límites del perímetro. La función escribe uno de los siguientes errores en la columna status del resultado:

  • INVALID_ARGUMENT: HTTP links are not supported for requests restricted by VPCSC. Este error se produce si tu perímetro restringe Agent Platform.
  • Cannot fetch content from the provided URL Este error se produce si tu perímetro restringe Cloud Storage.

Debido a que la columna ref de una tabla de objetos siempre usa la conexión de la tabla de objetos como autorizador, pasar ref a una función de IA dentro de un perímetro siempre devuelve este error. Para analizar el objeto, pasa un solo valor de argumento OBJ.MAKE_REF(uri), que usa el acceso directo y envía el URI de Cloud Storage al modelo sin generar una URL firmada.

Prácticas recomendadas

Ten en cuenta las siguientes prácticas recomendadas cuando decidas si usar el 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 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 almacén de datos y el análisis están separados. El administrador de datos puede configurar conexiones y crear valores de 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. Debido a que el acceso delegado otorga acceso a todos los objetos a los que puede acceder la cuenta de servicio de la conexión, independientemente de las políticas de acceso a nivel de fila en las tablas de objetos o las tablas estándar, define el alcance de los permisos de Cloud Storage de cada conexión solo para los buckets o las carpetas administradas a los que sus usuarios tienen autorización para acceder.

Errores

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

  • Falla de la consulta: Es posible que la consulta falle con un mensaje de error y sin resultados.
  • Valores de error mostrados: 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 devuelve un valor ObjectRef, el campo details de ese valor puede contener un campo errors. Si es así, 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 Código de error de HTTP estándar. 400
message STRING REQUIRED 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 de errores comunes:

  • 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?