스키마 1

{
  "type": "record",
  "name": "book",
  "fields": [
    {
      "name": "title",
      "type": "string"
    },
    {
      "name": "author",
      "type": "string"
    }
  ]
}

스키마 2

{
  "type": "record",
  "name": "book",
  "fields": [
    {
      "name": "author",
      "type": "string"
    },
    {
      "name": "title",
      "type": "string"
    }
  ]
}

스키마 3

{
  "type": "record",
  "name": "book",
  "fields": [
    {
      "type": "string"
      "name": "author",
    },
    {
      "type": "string"
      "name": "title",
    }
  ]
}

스키마 1및 스키마 2는 구별되는 스키마이며 레지스트리는 이를 별도의 스키마로 저장합니다. author 및 title 필드를 다른 순서로 나열하기 때문에 서로 교환하여 사용할 수 없습니다. 스키마 1로 인코딩된 데이터는 디코딩 프로세스에서 스키마 2를 사용한 경우 올바르게 디코딩되지 않습니다.

SerDes 를 사용하여 Schema 1, Schema 2및 Schema 3의 순서로 새 스키마를 작성하면 두 개의 새 스키마가 작성됩니다. 스키마 1과 스키마 2는 다르지만 스키마 3은 스키마 2와 동일합니다.

REST API를 사용하여 스키마를 작성할 때 스키마는 모든 속성 순서 지정 및 설명 필드를 포함하여 텍스트가 동일한 경우에만 일치하는 것으로 간주됩니다. 이는 스키마 3이 다른 스키마가 되기를 원하는 경우를 허용하기 위한 것입니다.

인증

스키마 레지스트리에 액세스하려면 레지스트리를 인증하는 데 사용할 수 있는 신임 정보 세트도 필요합니다. API키를 사용한 기본 인증 또는 베어러 토큰 인증의 두 가지 옵션이 있습니다.

이 문서의 예제는 API키의 사용을 표시하지만 두 옵션 중 하나를 사용할 수 있습니다.

curl -u token:$APIKEY ...

curl -H "Authorization: Bearer $TOKEN" ...

오류

오류 조건이 발생하면 스키마 레지스트리는 오류 범위( non-2XX )와 상태 코드( HTTP )를 반환합니다. 응답 본문에는 다음과 같은 형식의 JSON 객체가 포함되어 있습니다

{
    "error_code":404,
    "message":"No artifact with id 'my-schema' might be found."
}

오류 JSON 오브젝트의 특성은 다음과 같습니다.

스키마 상태 설정

이 엔드포인트는 레지스트리의 스키마 상태를 ENABLED 또는 DISABLED 로 설정하는 데 사용됩니다. 스키마의 상태는 /artifacts/{schema-id}/state 엔드포인트에 PUT 요청을 발행하여 설정할 수 있습니다 (여기서 {schema-id} 는 스키마의 ID임). 요청이 성공하면 빈 응답과 상태 코드 204(내용 없음)가 반환됩니다.

curl 요청 예:

curl -u token:$APIKEY –X PUT $URL/artifacts/my-schema/state -d '{"state": "DISABLED"}'

스키마 상태를 설정하려면 다음이 필요합니다.

• 관리자 역할은 수정된 스키마와 일치하는 스키마 리소스에 대한 액세스 권한을 갖습니다.

스키마 버전 상태 설정

이 엔드포인트는 레지스트리의 스키마 버전 상태를 ENABLED 또는 DISABLED 로 설정하는 데 사용됩니다. 스키마 버전의 상태는 /artifacts/{schema-id}/versions/{version}/state 엔드포인트에 PUT 요청을 발행하여 설정할 수 있습니다 (여기서 {schema-id} 는 스키마의 ID이고 {version} 은 스키마 버전의 버전 번호임). 요청이 성공하면 빈 응답과 상태 코드 204(내용 없음)가 반환됩니다.

curl 요청 예:

curl -u token:$APIKEY –X PUT $URL/artifacts/my-schema/versions/1/state -d '{"state": "DISABLED"}'

스키마 버전 상태를 설정하려면 다음이 필요합니다.

• 관리자 역할은 수정 중인 스키마와 일치하는 스키마 리소스에 대한 액세스 권한을 갖습니다.

스키마 작성

이 엔드포인트는 레지스트리에서 스키마를 저장하는 데 사용됩니다. 스키마 데이터는 POST 요청의 본문으로 전송됩니다. ‘X-Registry-ArtifactId' 요청 헤더를 사용하면 스키마에 대한 ID를 포함할 수 있습니다. 이 헤더가 요청에 없으면 ID가 생성됩니다. 컨텐츠 유형 헤더는 “application/json”으로 설정되어야 합니다.

curl 요청 예:

curl -u token:$APIKEY -H 'Content-Type: application/json' -H 'X-Registry-ArtifactId: my-schema' $URL/artifacts -d '{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}'

리소스 예:

{"id":"my-schema","type":"AVRO","version":1,"createdBy":"","createdOn":1579267788258,"modifiedBy":"","modifiedOn":1579267788258,"globalId":75}

스키마를 작성하려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한
• 작성자 역할은 생성된 스키마와 일치하는 스키마 리소스에 대한 액세스 권한을 갖습니다.

조치를 보고하기 위한 활동 추적 프로그램 이벤트가 생성됩니다. 자세한 정보는 Activity Tracker 이벤트를 참조하십시오.

목록 스키마

/artifacts 엔드포인트에 GET 요청을 보내면 레지스트리에 저장된 모든 스키마의 ID 목록을 생성할 수 있습니다. jsonformat 매개변수를 사용하여 응답을 형식화할 수 있습니다 ( string 및 object 형식만 지원됨). 문자열 형식은 기본값이며 아티팩트 ID (문자열) 의 배열을 리턴합니다. 이 옵션이 설정되면 사용 가능한 아티팩트만 배열에 포함됩니다. 오브젝트 형식은 배열의 각 항목이 레지스트리의 아티팩트에 해당하는 배열을 포함하는 JSON 오브젝트를 리턴합니다. 이 옵션이 설정되면 사용 및 사용 안함으로 설정된 아티팩트가 모두 리턴됩니다.

curl 요청 예:

curl -u token:$APIKEY $URL/artifacts

or

curl -u token:$APIKEY $URL/artifacts?jsonformat=string

or

curl -u token:$APIKEY $URL/artifacts?jsonformat=object

jsonformat이 문자열이거나 제공되지 않은 경우의 응답 예 (기본값은 문자열):

["my-schema-2","my-schema-4"]

jsonformat이 오브젝트인 경우 응답 예:

{"artifacts":[{"id":"my-schema","state":"DISABLED"},{"id":"my-schema-2","state":"ENABLED"},{"id":"my-schema-3","state":"DISABLED"},{"id":"my-schema-4","state":"ENABLED"}],"count":4}

스키마를 나열하려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한

스키마의 상태 및 삭제

스키마 삭제는 2단계프로세스입니다. 삭제의 첫 번째 단계는 레지스트리에서 스키마를 보존하지만 일부 조작에서는 스키마를 숨깁니다. 두 번째 단계는 스키마를 영구적으로 제거하지만 첫 번째 단계 이후에만 적용할 수 있습니다. 2단계삭제 프로세스는 아티팩트 레벨 및 버전 레벨에서도 적용됩니다.

두 단계의 삭제는 아티팩트 및 버전 (첫 번째 단계) 모두와 연관된 사용 또는 사용 안함 상태를 갖고 자원 및 버전 (두 번째 단계) 에 대한 API를 삭제하여 수행됩니다.

사용 안함으로 설정된 아티팩트 또는 버전은 아티팩트 또는 버전을 나열하는 오퍼레이션에 의해 리턴되는 '상태' 특성을 사용하거나 아티팩트 또는 버전의 세부사항을 가져와서 발견할 수 있습니다. 사용 안함으로 설정된 스키마는 엔터프라이즈 인스턴스당 1000개스키마의 스키마 할당량에 포함됩니다.

스키마 삭제

스키마는 /artifacts/{schema-id} 엔드포인트에 DELETE 요청을 보내면 레지스트리에서 삭제됩니다(여기서 {schema-id} 는 스키마의 ID입니다). 성공하면 비어 있는 요청과 204의 상태 코드(컨텐츠 없음)가 리턴됩니다.

curl 요청 예:

curl -u token:$APIKEY -X DELETE $URL/artifacts/my-schema

스키마를 삭제하려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한
• 관리자 역할은 삭제된 스키마와 일치하는 스키마 리소스에 대한 액세스 권한을 가집니다.

조치를 보고하기 위한 활동 추적 프로그램 이벤트가 생성됩니다. 자세한 정보는 Activity Tracker 이벤트를 참조하십시오.

스키마의 새 버전 작성

스키마의 새로운 버전을 생성하려면, /artifacts/{schema-id}/versions 엔드포인트에 POST 요청을 하십시오(여기서 {schema-id} 는 스키마의 ID입니다). 요청의 본문에는 스키마의 새 버전이 포함되어야 합니다.

요청이 성공적으로 완료되면, 새로운 스키마가 스키마의 최신 버전으로 생성되고, 적절한 버전 번호가 부여되며, 상태 코드 200(OK)이 포함된 응답과 새로운 버전을 설명하는 메타데이터(버전 번호 포함)가 포함된 페이로드가 반환됩니다.

curl 요청 예:

curl -u token:$APIKEY -H 'Content-Type: application/json' $URL/artifacts/my-schema/versions -d '{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}'

리소스 예:

{"id":"my-schema","type":"AVRO","version":2,"createdBy":"","createdOn": 1579267978382,"modifiedBy":"","modifiedOn":1579267978382,"globalId":83}

스키마의 새 버전을 작성하려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한
• 작성자 역할은 새 버전을 가져오는 스키마와 일치하는 스키마 리소스에 대한 액세스 권한을 갖습니다.

조치를 보고하기 위한 활동 추적 프로그램 이벤트가 생성됩니다. 자세한 정보는 Activity Tracker 이벤트를 참조하십시오.

스키마의 최신 버전 가져오기

특정 스키마의 최신 버전을 검색하려면 /artifacts/{schema-id} 엔드포인트에 GET 요청을 하십시오(여기서 {schema-id} 는 스키마의 ID입니다). 성공하면 스키마의 최신 버전이 응답의 페이로드에서 리턴됩니다.

curl 요청 예:

curl -u token:$APIKEY $URL/artifacts/my-schema

리소스 예:

{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}

스키마의 최신 버전을 가져오려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한
• 리더 역할은 검색된 스키마와 일치하는 스키마 리소스에 액세스할 수 있습니다.

스키마의 특정 버전 가져오기

특정 버전의 스키마를 검색하려면 /artifacts/{schema-id}/versions/{version} 엔드포인트에 GET 요청을 하십시오(여기서 {schema-id} 는 스키마의 ID이고, {version} 는 검색하려는 특정 버전의 버전 번호입니다). 성공하면 스키마의 지정된 버전이 응답의 페이로드에서 리턴됩니다.

curl 요청 예

curl -u token:$APIKEY $URL/artifacts/my-schema/versions/3

리소스 예:

{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}

스키마의 최신 버전을 가져오려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한
• 리더 역할은 검색된 스키마와 일치하는 스키마 리소스에 액세스할 수 있습니다.

스키마의 모든 버전 나열

레지스트리에 현재 저장되어 있는 스키마의 모든 버전을 나열하려면 /artifacts/{schema-id}/versions 엔드포인트에 GET 요청을 하십시오(여기서 {schema-id} 는 스키마의 ID입니다). 성공하면 스키마의 모든 현재 버전 번호 목록은 응답의 페이로드에서 리턴됩니다. jsonformat 매개변수를 사용하여 응답을 형식화할 수 있습니다 ( number 및 object 형식만 지원됨). 'number' (기본값) 를 지정하는 경우 응답은 아티팩트의 사용 가능한 버전에 해당하는 숫자 값의 배열입니다 (사용 불가능한 버전은 생략됨). 현재 엔드포인트가 생성하는 형식과 동일합니다. '오브젝트' 를 지정하는 경우 응답은 아티팩트의 버전을 나타내는 JSON 오브젝트의 배열을 포함하는 JSON 오브젝트입니다. 사용 및 사용 안함으로 설정된 버전 모두 어레이에 포함되어 있습니다.

curl 요청 예:

curl -u token:$APIKEY $URL/artifacts/my-schema/versions

or

curl -u token:$APIKEY $URL/artifacts/my-schema/versions?jsonformat=number

or

curl -u token:$APIKEY $URL/artifacts/my-schema/versions?jsonformat=object

jsonformat이 숫자이거나 제공되지 않은 경우의 응답 예 (기본값은 숫자):

[1,3,4,6,7]

jsonformat이 오브젝트인 경우 응답 예:

{"versions":[{"id":1,"state":"ENABLED"},{"id":2,"state":"DISABLED"},{"id":3,"state":"ENABLED"},{"id":4,"state":"ENABLED"},{"id":5,"state":"DISABLED"},{"id":6,"state":"ENABLED"},{"id":7,"state":"ENABLED"}],"count":7}

스키마의 사용 가능한 버전 목록을 가져오려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한
• 리더 역할은 검색된 스키마와 일치하는 스키마 리소스에 액세스할 수 있습니다.

스키마의 버전 삭제

스키마 버전은 /artifacts/{schema-id}/versions/{version} 엔드포인트에 DELETE 요청을 보내 레지스트리에서 삭제됩니다(여기서 {schema-id} 는 스키마의 ID이고, {version} 는 스키마 버전의 버전 번호입니다). 성공하면 비어 있는 요청과 204의 상태 코드(컨텐츠 없음)가 리턴됩니다. 스키마의 유일한 남은 버전을 삭제하면 스키마도 삭제됩니다.

curl 요청 예:

curl -u token:$APIKEY -X DELETE $URL/artifacts/my-schema/versions/3

스키마 버전을 삭제하려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한
• 관리자 역할은 삭제된 스키마와 일치하는 스키마 리소스에 대한 액세스 권한을 가집니다.

조치를 보고하기 위한 활동 추적 프로그램 이벤트가 생성됩니다. 자세한 정보는 Activity Tracker 이벤트를 참조하십시오.

스키마 버전의 특정 글로벌 고유 ID 가져오기

스키마 버전의 특정 글로벌 고유 ID를 검색하려면 /artifacts/{artifactId}/versions/{version}/meta 엔드포인트에 GET 요청을 하십시오(여기서 {artifactId} 는 아티팩트의 ID이고, {version} 는 검색하려는 특정 버전의 버전 번호입니다). 성공하면 스키마 버전의 특정 글로벌 고유 ID가 응답의 페이로드에 리턴됩니다.

curl 요청 예:

curl -u token:$APIKEY $URL/artifacts/9030f450-45fb-4750-bb37-771ad49ee0e8/versions/1/meta

리소스 예:

{"id":"9030f450-45fb-4750-bb37-771ad49ee0e8","type":"AVRO","version":1,"createdOn":1682340169202,"modifiedOn":1682340169202,"globalId":1}

스키마 버전의 글로벌 고유 ID를 가져오려면 최소한 다음 유형의 액세스가 모두 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한
• 리더 역할은 검색된 스키마와 일치하는 스키마 리소스에 액세스할 수 있습니다.

글로벌 규칙 업데이트

글로벌 호환성 규칙은 /rules/ {rule-type} 엔드포인트에 PUT 요청을 보내 업데이트할 수 있습니다(여기서 {rule-type} 는 업데이트할 글로벌 규칙의 유형을 식별합니다 - 현재 지원되는 유형은 COMPATIBILITY뿐입니다). 요청 본문에 새로운 규칙 구성을 포함시켜야 합니다. 요청에 성공하면 새로 업데이트 규칙 구성은 200(확인)의 상태 코드와 함께 응답의 페이로드에서 리턴됩니다.

요청 본문에 전송되는 JSON 문서에는 다음 속성이 있어야 합니다

curl 요청 예:

curl -u token:$APIKEY -X PUT $URL/rules/COMPATIBILITY -d '{"type":"COMPATIBILITY","config":"BACKWARD"}'

리소스 예:

{"type":"COMPATIBILITY","config":"BACKWARD"}

글로벌 규칙 구성을 업데이트하려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 관리자 역할 액세스 권한

조치를 보고하기 위한 활동 추적 프로그램 이벤트가 생성됩니다. 자세한 정보는 Activity Tracker 이벤트를 참조하십시오.

글로벌 규칙의 현재 값 가져오기

전역 규칙의 현재 값은 /rules/ {rule-type} 엔드포인트에 대한 GET 요청을 실행하여 검색할 수 있습니다(여기서 {rule-type} 는 검색할 전역 규칙의 유형입니다 - 현재 지원되는 유형은 COMPATIBILITY뿐입니다). 요청에 성공하면 현재 규칙 구성은 200(확인)의 상태 코드와 함께 응답의 페이로드에서 리턴됩니다.

curl 요청 예:

curl -u token:$APIKEY $URL/rules/COMPATIBILITY

리소스 예:

{"type":"COMPATIBILITY","config":"BACKWARD"}

글로벌 규칙 구성을 가져오려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한

스키마당 규칙 작성

규칙은 특정 스키마에 적용될 수 있으며, /artifacts/{schema-id}/rules 엔드포인트(여기서 {schema-id} 는 스키마의 ID임)에 POST 요청을 보내어 설정된 전역 규칙을 재정의할 수 있습니다. 요청 본문에 포함된 새 규칙의 유형과 값(현재 지원되는 유형은 COMPATIBILITY뿐임). 성공하면 비어 있는 요청과 204의 상태 코드(컨텐츠 없음)가 리턴됩니다.

curl 요청 예:

curl -u token:$APIKEY $URL/artifacts/my-schema/rules -d '{"type":"COMPATIBILITY","config":"FORWARD"}'

스키마당 규칙을 작성하려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한
• 관리자 역할 규칙이 적용되는 스키마 리소스에 대한 액세스 권한.

조치를 보고하기 위한 활동 추적 프로그램 이벤트가 생성됩니다. 자세한 정보는 Activity Tracker 이벤트를 참조하십시오.

스키마당 규칙 가져오기

특정 스키마에 적용되는 규칙 유형의 현재 값을 검색하려면 /artifacts/{schema-id}/rules/{rule-type} 엔드포인트로 GET 요청을 합니다(여기서 {schema-id} 는 스키마의 ID이고, {rule-type} 는 검색할 전역 규칙 유형입니다. 현재 지원되는 유형은 COMPATIBILITY뿐입니다). 요청에 성공하면 현재 규칙 값은 200(확인)의 상태 코드와 함께 응답의 페이로드에서 리턴됩니다.

curl 요청 예:

curl -u token:$APIKEY $URL/artifacts/my-schema/rules/COMPATIBILITY

리소스 예:

{"type":"COMPATIBILITY","config":"FORWARD"}

스키마당 규칙을 가져오려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한
• 규칙이 적용되는 스키마 리소스에 대한 독자 역할 액세스 권한

스키마당 규칙 업데이트

특정 스키마에 적용되는 규칙은 /artifacts/{schema-id}/rules/{rule-type} 엔드포인트에 PUT 요청을 함으로써 수정됩니다(여기서 {schema-id} 는 스키마의 ID이고, {rule-type} 는 검색할 글로벌 규칙의 유형입니다 - 현재 지원되는 유일한 유형은 COMPATIBILITY입니다). 요청에 성공하면 새로 업데이트 규칙 구성은 200(확인)의 상태 코드와 함께 응답의 페이로드에서 리턴됩니다.

curl 요청 예:

curl -u token:$APIKEY -X PUT $URL/artifacts/my-schema/rules/COMPATIBILITY -d '{"type":"COMPATIBILITY","config":"BACKWARD"}'

리소스 예:

{"type":"COMPATIBILITY","config":"BACKWARD"}

스키마당 규칙을 업데이트하려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한
• 규칙이 적용되는 스키마 리소스에 대한 관리자 역할 액세스 권한

조치를 보고하기 위한 활동 추적 프로그램 이벤트가 생성됩니다. 자세한 정보는 Activity Tracker 이벤트를 참조하십시오.

스키마당 규칙 삭제

특정 스키마에 적용된 규칙은 /artifacts/{schema-id}/rules/{rule-type} 엔드포인트에 DELETE 요청을 보내 삭제할 수 있습니다(여기서 {schema-id} 는 스키마의 ID이고, {rule-type} 는 검색할 글로벌 규칙의 유형입니다. 현재 지원되는 유형은 COMPATIBILITY뿐입니다). 요청에 성공하면 비어 있는 요청과 204의 상태 코드(컨텐츠 없음)가 리턴됩니다.

curl 요청 예:

curl -u token:$APIKEY -X DELETE $URL/artifacts/my-schema/rules/COMPATIBILITY

스키마당 규칙을 삭제하려면 최소 다음과 같은 역할 액세스 권한이 필요합니다.

• Event Streams 클러스터 리소스 유형에 대한 독자 역할 액세스 권한
• 규칙이 적용되는 스키마 리소스에 대한 관리자 역할 액세스 권한

조치를 보고하기 위한 활동 추적 프로그램 이벤트가 생성됩니다. 자세한 정보는 Activity Tracker 이벤트를 참조하십시오.