새 스키마 버전 등록

주제를 만든 후 새 버전을 추가할 수 있습니다. 이 프로세스를 새 스키마 버전 등록이라고 합니다. 각 새 버전은 해당 주제와 연결된 스키마의 진화를 나타냅니다.

주제에는 여러 버전이 있을 수 있습니다. 주제 내 버전은 안전한 스키마 발전을 보장하기 위해 구성 가능한 호환성 규칙을 따릅니다. 예를 들어 주제는 모든 변경사항이 이전 버전과 호환되어야 한다고 요구할 수 있습니다. 하위 호환성 변경사항의 예는 선택 필드를 추가하는 것입니다. 필수 필드를 추가하는 것은 하위 호환되지 않는 변경사항으로 간주됩니다. 주제가 하위 호환성을 위해 구성된 경우 이 변경사항은 허용되지 않습니다. 하지만 주제가 하위 호환성을 위해 구성된 경우 필수 필드를 추가해도 됩니다.

호환성 검사는 소급 적용되지 않습니다. 주제 또는 스키마 레지스트리의 호환성 규칙이 변경되면 주제 내에 이미 있는 버전이 새 규칙을 기준으로 다시 검사되지 않습니다. 호환성에 대한 자세한 내용은 호환성 유형 정보를 참고하세요.

필수 역할 및 권한

주제에 대한 스키마 버전을 등록하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트 또는 특정 스키마 레지스트리 및 주제에 대한 관리 Kafka 스키마 레지스트리 편집자 (roles/managedkafka.schemaRegistryEditor) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 주제의 스키마 버전을 등록하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

주제의 스키마 버전을 등록하려면 다음 권한이 필요합니다.

상위 컨텍스트 또는 기본 컨텍스트에 이 권한을 부여합니다. managedkafka.versions.create

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

상위 수준의 관리형 Kafka 스키마 레지스트리 관리자(roles/managedkafka.schemaRegistryAdmin) 역할에도 이러한 권한이 포함되어 있습니다.

Apache Kafka용 관리형 서비스에 사용할 수 있는 사전 정의된 역할에 대한 자세한 내용은 액세스 제어 문서를 참고하세요.

새 스키마 버전 등록

새 스키마 버전을 등록하려면 다음 단계를 따르세요.

콘솔

Google Cloud 콘솔에서 스키마 레지스트리 페이지로 이동합니다.

스키마 레지스트리로 이동
새 스키마 버전을 등록할 스키마 레지스트리의 이름을 클릭합니다.
Subjects in this schema registry(이 스키마 레지스트리의 제목)에서 제목 이름을 클릭합니다.
주체 세부정보 페이지에서 버전 만들기를 클릭합니다.
스키마 정의 필드에 최신 버전의 정의가 표시됩니다. 이 필드의 정의를 새 버전으로 업데이트합니다. 스키마 필드 이름에 개인 식별 정보 (PII) 또는 보안 데이터와 같은 민감한 정보를 포함하지 마세요.
스키마가 스키마 레지스트리의 다른 스키마에 정의된 데이터 구조를 사용하거나 이에 종속되는 경우 다음 단계를 실행하세요.
1. 스키마 참조 추가를 클릭합니다.
2. 참조 이름 필드에 참조된 스키마의 참조 이름을 입력합니다.
3. 주제 목록에서 참조된 스키마가 포함된 주제를 선택합니다.
4. 버전 목록에서 참조된 스키마의 버전 번호를 선택합니다.
5. 확인을 클릭합니다.
참조된 각 스키마에 대해 이 단계를 반복합니다.
(선택사항) 새 스키마가 이전 버전과 호환되는지 확인하려면 호환성 확인을 클릭합니다.

스키마가 호환되면 체크표시가 표시됩니다. 그렇지 않으면 오류 메시지가 표시됩니다. 이 경우 오류를 수정하고 호환성 확인을 다시 클릭합니다.

실행되는 호환성 검사는 주제의 호환성 유형에 따라 다릅니다.
만들기를 클릭합니다. 스키마 정의가 유효하고 주제의 호환성 검사를 통과하면 새 버전이 모든 버전에 표시됩니다.

REST

Authorization 헤더의 액세스 토큰으로 요청을 인증해야 합니다. 현재 애플리케이션 기본 사용자 인증 정보의 액세스 토큰을 얻으려면 gcloud auth application-default print-access-token을 실행합니다.

기본 컨텍스트 내에서 주제의 새 스키마 버전을 등록하려면 projects.locations.schemaRegistries.subjects.versions.create 메서드를 사용하여 특정 URI에 POST 요청을 실행합니다.

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

또는 특정 컨텍스트를 사용하는 경우 버전 컬렉션 URI에 컨텍스트를 포함하고 projects.locations.schemaRegistries.contexts.subjects.versions.create 메서드를 사용합니다.

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

다음을 바꿉니다.

PROJECT_ID (필수): Google Cloud프로젝트 ID입니다.
LOCATION (필수): 스키마 레지스트리가 있는 Google Cloud 리전입니다.
REGISTRY_ID (필수): 대상 스키마 레지스트리의 ID입니다.
CONTEXT_ID (선택사항): 주제를 포함하는 컨텍스트의 ID입니다. 명시적으로 지정하려면 기본 컨텍스트에 . (단일 마침표)를 사용하고, 그렇지 않으면 /contexts/CONTEXT_ID을 생략하여 기본 컨텍스트를 암시적으로 사용합니다.
SUBJECT_ID (필수): 새 버전을 만들 주체의 ID입니다.

요청 본문:

요청 본문에 스키마 세부정보를 지정하는 JSON 객체를 포함합니다.

{
  "schema": "YOUR_SCHEMA_DEFINITION_STRING",
  "schema_type": "AVRO" | "PROTOBUF" | "JSON", // Optional, defaults to AVRO
  "references": [ // Optional
    {
      "name": "REFERENCE_NAME",
      "subject": "REFERENCED_SUBJECT_ID",
      "version": REFERENCED_VERSION_NUMBER
    }
    // ... more references
  ]
  // "version": VERSION_NUMBER, // Optional: Usually omitted, let service assign next
  // "id": SCHEMA_ID, // Optional: Usually omitted, let service assign or reuse
}

다음을 바꿉니다.

YOUR_SCHEMA_DEFINITION_STRING (필수): 실제 스키마 정의 페이로드를 포함하는 문자열입니다.
schemaType (선택사항, schema 객체 내): 스키마의 유형입니다. AVRO 또는 PROTOBUF일 수 있습니다. 생략하면 기본값은 AVRO입니다.
references (선택사항, schema 객체 내): 이 스키마에서 참조하는 스키마를 정의하는 객체의 배열입니다.
- REFERENCE_NAME: 이 스키마의 정의 내에서 다른 스키마를 참조하는 데 사용되는 이름입니다.
- REFERENCED_SUBJECT_ID: 참조되는 스키마의 정규화된 주제 이름입니다. 예를 들면 projects/test-project/locations/us-central1/schemaRegistries/test-registry/subjects/test-referenced-subject입니다.
- REFERENCED_VERSION_NUMBER: 참조된 주제 스키마의 특정 버전 번호 (정수)입니다.
versionId, schemaId: 서비스에서 일반적으로 처리하는 선택적 필드입니다. 스키마 버전을 등록할 때 서비스는 사용 가능한 다음 버전 번호를 할당합니다.

요청이 성공하면 API가 200 OK 상태 코드와 스키마 ID가 포함된 응답 본문을 반환합니다.

자세한 내용은 REST API 문서를 참고하세요.

다음 단계

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

달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.

최종 업데이트: 2026-02-25(UTC)