protobuf 스키마 만들기 및 관리

프리뷰

이 제품이나 기능에는 서비스별 약관이 적용됩니다. 정식 버전(GA) 이전 제품과 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 문서에서는 스키마 번들을 만들고 스키마 번들에 대한 작업을 실행하는 방법을 설명합니다.

Bigtable에서는 프로토콜 버퍼 (protobuf) 스키마를 사용하여 열에 바이트로 저장된 protobuf 메시지 내의 개별 필드를 쿼리할 수 있습니다. 스키마 번들(하나 이상의 protobuf 스키마가 포함된 테이블 수준 리소스)에 스키마를 업로드하면 됩니다.

스키마 번들을 사용하면 다음과 같은 이점이 있습니다.

• 시간과 노력 절약: 프로토콜 버퍼를 사용하면 proto 파일에서 데이터 구조를 한 번 정의한 다음 생성된 소스 코드를 사용하여 데이터를 쓰고 읽을 수 있습니다.
• 데이터 일관성 향상: proto 파일을 단일 소스로 사용하면 모든 애플리케이션과 서비스가 동일한 데이터 모델을 사용하도록 할 수 있습니다.
• 데이터 중복 제거: 특정 프로젝트의 코드베이스 외부에 있는 proto 파일에 메시지 유형을 정의하여 프로젝트 전반에서 프로토콜 버퍼를 사용할 수 있습니다.

Bigtable에서 스키마를 사용하는 프로세스는 프로토 파일로 시작됩니다. proto 파일은 데이터 구조를 정의하는 텍스트 파일입니다. protoc이라고도 하는 protobuf 컴파일러 도구를 사용하여 protobuf 파일 설명자 세트를 생성합니다. 이는 proto 파일의 머신 판독 가능 스키마입니다. 그런 다음 이 설명자 세트를 사용하여 스키마 번들을 만듭니다.

프로토 파일 및 해당 설명자 세트의 예시는 예시 데이터를 참고하세요.

다음 다이어그램은 Bigtable에서 스키마를 사용하는 프로세스를 보여줍니다.

그림 1. Bigtable에서 protobuf 스키마를 사용하는 프로세스 (확대하려면 클릭)

Google Cloud CLI를 사용하여 스키마 번들을 만들 수 있습니다. 스키마 번들을 Bigtable에 업로드한 후 Bigtable Studio 쿼리 빌더, Bigtable용 GoogleSQL 또는 BigQuery의 Bigtable 외부 테이블을 사용하여 데이터를 쿼리할 수 있습니다.

시작하기 전에

gcloud CLI를 사용하려면 다음 단계를 따르세요.

1. Google Cloud CLI 설치

2. gcloud CLI를 초기화합니다.

   gcloud init
   

필요한 역할

스키마 번들을 만들고 관리하는 데 필요한 권한을 얻으려면 관리자에게 테이블에 대한 Bigtable 관리자 (roles/bigtable.admin) ID 및 액세스 관리 (IAM) 역할을 부여해 달라고 요청하세요.

이 사전 정의된 역할에는 Bigtable이 스키마 번들을 사용하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.

필수 권한

• bigtable.schemaBundles.create
• bigtable.schemaBundles.update
• bigtable.schemaBundles.delete
• bigtable.schemaBundles.get
• bigtable.schemaBundles.list

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

Bigtable 역할 및 권한에 대한 자세한 내용은 IAM으로 액세스 제어를 참고하세요.

protobuf 파일 설명자 집합 생성

스키마 번들을 만들려면 먼저 protobuf 컴파일러 도구를 사용하여 프로토 파일에서 설명자 세트를 생성해야 합니다.

1. 컴파일러를 설치하려면 패키지를 다운로드하고 리드미 파일의 안내를 따르세요.

2. 컴파일러를 실행합니다.

   protoc --proto_path=IMPORT_PATH --include_imports \
      --descriptor_set_out=DESCRIPTOR_OUTPUT_LOCATION PATH_TO_PROTO
   

   다음을 바꿉니다.

   • IMPORT_PATH: protoc 컴파일러가 proto 파일을 검색하는 디렉터리입니다.
   • DESCRIPTOR_OUTPUT_LOCATION: protoc 컴파일러가 생성된 설명자 세트를 저장하는 디렉터리입니다.
   • PATH_TO_PROTO: proto 파일의 경로입니다.

예를 들어 현재 디렉터리의 library.proto 파일에 대해 library.pb라는 설명자 세트를 만들려면 다음 명령어를 사용하면 됩니다.

protoc --include_imports --descriptor_set_out=library.pb
library.proto

스키마 번들 만들기

gcloud

스키마 번들을 만들려면 gcloud bigtable schema-bundles create 명령어를 사용합니다.

gcloud bigtable schema-bundles create SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --proto-descriptors-file=PROTO_DESCRIPTORS_FILE

다음을 바꿉니다.

• SCHEMA_BUNDLE_ID: 점 ('.') 문자를 포함할 수 없는 새 스키마 번들의 고유 ID입니다.
• INSTANCE_ID: 스키마 번들을 만들 인스턴스의 ID입니다.
• TABLE_ID: 스키마 번들을 만들 테이블의 ID입니다.
• PROTO_DESCRIPTORS_FILE: 이전 단계에서 생성된 설명자 세트의 경로입니다.

자바

스키마 번들을 만들려면 createSchemaBundle 메서드를 사용합니다.

Bigtable용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Bigtable 클라이언트 라이브러리를 참조하세요.

Bigtable에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

try {
  InputStream in = getClass().getClassLoader().getResourceAsStream(PROTO_FILE_PATH);
  CreateSchemaBundleRequest request =
      CreateSchemaBundleRequest.of(tableId, schemaBundleId)
          .setProtoSchema(ByteString.readFrom(in));
  SchemaBundle schemaBundle = adminClient.createSchemaBundle(request);
  System.out.printf("Schema bundle: %s created successfully%n", schemaBundle.getId());
} catch (NotFoundException e) {
  System.err.println(
      "Failed to create a schema bundle from a non-existent table: " + e.getMessage());
} catch (IOException e) {
  throw new RuntimeException(e);
}

스키마 번들에 관한 정보 보기

스키마 번들에 관한 정보를 보려면 스키마 번들이 하나 이상 있는 Bigtable 테이블이 있어야 합니다. 단일 스키마 번들의 정의를 가져오거나 테이블의 모든 스키마 번들을 나열하여 테이블의 스키마 번들에 관한 정보를 가져올 수 있습니다.

스키마 번들 정의 가져오기

gcloud

스키마 번들에 대한 세부정보를 가져오려면 gcloud bigtable schema-bundles describe 명령어를 사용합니다.

gcloud bigtable schema-bundles describe SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

다음을 바꿉니다.

• SCHEMA_BUNDLE_ID: 스키마 번들의 ID입니다.
• INSTANCE_ID: 인스턴스의 ID입니다.
• TABLE_ID: 테이블의 ID입니다.

자바

스키마 번들의 정의를 가져오려면 getSchemaBundle 메서드를 사용합니다. 이 메서드는 스키마 정의가 포함된 SchemaBundle 객체를 반환합니다.

다음 예시에서는 스키마 번들을 가져오고 설명자 집합을 역직렬화하여 스키마의 콘텐츠를 출력하는 방법을 보여줍니다.

Bigtable용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Bigtable 클라이언트 라이브러리를 참조하세요.

Bigtable에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

SchemaBundle schemaBundle = null;
try {
  schemaBundle = adminClient.getSchemaBundle(tableId, schemaBundleId);
  // Deserialize and print the FileDescriptorSet
  DescriptorProtos.FileDescriptorSet fileDescriptorSet =
      DescriptorProtos.FileDescriptorSet.parseFrom(schemaBundle.getProtoSchema());

  System.out.println("--------- Deserialized FileDescriptorSet ---------");
  for (DescriptorProtos.FileDescriptorProto fileDescriptorProto :
      fileDescriptorSet.getFileList()) {
    System.out.println("File: " + fileDescriptorProto.getName());
    System.out.println("  Package: " + fileDescriptorProto.getPackage());
    for (DescriptorProtos.DescriptorProto messageType :
        fileDescriptorProto.getMessageTypeList()) {
      System.out.println("  Message: " + messageType.getName());
    }
  }
  System.out.println("--------------------------------------------------");
} catch (InvalidProtocolBufferException e) {
  System.err.println("Failed to parse FileDescriptorSet: " + e.getMessage());
} catch (NotFoundException e) {
  System.err.println(
      "Failed to retrieve metadata from a non-existent schema bundle: " + e.getMessage());
}

출력은 다음과 비슷합니다.

--------- Deserialized FileDescriptorSet ---------
File: my_schema.proto
Package: my_package
Message: MyMessage
--------------------------------------------------

표로 스키마 번들 나열

gcloud

표의 스키마 번들 목록을 보려면 gcloud bigtable schema-bundles list 명령어를 사용합니다.

gcloud bigtable schema-bundles list \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

다음을 바꿉니다.

• INSTANCE_ID: 인스턴스의 ID입니다.
• TABLE_ID: 테이블의 ID입니다.

자바

표에 있는 모든 스키마 번들의 목록을 보려면 listSchemaBundles 메서드를 사용합니다. 이 메서드는 스키마 번들 ID 목록을 반환합니다.

다음 예시에서는 테이블에 스키마 번들을 나열하는 방법을 보여줍니다.

Bigtable용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Bigtable 클라이언트 라이브러리를 참조하세요.

Bigtable에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

List<String> schemaBundleIds = new ArrayList<>();
try {
  schemaBundleIds = adminClient.listSchemaBundles(tableId);
  for (String schemaBundleId : schemaBundleIds) {
    System.out.println(schemaBundleId);
  }
} catch (NotFoundException e) {
  System.err.println(
      "Failed to list schema bundles from a non-existent table: " + e.getMessage());
}

출력은 다음과 비슷합니다.

my-schema-bundle-1
my-schema-bundle-2

스키마 번들 업데이트

스키마 번들을 업데이트하면 Bigtable에서 새 설명자 세트가 기존 세트와 하위 호환되는지 확인합니다. 호환되지 않으면 FailedPrecondition 오류와 함께 업데이트가 실패합니다. 삭제된 필드 번호는 재사용되지 않도록 예약하는 것이 좋습니다. 자세한 내용은 protobuf 문서의 Proto 권장사항을 참고하세요.

호환되지 않는 변경사항이 안전하다고 확신하고 업데이트를 강제 적용하려면 gcloud CLI와 함께 --ignore-warnings 플래그를 사용하면 됩니다.

gcloud

다른 설명자 세트를 사용하도록 스키마 번들을 업데이트하려면 gcloud bigtable schema-bundles update 명령어를 사용합니다.

gcloud bigtable schema-bundles update SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --proto-descriptors-file=PROTO_DESCRIPTORS_FILE

다음을 바꿉니다.

• SCHEMA_BUNDLE_ID: 업데이트할 스키마 번들의 ID입니다.
• INSTANCE_ID: 스키마 번들을 포함하는 인스턴스의 ID입니다.
• TABLE_ID: 스키마 번들을 포함하는 테이블의 ID입니다.
• PROTO_DESCRIPTORS_FILE: 새 설명자 세트 파일의 경로입니다.

선택사항: 호환되지 않는 변경사항이 있더라도 업데이트를 강제하려면 --ignore-warnings 플래그를 사용하여 명령어를 추가합니다.

자바

Bigtable용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Bigtable 클라이언트 라이브러리를 참조하세요.

Bigtable에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

try {
  InputStream in = getClass().getClassLoader().getResourceAsStream(PROTO_FILE_PATH);
  UpdateSchemaBundleRequest request =
      UpdateSchemaBundleRequest.of(tableId, schemaBundleId)
          .setProtoSchema(ByteString.readFrom(in));
  SchemaBundle schemaBundle = adminClient.updateSchemaBundle(request);
  System.out.printf("Schema bundle: %s updated successfully%n", schemaBundle.getId());
} catch (NotFoundException e) {
  System.err.println("Failed to modify a non-existent schema bundle: " + e.getMessage());
} catch (IOException e) {
  throw new RuntimeException(e);
}

스키마 번들 삭제

경고: 이 작업은 되돌릴 수 없습니다.

gcloud

스키마 번들을 삭제하려면 gcloud bigtable schema-bundles delete 명령어를 사용합니다.

gcloud bigtable schema-bundles delete SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

다음을 바꿉니다.

• SCHEMA_BUNDLE_ID: 삭제할 스키마 번들의 ID입니다.
• INSTANCE_ID: 스키마 번들을 포함하는 인스턴스의 ID입니다.
• TABLE_ID: 스키마 번들을 포함하는 테이블의 ID입니다.

자바

Bigtable용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Bigtable 클라이언트 라이브러리를 참조하세요.

Bigtable에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

try {
  adminClient.deleteSchemaBundle(tableId, schemaBundleId);
  System.out.printf("SchemaBundle: %s deleted successfully%n", schemaBundleId);
} catch (NotFoundException e) {
  System.err.println("Failed to delete a non-existent schema bundle: " + e.getMessage());
}

제한사항

스키마 번들에는 다음과 같은 제한사항이 있습니다.

• 테이블당 최대 10개의 스키마 번들을 만들 수 있습니다.
• 스키마 번들 내 직렬화된 프로토콜 버퍼 설명자의 총 크기는 4MB를 초과할 수 없습니다. 번들의 총 크기가 이 한도를 초과하지 않는 한 번들에 포함할 수 있는 개별 스키마 수에는 직접적인 제한이 없습니다.

다음 단계

• protobuf 데이터 쿼리 방법 알아보기
• 변경되거나 불확실한 질문에 대해 알아보세요.
• Bigtable용 GoogleSQL 개요를 참고하세요.