제목 만들기

이 문서에서는 스키마 레지스트리에서 주제를 만드는 방법을 설명합니다. 주제는 스키마의 여러 버전을 위한 논리적 컨테이너입니다. 주제를 처음 만들면 해당 주제의 스키마 첫 번째 버전도 생성됩니다.

다음 방법 중 하나로 주제를 만들 수 있습니다.

암시적 (기본값): 많은 생산자 및 소비자 클라이언트의 기본 동작은 클라이언트가 연결될 때 존재하지 않는 스키마를 자동으로 만드는 것입니다. 스키마를 참조하는 주제와 버전도 자동으로 생성됩니다. 이는 편리하지만 여러 클라이언트가 동시에 버전을 만들면 데이터가 일치하지 않을 수 있습니다.
명시적 (권장): 이 방법에서는 생산자 또는 소비자 클라이언트가 스키마를 사용하기 전에 각 스키마를 레지스트리에 만들어야 합니다. Google Cloud 콘솔 또는 관리형 Kafka API를 사용하여 이 작업을 수행할 수 있습니다.

이 동작은 클라이언트 설정에서 구성해야 합니다. 자세한 내용은 직렬화기 또는 역직렬화기 클라이언트 라이브러리 문서를 참고하세요.

시작하기 전에

스키마 개요에 대해 알아봅니다.
아직 없는 경우 스키마 레지스트리를 만듭니다.
스키마 참조를 이해합니다.

필수 역할 및 권한

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

이 사전 정의된 역할에는 주제를 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

주체를 만들려면 다음 권한이 필요합니다.

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

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

상위 수준의 관리형 Kafka 스키마 레지스트리 관리자(roles/managedkafka.schemaRegistryAdmin) 역할에는 주제 버전을 만들고 관리할 수 있는 권한도 포함되어 있습니다.

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

주제 또는 스키마의 첫 번째 버전 만들기

주제를 만들면 첫 번째 버전도 만들어집니다. 이 첫 번째 버전은 새 스키마를 만들거나 기존 스키마를 참조합니다.

콘솔

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

스키마 레지스트리로 이동
주제를 만들 스키마 레지스트리의 이름을 클릭합니다.
주제 만들기를 클릭합니다.
주체 이름에 주체의 고유한 이름을 입력합니다.

이름은 영문자로 시작해야 하며 영문자, 숫자, 대시 (-), 마침표 (.), 밑줄(_), 물결표 (~), 퍼센트 (%), 더하기 기호 (+)만 포함해야 합니다. 주제의 이름은 변경할 수 없습니다.

주체 이름 선택에 대한 자세한 내용은 주체 이름 지정 전략을 참고하세요.
컨텍스트에서 컨텍스트를 선택하거나 새 컨텍스트를 만듭니다. 컨텍스트는 네임스페이스처럼 작동하여 주제와 스키마를 정리하고 서로 다른 그룹 간에 격리를 제공합니다.
- 기존 컨텍스트를 사용하려면 컨텍스트 목록에서 컨텍스트를 선택합니다. 기본 컨텍스트는 (default context)로 표시됩니다.
- 새 컨텍스트를 만들려면 다음 단계를 따르세요.
  1. 컨텍스트 목록에서 컨텍스트 만들기를 선택합니다.
  2. 컨텍스트 이름 필드에 컨텍스트 이름을 입력합니다.
    
    이름은 영문자로 시작하고 영문자, 숫자, 대시 (-), 마침표(.), 밑줄 (_), 물결표 (~), 퍼센트 (%), 더하기 기호(+)만 포함해야 합니다. 컨텍스트의 이름은 변경할 수 없습니다.
  3. 저장을 클릭합니다.
스키마 유형에 Avro 또는 프로토콜 버퍼를 선택합니다.
스키마 정의 필드에 스키마 정의를 입력합니다. 스키마 형식은 스키마 유형과 일치해야 합니다. 스키마 필드 이름에 개인 식별 정보 (PII) 또는 보안 데이터와 같은 민감한 정보를 포함하지 마세요.
스키마가 스키마 레지스트리의 다른 스키마에 정의된 데이터 구조를 사용하거나 이에 종속되는 경우 다음 단계를 실행하세요.
1. 스키마 참조 추가를 클릭합니다.
2. 참조 이름 필드에 참조된 스키마의 참조 이름을 입력합니다.
3. 주제 목록에서 참조된 스키마가 포함된 주제를 선택합니다.
4. 버전 목록에서 참조된 스키마의 버전 번호를 선택합니다.
5. 확인을 클릭합니다.
참조된 각 스키마에 대해 이 단계를 반복합니다.
만들기를 클릭합니다.

REST

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

다음 REST API 샘플은 주제의 첫 번째 버전을 만듭니다.

기본 컨텍스트 내에서 주체를 만들려면 projects.locations.schemaRegistries.subjects.versions.create 메서드를 사용하여 지정된 URI에 POST 요청을 전송합니다.

POST https://managedkafka.googleapis.com/v1main/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

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

POST https://managedkafka.googleapis.com/v1main/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", // 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 (필수): 실제 스키마 정의 페이로드를 포함하는 문자열입니다.

스키마 필드 이름에 개인 식별 정보 (PII) 또는 보안 데이터와 같은 민감한 정보를 포함하지 마세요.
schemaType (선택사항): 스키마 유형입니다. AVRO 또는 PROTOBUF일 수 있습니다. 생략하면 기본값은 AVRO입니다.
references (선택사항): 이 스키마에서 참조하는 스키마를 정의하는 객체의 배열입니다.
- REFERENCE_NAME: 이 스키마의 정의 내에서 다른 스키마를 참조하는 데 사용되는 이름입니다.
- REFERENCED_SUBJECT_ID: 참조되는 스키마의 주제 ID입니다.
- REFERENCED_VERSION_NUMBER: 참조된 주제의 스키마의 특정 버전 번호입니다.
versionId, schemaId: 서비스에서 일반적으로 처리하는 선택적 필드입니다. 주제의 첫 번째 버전의 경우 versionId은 '1'입니다.

요청이 성공하고 스키마가 유효하며 구성된 경우 호환성 검사를 통과하면 API가 200 OK 상태 코드를 반환합니다. 응답 본문에는 생성된 버전에서 사용되는 스키마 ID가 포함되어 있으며, 이는 버전 ID와 다릅니다.

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

다음 단계

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