ObjectRef 값 사용

이 문서에서는 ObjectRef 값과 BigQuery에서 이를 만들고 사용하는 방법을 설명합니다.

ObjectRef 값은 멀티모달 분석을 위해 Cloud Storage 객체를 참조하는 사전 정의된 스키마가 있는 STRUCT 유형입니다. OBJ 함수, AI 함수 또는 Python 사용자 정의 함수로 처리할 수 있습니다.

스키마

ObjectRef 값에는 다음 필드가 있습니다.

이름 유형 모드 설명 예
uri STRING REQUIRED Cloud Storage 객체의 URI입니다. "gs://cloud-samples-data/vision/demo-img.jpg"
version STRING NULLABLE 객체 생성입니다. "1560286006357632"
authorizer STRING NULLABLE 위임된 액세스의 BigQuery 연결 ID 또는 직접 액세스의 NULL입니다. ID는
"region.connection"
또는
"project.region.connection" 형식일 수 있습니다.		 "myproject.us.myconnection"
details JSON NULLABLE 객체 메타데이터 또는 객체 처리에서 발생한 오류입니다. 객체의 content_type, md5_hash, size, updated 필드를 포함할 수 있습니다. {"gcs_metadata":{"content_type":"image/png","md5_hash":"dfbbb5cf034af026d89f2dc16930be15","size":915052,"updated":1560286006000000}}

details 열의 gcs_metadata 필드에 있는 content_type 필드가 Cloud Storage에서 가져옵니다. Cloud Storage에서 객체의 콘텐츠 유형을 설정할 수 있습니다. Cloud Storage에서 이를 생략하면 BigQuery가 URI의 접미사에서 콘텐츠 유형을 추론합니다.

ObjectRef 값 만들기

객체 테이블, OBJ.MAKE_REF 함수 또는 Cloud Storage Insights 데이터 세트를 사용하여 ObjectRef 값을 만들 수 있습니다.

객체 테이블 사용

테이블에 저장된 URI가 없고 Cloud Storage 접두사에서 모든 객체를 나열하려면 객체 테이블을 사용하세요. 객체 테이블은 각 행에 객체에 대한 참조를 저장하고 ObjectRef 값을 포함하는 ref 열이 있습니다. 다음 쿼리는 CREATE EXTERNAL TABLE 문을 사용하여 객체 테이블을 만듭니다.

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;

객체 테이블의 ObjectRef 값에는 위임된 액세스에 대한 승인자가 있어야 합니다. 승인자 연결은 객체 테이블을 만드는 데 사용하는 연결과 동일합니다.

OBJ.MAKE_REF 함수 사용

테이블에 URI가 이미 저장되어 있고 이러한 URI에서 ObjectRef 값을 만들려면 OBJ.MAKE_REF 함수를 사용합니다. 다음 쿼리는 Cloud Storage URI가 포함된 uri 열에서 image_ref 열에 ObjectRef 값을 만드는 방법을 보여줍니다.

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

기존 ObjectRef 값의 승인자를 수정하려면 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;

OBJ.MAKE_REF 함수는 직접 액세스 및 위임된 액세스를 지원하기 위해 null 허용 인증자를 허용합니다.

Cloud Storage Insights 데이터 세트 사용

Storage Insights 데이터 세트가 구성된 경우 데이터 세트에는 이미 ObjectRef 값이 포함된 ref 열이 포함되어 있습니다. 스토리지 인사이트 데이터 세트에서 생성된 ObjectRef 값에는 승인자가 없습니다. 이러한 객체를 쿼리하려면 객체에 대한 직접 액세스 권한이 있거나 ObjectRef에 승인자를 추가하여 위임된 액세스를 사용해야 합니다.

승인자 및 권한

ObjectRef 값을 ObjectRef 함수, AI 함수 또는 Python UDF에 전달하면 이러한 함수가 Cloud Storage에 저장된 객체에 액세스해야 합니다. 직접 액세스와 위임된 액세스라는 두 가지 방법으로 authorizer 필드의 값을 기반으로 이 액세스를 승인할 수 있습니다.

직접 액세스

직접 액세스를 사용하면 쿼리를 실행하는 사용자가 자신의 사용자 인증 정보를 사용하여 객체에 직접 액세스합니다. ObjectRef 값이 승인자가 없는 경우 직접 액세스가 사용됩니다.

직접 액세스에는 다음과 같은 제한사항이 있습니다.

  • 사용자에게 객체에 액세스할 수 있는 권한이 있어야 합니다.
  • 연결 없이 AI.GENERATE, AI.IF, AI.SCORE 또는 AI.CLASSIFY 함수를 사용하는 쿼리 작업에는 사용자에게 추가 권한이 필요합니다. 쿼리는 작업이 실행되는 동일한 프로젝트의 Cloud Storage 버킷 및 객체에만 액세스할 수 있습니다.

예를 들어 승인자가 없는 ObjectRef 값에서 AI.GENERATE 함수를 호출하면 함수가 객체를 사용자로 읽습니다. 객체를 읽을 권한이 없으면 함수는 결과의 status 열에 "permission denied" 오류를 씁니다.

다음 예는 직접 액세스를 사용하는 쿼리를 보여줍니다.

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

위임된 액세스 권한

위임된 액세스 권한을 사용하면 쿼리를 실행하는 사용자가 ObjectRef 값의 authorizer 필드에 지정된 BigQuery Cloud 리소스 연결에 객체 액세스 권한을 위임합니다. 위임된 액세스를 사용하면 교차 프로젝트 데이터 액세스가 가능합니다.

위임된 액세스를 사용하려면 데이터 관리자가 다음 단계에 따라 연결 및 권한을 설정해야 합니다.

예를 들어 사용자가 승인자가 있는 ObjectRef 값을 AI.GENERATE 함수에 전달하면 함수는 사용자에게 bigquery.objectRefs.read 권한이 있는지 확인한 다음 연결의 서비스 계정을 사용하여 객체를 읽습니다. 사용자 또는 서비스 계정에 권한이 부족하면 함수는 결과의 status 열에 "permission denied" 오류를 씁니다.

다음 예는 위임된 액세스를 사용하는 쿼리를 보여줍니다. 다음이 필요합니다.

  • 사용자에게 connection1에 대한 bigquery.objectRefs.read 권한이 있습니다.
  • connection1 서비스 계정에는 객체에 대한 storage.objects.get 권한이 있습니다.
  • connection2의 서비스 계정에는 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");

권장사항

직접 액세스 또는 위임된 액세스를 사용할지 여부를 결정할 때는 다음 권장사항을 고려하세요.

  • 데이터 저장 및 분석을 위해 단일 프로젝트에서 운영되는 소규모 팀의 경우 직접 액세스를 사용합니다. 데이터 관리자는 Identity and Access Management를 사용하여 사용자에게 BigQuery 데이터 및 Cloud Storage 데이터에 대한 액세스 권한을 부여합니다. 사용자는 자체 사용자 인증 정보를 사용하여 객체를 분석하기 위해 승인자 없이 필요에 따라 ObjectRef 값을 만들 수 있습니다.
  • 여러 프로젝트에서 운영되는 대규모 팀의 경우, 특히 데이터 스토리지와 분석이 분리된 경우 위임된 액세스를 사용하세요. 데이터 관리자는 연결을 승인자로 사용하여 미리 연결을 설정하고 분석을 위한 ObjectRef 값을 만들 수 있습니다. 이 접근 방식은 객체 테이블과 함께 작동하거나 URI 목록에서 OBJ.MAKE_REF를 사용하여 작동합니다. 그런 다음 데이터 관리자는 ObjectRef 값을 저장하는 표를 분석가와 공유할 수 있습니다. 분석가는 객체를 분석하기 위해 원래 버킷에 액세스할 필요가 없습니다.

오류

ObjectRef 값을 사용하는 함수는 다음과 같은 두 가지 방법으로 오류를 보고합니다.

  • 쿼리 실패: 오류 메시지가 표시되고 결과가 표시되지 않아 쿼리가 실패할 수 있습니다.
  • 반환된 오류 값: 쿼리는 성공하지만 함수가 반환 값의 일부로 오류를 쓸 수 있습니다. 반환 값의 형식에 대한 자세한 내용은 사용 중인 함수의 참조 페이지를 참고하세요.

함수가 ObjectRef 값을 반환하면 해당 값의 details 필드에 errors 필드가 포함될 수 있습니다. 그렇다면 해당 필드의 값은 오류 배열입니다. 각 오류에는 다음 스키마가 있습니다.

이름 유형 모드 설명 예
code INT64 REQUIRED 표준 HTTP 오류 코드입니다. 400
message STRING REQUIRED 설명적이고 사용자 친화적인 오류 메시지입니다. "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 오류를 트리거한 함수의 이름입니다. "OBJ.MAKE_REF"

다음은 두 가지 일반적인 오류 유형입니다.

  • 객체 오류: 제공된 객체 URI 또는 버전이 존재하지 않습니다.
  • 승인자 오류: 연결이 존재하지 않거나 사용자에게 위임된 액세스에 사용할 권한이 없습니다.

다음 쿼리는 Objectref 열에서 오류가 포함된 ObjectRef 값을 선택하는 방법을 보여줍니다.

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

다음 단계