스키마 레지스트리 개요

스키마 레지스트리는 여러 애플리케이션에서 공유하는 스키마 저장소를 제공합니다. 이전에는 스키마 레지스트리가 없었기 때문에 팀에서 메시지 형식과 메시지 직렬화 및 역직렬화 방법을 정의하기 위해 비공식 계약(예: 구두 이해, 프로그래매틱 방식으로 적용되지 않는 공유 문서, 위키 페이지)에 의존했을 수 있습니다. 스키마 레지스트리는 일관된 메시지 인코딩 및 디코딩을 보장합니다.

이 문서에서는 Apache Kafka용 관리형 서비스의 스키마 레지스트리 기능, 구성요소, 기본 워크플로를 간략하게 설명합니다.

스키마 이해

고객 주문을 추적하는 애플리케이션을 빌드한다고 가정해 보겠습니다. customer_orders라는 Kafka 주제를 사용하여 각 주문에 관한 정보가 포함된 메시지를 전송할 수 있습니다. 일반적인 주문 메시지에는 다음 정보 필드가 포함될 수 있습니다.

주문 ID
고객 이름
제품 이름
수량
가격

이러한 메시지가 일관되게 구조화되도록 스키마를 정의할 수 있습니다. 다음은 Apache Avro 형식의 예입니다.

{
  "type": "record",
  "name": "Order",
  "namespace": "com.example",
  "fields": [
    {"name": "orderId", "type": "string"},
    {"name": "customerName", "type": "string"},
    {"name": "productName", "type": "string"},
    {"name": "quantity", "type": "int"},
    {"name": "price", "type": "double"}
  ]
}

다음은 프로토콜 버퍼 형식의 동일한 예입니다.

syntax = "proto3";

package com.example;

option java_multiple_files = true; // Optional: Recommended for Java users
option java_package = "com.example"; // Optional: Explicit Java package

message Order {
  string orderId = 1;
  string customerName = 2;
  string productName = 3;
  int32 quantity = 4; // Avro int maps to Protobuf int32
  double price = 5;
}

이 스키마는 메시지의 청사진입니다. order 메시지에는 주문 ID, 고객 이름, 제품 이름, 수량, 가격의 5개 필드가 있습니다. 각 필드의 데이터 유형도 지정합니다.

소비자 클라이언트가 이 스키마로 인코딩된 바이너리 메시지를 수신하는 경우 이를 해석하는 방법을 정확히 알아야 합니다. 이를 위해 생산자는 스키마 레지스트리에 order 스키마를 저장하고 메시지와 함께 스키마 식별자를 전달합니다. 메시지 소비자가 사용된 레지스트리를 알고 있는 한 동일한 스키마를 검색하고 메시지를 디코딩할 수 있습니다.

order 메시지에 orderDate 필드를 추가한다고 가정해 보겠습니다. order 스키마의 새 버전을 만들고 동일한 주제로 등록합니다. 이를 통해 시간 경과에 따른 스키마의 변화를 추적할 수 있습니다. 필드 추가는 상위 호환 변경사항입니다. 즉, 이전 스키마 버전 (orderDate 없음)을 사용하는 소비자는 새 스키마로 생성된 메시지를 계속 읽고 처리할 수 있습니다. 새 필드는 무시됩니다.

스키마 레지스트리의 하위 호환성은 새 스키마 버전으로 구성된 소비자 애플리케이션이 이전 스키마로 생성된 데이터를 읽을 수 있음을 의미합니다.

이 예시에서 초기 order 스키마는 버전 1입니다. orderDate 필드를 추가하면 order 스키마의 버전 2가 생성됩니다. 두 버전 모두 동일한 주제 아래에 저장되므로 버전 1을 계속 사용할 수 있는 기존 애플리케이션을 중단하지 않고 스키마 업데이트를 관리할 수 있습니다.

다음은 컨텍스트, 주제, 스키마 버전별로 정리된 샘플 스키마 레지스트리(schema_registry_test)의 하향식 뷰입니다.

customer_support context
- order 제목
- V1 버전 (orderId, customerName, productName, quantity, price 포함)
- V2 버전 (V1에 orderDate 추가)

스키마란 무엇인가요?

Apache Kafka 메시지는 바이트 문자열로 구성됩니다. 정의된 구조가 없으면 소비자 애플리케이션은 이러한 바이트를 해석하는 방법을 이해하기 위해 생산자 애플리케이션과 직접 조정해야 합니다.

스키마는 메시지 내 데이터에 대한 공식 설명을 제공합니다. 필드와 문자열, 정수, 불리언과 같은 데이터 유형, 중첩된 구조를 정의합니다.

Managed Service for Apache Kafka는 다음 형식의 스키마를 지원합니다.

Apache Avro
프로토콜 버퍼 (Protobuf)

스키마 레지스트리 API는 JSON을 지원하지 않습니다.

Apache Kafka용 관리형 서비스 내에 통합된 스키마 레지스트리 기능을 사용하면 Kafka 클라이언트로 이러한 스키마를 만들고, 관리하고, 사용할 수 있습니다. 스키마 레지스트리는 기존 Apache Kafka 애플리케이션 및 일반 클라이언트 라이브러리와 호환되는 Confluent 스키마 레지스트리 REST API를 구현합니다.

스키마 레지스트리 조직

스키마 레지스트리는 계층 구조를 사용하여 스키마를 구성합니다.

그림: 스키마의 계층 구조

스키마: 메시지의 구조와 데이터 유형입니다. 각 스키마는 스키마 ID로 식별됩니다. 이 ID는 애플리케이션이 스키마를 가져오는 데 사용됩니다.
주제: 스키마의 여러 버전을 위한 논리적 컨테이너입니다. 주제는 호환성 규칙을 사용하여 시간이 지남에 따라 스키마가 어떻게 발전하는지 관리합니다. 각 주제는 일반적으로 Kafka 주제 또는 레코드 객체에 해당합니다.
버전: 비즈니스 로직에 메시지 구조 변경이 필요한 경우 관련 주제 아래에 새 스키마 버전을 만들어 등록합니다.

각 버전은 특정 스키마를 참조합니다. 기본 스키마가 동일한 경우 서로 다른 주제의 버전이 동일한 스키마를 참조할 수 있습니다.
컨텍스트: 주제의 상위 그룹 또는 네임스페이스입니다. 컨텍스트를 사용하면 서로 다른 팀이나 애플리케이션이 동일한 스키마 레지스트리 내에서 충돌 없이 동일한 주제 이름을 사용할 수 있습니다.

스키마 레지스트리에는 컨텍스트가 여러 개 있을 수 있습니다. 항상 .로 식별되는 기본 컨텍스트가 포함됩니다. 다른 컨텍스트 식별자가 지정되지 않은 경우 스키마와 주제가 여기에 배치됩니다.

컨텍스트에는 여러 주제가 포함될 수 있습니다.
레지스트리: 전체 스키마 생태계의 최상위 컨테이너입니다. 모든 스키마, 주제, 버전, 컨텍스트를 저장하고 관리합니다.

스키마 레지스트리 워크플로

이 섹션에 설명된 워크플로를 따르려면 스키마 레지스트리로 Avro 메시지 생성에서 빠른 시작을 사용해 보세요.

Kafka 클라이언트의 직렬화 프로그램과 역직렬화 프로그램은 스키마 레지스트리와 상호작용하여 메시지가 정의된 스키마를 준수하도록 합니다. 다음은 Managed Service for Apache Kafka의 스키마 레지스트리의 일반적인 워크플로입니다.

Avro 생성 클래스로 지정된 특정 스키마로 프로듀서 애플리케이션을 초기화하고 특정 스키마 레지스트리 및 직렬화 프로그램 라이브러리를 사용하도록 구성합니다.
해당 역직렬화기 라이브러리와 동일한 스키마 레지스트리를 사용하도록 소비자 클라이언트를 구성합니다.
런타임에 클라이언트는 메시지 객체를 producer.send 메서드에 전달하고 Kafka 클라이언트 라이브러리는 구성된 직렬화 프로그램을 사용하여 이 레코드를 Avro로 인코딩된 바이트로 변환합니다.
직렬화기는 클라이언트 라이브러리 내에 구성된 주제 이름 전략을 기반으로 스키마의 주제 이름을 결정합니다. 그런 다음 스키마 레지스트리에 대한 요청에서 이 주제 이름을 사용하여 스키마의 ID를 가져옵니다. 자세한 내용은 주제 이름 지정 전략을 참고하세요.
해당 주제 이름으로 레지스트리에 스키마가 없으면 클라이언트가 스키마를 등록하도록 구성할 수 있으며, 이 경우 새로 할당된 ID를 수신합니다.

프로덕션 환경에서는 이 구성을 사용하지 마세요.
프로듀서는 스키마 ID가 포함된 직렬화된 메시지를 Kafka 브로커의 적절한 주제에 전송합니다.
Kafka 브로커는 주제에 메시지의 바이트 배열 표현을 저장합니다.
소비자 애플리케이션이 메시지를 수신합니다.
역직렬화기는 스키마 레지스트리에서 이 ID를 사용하여 스키마를 가져옵니다.
역직렬화기는 소비자 애플리케이션의 메시지를 파싱합니다.

제한사항

다음 기능은 스키마 레지스트리에서 지원되지 않습니다.

스키마 형식:
- JSON 스키마 형식입니다.
스키마 모드:
- READONLY_OVERRIDE 스키마 모드
스키마 구성 값:
- Normalize 및 Alias 구성 값
API 메서드:
- ModifySchemaTags 메서드 (/subjects/{subject}/versions/{version}/tags)
- GetLatestWithMetadata 메서드 (/subjects/{subject}/metadata)
- ListSchemas 메서드 (/schemas)
- DeleteSchemaMode 메서드.
- GetVersion 메서드의 경우 format, deleted, findTags 매개변수
- CreateVersion 메서드의 경우 metadata, ruleSet, schemaTagsToAdd, schemaTagsToRemove 매개변수
- UpdateSchemaMode 메서드의 경우 force 매개변수
- GetSchemaMode 메서드의 경우 defaultToGlobal 매개변수
- GetSchema 메서드의 경우 WorkspaceMaxId 및 findTags 매개변수
- ListVersions 메서드의 경우 deletedOnly 매개변수
- ListSubjects 메서드의 경우 deletedOnly 매개변수

다음 단계

Apache Kafka®는 미국 및/또는 다른 국가에서 사용되는 Apache Software Foundation 또는 해당 계열사의 등록 상표입니다.