Trabalhar com valores ObjectRef

Neste documento, descrevemos os valores de ObjectRef e como criá-los e usá-los no BigQuery.

Um valor ObjectRef é um tipo STRUCT com um esquema predefinido que faz referência a objetos do Cloud Storage para análise multimodal. Ele pode ser processado por funções OBJ, funções de IA ou funções definidas pelo usuário em Python.

Esquema

Um valor ObjectRef tem os seguintes campos:

Nome Tipo Modo Descrição Exemplo
uri STRING REQUIRED O URI do objeto do Cloud Storage. "gs://cloud-samples-data/vision/demo-img.jpg"
version STRING NULLABLE A geração de objetos. "1560286006357632"
authorizer STRING NULLABLE Um ID de conexão do BigQuery para acesso delegado ou NULL para acesso direto. O ID pode ter os seguintes formatos:
"region.connection"
ou
"project.region.connection"		 "myproject.us.myconnection"
details JSON NULLABLE Os metadados do objeto ou erros no processamento dele. Ele pode incluir os campos content_type, md5_hash, size e updated para o objeto. {"gcs_metadata":{"content_type":"image/png","md5_hash":"dfbbb5cf034af026d89f2dc16930be15","size":915052,"updated":1560286006000000}}

O campo content_type no campo gcs_metadata da coluna details é buscado no Cloud Storage. É possível definir o tipo de conteúdo de um objeto no Cloud Storage. Se você omitir esse campo no Cloud Storage, o BigQuery vai inferir o tipo de conteúdo pelo sufixo do URI.

Criar valores ObjectRef

É possível criar valores ObjectRef usando tabelas de objetos, a função OBJ.MAKE_REF, a função OBJ.LIST ou conjuntos de dados do Cloud Storage Insights.

Usar tabelas de objetos

Use uma tabela de objetos se você não tiver URIs armazenados em uma tabela e quiser manter uma lista de todos os objetos de um prefixo do Cloud Storage. Uma tabela de objetos armazena a referência a um objeto em cada linha e tem uma coluna ref que contém valores ObjectRef. A consulta a seguir usa a instrução CREATE EXTERNAL TABLE para criar uma tabela 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;

Os valores de ObjectRef de uma tabela de objetos precisam ter um autorizador para acesso delegado. A conexão do autorizador é a mesma que você usa para criar a tabela de objetos.

Usar a função OBJ.MAKE_REF

Use a função OBJ.MAKE_REF se você já tiver URIs armazenados em uma tabela e quiser criar valores ObjectRef com base nesses URIs. As consultas a seguir mostram como criar valores ObjectRef na coluna image_ref da coluna uri que contém URIs do 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 os autorizadores de um valor ObjectRef, use a função 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;

A função OBJ.MAKE_REF aceita um autorizador anulável para oferecer suporte a acesso direto e acesso delegado.

Usar a função OBJ.LIST

Use a função OBJ.LIST para descobertas espontâneas. A função OBJ.LIST retorna uma tabela de metadados e valores ObjectRef para arquivos armazenados no Cloud Storage. Os dados do Cloud Storage podem incluir documentos, imagens e áudio.

Usar OBJ.LIST elimina a necessidade de construir manualmente valores ObjectRef em uma tabela persistente. É possível adicionar rapidamente objetos do Cloud Storage a funções de IA para criar pipelines de ETL espontâneos que convertem dados não estruturados em dados estruturados. Se você precisar de uma tabela persistente e autossuficiente que rastreie continuamente novos objetos que chegam a um bucket ao longo do tempo, crie uma tabela de objetos padrão do BigQuery.

A consulta a seguir usa o caractere curinga (*) para descobrir tipos de arquivo específicos e a função AI.IF para filtrar dados não estruturados. Essa consulta lista apenas os arquivos PNG que contêm uma imagem de um cachorro.

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;

Usar conjuntos de dados do Cloud Storage Insights

Se você tiver um conjunto de dados do Storage Insights configurado, ele já vai incluir uma coluna ref que contém valores ObjectRef. Os valores ObjectRef criados em conjuntos de dados do Storage Insights não têm uma autorização. Para consultar esses objetos, você precisa ter acesso direto a eles ou adicionar um autorizador ao ObjectRef para usar o acesso delegado.

Autorizador e permissões

Quando você transmite um valor ObjectRef para funções ObjectRef, funções de IA ou UDFs do Python, essas funções precisam acessar o objeto armazenado no Cloud Storage. Você pode autorizar esse acesso com base no valor do campo authorizer de duas maneiras: acesso direto e acesso delegado.

Acesso direto

Com o acesso direto, o usuário que executa a consulta acessa o objeto diretamente usando as próprias credenciais. O acesso direto é usado quando o valor ObjectRef não tem autorizador.

O acesso direto tem as seguintes restrições:

  • O usuário precisa ter permissão para acessar os objetos.
  • Um trabalho de consulta que usa as funções AI.GENERATE, AI.IF, AI.SCORE ou AI.CLASSIFY sem uma conexão exige que o usuário tenha permissões adicionais. A consulta só pode acessar buckets e objetos do Cloud Storage do mesmo projeto em que o job é executado.

Por exemplo, se você chamar a função AI.GENERATE em um valor ObjectRef que não tem um autorizador, a função vai ler o objeto como se fosse você. Se você não tiver permissão para ler o objeto, a função vai gravar um erro "permission denied" na coluna status do resultado.

O exemplo a seguir mostra uma consulta que usa acesso direto:

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

Acesso delegado

Com o acesso delegado, o usuário que executa a consulta delega o acesso ao objeto a uma conexão a recursos do Cloud do BigQuery, que é especificada no campo authorizer do valor ObjectRef. O acesso delegado pode permitir o acesso aos dados entre projetos.

Para usar o acesso delegado, o administrador de dados precisa seguir estas etapas para configurar a conexão e as permissões:

Por exemplo, se um usuário transmitir valores ObjectRef que têm um autorizador para uma função AI.GENERATE, a função vai verificar se o usuário tem a permissão bigquery.objectRefs.read e ler os objetos usando a conta de serviço da conexão. Se o usuário ou a conta de serviço não tiver permissões suficientes, a função vai gravar um erro "permission denied" na coluna status do resultado.

O exemplo a seguir mostra uma consulta que usa acesso delegado. Ele exige o seguinte:

  • O usuário tem a permissão bigquery.objectRefs.read em connection1.
  • A conta de serviço de connection1 tem a permissão storage.objects.get no objeto.
  • A conta de serviço de connection2 tem o papel de usuário da 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");

Em um perímetro do VPC Service Controls, as funções de IA não podem processar valores ObjectRef que usam acesso delegado. O acesso delegado gera um URL HTTPS assinado para o objeto, e a Gemini Enterprise Agent Platform bloqueia buscas HTTP e HTTPS para projetos dentro de um perímetro. A função grava o seguinte erro na coluna status do resultado:

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

Como a coluna ref de uma tabela de objetos sempre usa a conexão da tabela de objetos como autorizador, transmitir ref para uma função de IA dentro de um perímetro sempre retorna esse erro. Para analisar o objeto, transmita um valor OBJ.MAKE_REF(uri) de argumento único, que usa acesso direto e envia o URI do Cloud Storage para o modelo sem gerar um URL assinado.

Práticas recomendadas

Considere as seguintes práticas recomendadas ao decidir se vai usar acesso direto ou delegado:

  • Use o acesso direto para uma equipe pequena que trabalha em um único projeto para armazenamento e análise de dados. O administrador de dados usa o Identity and Access Management para conceder aos usuários acesso aos dados do BigQuery e do Cloud Storage. Os usuários podem criar valores de ObjectRef sob demanda sem um autorizador para analisar objetos usando as próprias credenciais.
  • Use o acesso delegado para uma equipe grande que opera em vários projetos, principalmente quando o armazenamento e a análise de dados estão separados. O administrador de dados pode configurar conexões e criar valores de ObjectRef para análise com antecedência usando uma conexão como autorizador. Essa abordagem funciona com tabelas de objetos ou usando OBJ.MAKE_REF em uma lista de URIs. Em seguida, o administrador de dados pode compartilhar com os analistas a tabela que armazena os valores de ObjectRef. Os analistas não precisam acessar o bucket original para analisar os objetos.

Erros

As funções que consomem valores ObjectRef informam erros de duas maneiras:

  • Falha na consulta: a consulta pode falhar com uma mensagem de erro e nenhum resultado.
  • Valores de erro retornados: a consulta é bem-sucedida, mas a função pode gravar erros como parte do valor de retorno. Para informações sobre o formato do valor de retorno, consulte a página de referência da função que você está usando.

Quando uma função retorna um valor ObjectRef, o campo details desse valor pode conter um campo errors. Se houver, o valor desse campo será uma matriz de erros. Cada erro tem o seguinte esquema:

Nome Tipo Modo Descrição Exemplo
code INT64 REQUIRED Código de erro HTTP padrão. 400
message STRING REQUIRED Uma mensagem de erro descritiva e 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 O nome da função que acionou o erro. "OBJ.MAKE_REF"

Estes são dois tipos comuns de erros:

  • Erro de objeto: o URI ou a versão do objeto fornecida não existe.
  • Erro do autorizador: a conexão não existe ou o usuário não tem permissão para usá-la no acesso delegado.

A consulta a seguir mostra como selecionar valores de ObjectRef que contêm erros de uma coluna Objectref:

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

A seguir