protobuf 스키마 만들기 및 관리

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

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

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

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

Bigtable에서 스키마를 사용하는 프로세스는 proto 파일로 시작됩니다. proto 파일 은 데이터 구조를 정의하는 텍스트 파일입니다. protoc이라고도 하는 protobuf 컴파일러 도구를 사용하여 proto 파일의 머신 리더블 스키마인 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 컴파일러 도구를 사용하여 proto 파일에서 설명자 세트를 생성해야 합니다.

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

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)) {
  if (in == null) {
    throw new FileNotFoundException("Resource not found: " + PROTO_FILE_PATH);
  }
  SchemaBundle schemaBundleObj =
      SchemaBundle.newBuilder()
          .setProtoSchema(
              ProtoSchema.newBuilder().setProtoDescriptors(ByteString.readFrom(in)).build())
          .build();
  CreateSchemaBundleRequest request =
      CreateSchemaBundleRequest.newBuilder()
          .setParent(
              "projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
          .setSchemaBundleId(schemaBundleId)
          .setSchemaBundle(schemaBundleObj)
          .build();
  SchemaBundle schemaBundle = adminClient.createSchemaBundleAsync(request).get();
  System.out.printf("Schema bundle: %s created successfully%n", schemaBundle.getName());
} catch (Exception e) {
  System.err.println("Failed to create a schema bundle: " + e.getMessage());
}

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

스키마 번들에 대한 정보를 보려면 스키마 번들이 하나 이상 있는 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(
          "projects/"
              + projectId
              + "/instances/"
              + instanceId
              + "/tables/"
              + tableId
              + "/schemaBundles/"
              + schemaBundleId);
  // Deserialize and print the FileDescriptorSet
  DescriptorProtos.FileDescriptorSet fileDescriptorSet =
      DescriptorProtos.FileDescriptorSet.parseFrom(
          schemaBundle.getProtoSchema().getProtoDescriptors());

  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 {
  ListSchemaBundlesRequest request =
      ListSchemaBundlesRequest.newBuilder()
          .setParent(
              "projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
          .build();
  for (SchemaBundle bundle : adminClient.listSchemaBundles(request).iterateAll()) {
    String id = SchemaBundleName.parse(bundle.getName()).getSchemaBundle();
    System.out.println(id);
    schemaBundleIds.add(id);
  }
} 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)) {
  if (in == null) {
    throw new FileNotFoundException("Resource not found: " + PROTO_FILE_PATH);
  }
  SchemaBundle schemaBundleObj =
      SchemaBundle.newBuilder()
          .setName(
              "projects/"
                  + projectId
                  + "/instances/"
                  + instanceId
                  + "/tables/"
                  + tableId
                  + "/schemaBundles/"
                  + schemaBundleId)
          .setProtoSchema(
              ProtoSchema.newBuilder().setProtoDescriptors(ByteString.readFrom(in)).build())
          .build();
  UpdateSchemaBundleRequest request =
      UpdateSchemaBundleRequest.newBuilder()
          .setSchemaBundle(schemaBundleObj)
          .setUpdateMask(FieldMask.newBuilder().addPaths("proto_schema").build())
          .build();
  SchemaBundle schemaBundle = adminClient.updateSchemaBundleAsync(request).get();
  System.out.printf("Schema bundle: %s updated successfully%n", schemaBundle.getName());
} catch (Exception e) {
  System.err.println("Failed to modify schema bundle: " + e.getMessage());
}

스키마 번들 삭제

**경고:** 이 작업은 영구적입니다.

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(
      "projects/"
          + projectId
          + "/instances/"
          + instanceId
          + "/tables/"
          + tableId
          + "/schemaBundles/"
          + 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 개요를 참조하세요.