서비스 레지스트리 사용자 가이드

절차

1. Artifacts 탭에서 서비스 레지스트리에 저장된 아티팩트 목록을 찾아보거나 검색 문자열을 입력하여 아티팩트를 찾습니다. 이름, 그룹, 레이블 또는 글로벌 ID와 같은 특정 기준으로 검색할 목록에서 선택할 수 있습니다.

   그림 3.1. Service Registry 웹 콘솔의 아티팩트

   

2. 아티팩트를 클릭하여 다음 세부 정보를 확인합니다.

   • 개요: 아티팩트 이름, 아티팩트 ID, 글로벌 ID, 콘텐츠 ID, 라벨, 속성 등과 같은 아티팩트 버전 메타데이터를 표시합니다. 아티팩트 콘텐츠에 대해 구성할 수 있는 유효성 및 호환성에 대한 규칙도 표시합니다.
   • documentation(OpenAPI 및 AsyncAPI만 해당): 자동으로 생성된 REST API 문서를 표시합니다.
   • Content: 전체 아티팩트 콘텐츠의 읽기 전용 보기를 표시합니다. JSON 콘텐츠의 경우 JSON 또는 YAML 을 클릭하여 기본 형식을 표시할 수 있습니다.
   • references: 이 아티팩트에서 참조하는 모든 아티팩트의 읽기 전용 보기를 표시합니다. 이 아티팩트를 참조하는 아티팩트 보기를 클릭할 수도 있습니다.
3. 이 아티팩트의 추가 버전이 추가된 경우 페이지 헤더의 버전 목록에서 해당 버전을 선택할 수 있습니다.
4. 아티팩트 콘텐츠를 로컬 파일(예: my-openapi.json 또는 my-protobuf-schema.proto )에 저장하려면 페이지 끝에 있는 다운로드를 클릭합니다.

절차

1. Artifacts 탭에서 아티팩트 업로드 를 클릭하고 다음 세부 정보를 지정합니다.

   • Group & ID: 기본 빈 설정을 사용하여 아티팩트 ID를 자동으로 생성하고 기본 아티팩트 그룹에 아티팩트를 추가합니다. 또는 선택적 아티팩트 그룹 이름 또는 ID를 입력할 수 있습니다.
   • type : 기본 Auto-Detect 설정을 사용하여 아티팩트 유형을 자동으로 감지하거나 목록에서 아티팩트 유형을 선택합니다(예: Avro Schema 또는 OpenAPI ). 자동으로 감지할 수 없는 Kafka Connect Schema 아티팩트 유형을 수동으로 선택해야 합니다.

   • artifact: 다음 옵션 중 하나를 사용하여 아티팩트 위치를 지정합니다.

     • 파일에서 찾아보기를 클릭하고 파일을 선택하거나 파일을 드래그 앤 드롭합니다. 예를 들면 my-openapi.json 또는 my-schema.proto 입니다. 또는 텍스트 상자에 파일 내용을 입력할 수 있습니다.
     • URL에서: 유효하고 액세스 가능한 URL을 입력하고 Fetch 를 클릭합니다. 예: https://petstore3.swagger.io/api/v3/openapi.json.

2. 업로드 를 클릭하고 아티팩트 세부 정보를 확인합니다.

   • 개요: 아티팩트 이름, 아티팩트 ID, 글로벌 ID, 콘텐츠 ID, 라벨, 속성 등과 같은 아티팩트 버전 메타데이터를 표시합니다. 아티팩트 콘텐츠에 대해 구성할 수 있는 유효성 및 호환성에 대한 규칙도 표시합니다.
   • documentation(OpenAPI 및 AsyncAPI만 해당): 자동으로 생성된 REST API 문서를 표시합니다.
   • Content: 전체 아티팩트 콘텐츠의 읽기 전용 보기를 표시합니다. JSON 콘텐츠의 경우 JSON 또는 YAML 을 클릭하여 기본 형식을 표시할 수 있습니다.

   • references: 이 아티팩트에서 참조하는 모든 아티팩트의 읽기 전용 보기를 표시합니다. 이 아티팩트를 참조하는 아티팩트 보기를 클릭할 수도 있습니다. Service Registry Maven 플러그인 또는 REST API만 사용하여 아티팩트 참조를 추가할 수 있습니다.

     다음 예제에서는 OpenAPI 아티팩트 예제를 보여줍니다.

     그림 3.2. Service Registry 웹 콘솔의 아티팩트 세부 정보

     

3. Overview 탭에서 연필 편집 아이콘을 클릭하여 이름 또는 설명과 같은 아티팩트 메타데이터를 편집합니다.

   검색을 위해 쉼표로 구분된 레이블 목록을 입력하거나 아티팩트와 관련된 임의의 속성의 키-값 쌍을 추가할 수도 있습니다. 속성을 추가하려면 다음 단계를 수행합니다.

   1. 속성 추가를 클릭합니다.
   2. 키 이름과 값을 입력합니다.
   3. 처음 두 단계를 반복하여 여러 속성을 추가합니다.
   4. 저장을 클릭합니다.
4. 아티팩트 내용을 로컬 파일에 저장하려면 my-protobuf-schema.proto 또는 my-openapi.json.json 을 클릭하여 페이지 끝에 있는 다운로드를 클릭합니다.
5. 새 아티팩트 버전을 추가하려면 페이지 헤더에서 새 버전 업로드 를 클릭하고 드래그 앤 드롭을 클릭하거나 찾아보기를 클릭하여 파일을 업로드합니다(예: my-avro-schema.json 또는 my-openapi.json ).

6. 아티팩트를 삭제하려면 페이지 헤더에서 삭제 를 클릭합니다.

   주의

   아티팩트를 삭제하면 아티팩트 및 해당 버전이 모두 삭제되며 취소할 수 없습니다.

절차

1. Artifacts 탭에서 서비스 레지스트리의 아티팩트 목록을 찾아보거나 검색 문자열을 입력하여 아티팩트를 찾습니다. 아티팩트 이름, 그룹, 레이블 또는 글로벌 ID와 같은 특정 기준으로 검색할 목록에서 선택할 수 있습니다.
2. 아티팩트를 클릭하여 버전 세부 정보 및 콘텐츠 규칙을 확인합니다.

3. Artifact-specific 규칙에서 Enable 을 클릭하여 아티팩트 콘텐츠에 대한 유효성, 호환성 또는 무결성 규칙을 구성하고 목록에서 적절한 규칙 구성을 선택합니다. 예를 들어 Validity 규칙 의 경우 Full 을 선택합니다.

   그림 3.3. Service Registry 웹 콘솔에서 아티팩트 콘텐츠 규칙

   
4. 글로벌 규칙에 액세스하려면 글로벌 규칙 탭을 클릭합니다. Enable 을 클릭하여 모든 아티팩트 콘텐츠에 대한 글로벌 유효성, 호환성 또는 무결성 규칙을 구성하고 목록에서 적절한 규칙 구성을 선택합니다.
5. 아티팩트 규칙 또는 글로벌 규칙을 비활성화하려면 규칙 옆에 있는 trash 아이콘을 클릭합니다.

절차

1. Artifacts 탭에서 Service Registry에 저장된 아티팩트 목록을 찾아보거나 검색 문자열을 입력하여 특정 OpenAPI 아티팩트를 찾습니다. 이름, 그룹, 레이블 또는 글로벌 ID와 같은 기준으로 검색할 목록에서 선택할 수 있습니다.
2. 목록에서 OpenAPI 아티팩트를 클릭하여 세부 정보를 확인합니다.

3. 버전 메타데이터 섹션에서 클라이언트 SDK 생성 을 클릭하고 대화 상자에서 다음 설정을 구성합니다.

   • Language: 클라이언트 SDK를 생성할 프로그래밍 언어(예: Java )를 선택합니다.
   • 생성된 클라이언트 클래스 이름: 클라이언트 SDK의 클래스 이름을 입력합니다(예: MyJavaClientSDK).
   • 생성된 클라이언트 패키지 이름: 클라이언트 SDK의 패키지 이름을 입력합니다(예: io.my.example.sdk).

4. 고급 설정 표시를 클릭하여 포함 또는 제외할 선택적 쉼표로 구분된 경로 패턴 목록을 구성합니다.

   • 경로 패턴 포함: 클라이언트 SDK를 생성할 때 포함할 특정 경로를 입력합니다(예: **/.*, **/my-path/* ). 이 필드가 비어 있으면 모든 경로가 포함됩니다.

   • 경로 패턴 제외: 클라이언트 SDK를 생성할 때 제외할 특정 경로를 입력합니다(예: **/my-other-path/* ). 이 필드가 비어 있으면 경로가 제외되지 않습니다.

     그림 3.4. 서비스 레지스트리 웹 콘솔에서 Java 클라이언트 SDK 생성

     
5. 대화 상자에서 설정을 구성한 경우 생성 및 다운로드를 클릭합니다.
6. 대화 상자에 클라이언트 SDK의 파일 이름(예: my-client-java.zip )을 입력하고 저장을 클릭하여 다운로드합니다.

절차

1. Artifacts 탭에서 서비스 레지스트리에 저장된 아티팩트 목록을 찾아보거나 검색 문자열을 입력하여 아티팩트를 찾습니다. 이름, 그룹, 레이블 또는 글로벌 ID와 같은 기준으로 검색할 목록에서 선택할 수 있습니다.
2. 다시 할당할 아티팩트를 클릭합니다.
3. Version metadata 섹션에서 Owner 필드 옆에 있는 연필 아이콘을 클릭합니다.
4. 새 소유자 필드에서 계정 이름을 선택하거나 입력합니다.
5. 소유자 변경을 클릭합니다.

절차

1. 서비스 레지스트리 웹 콘솔에서 설정 탭을 클릭합니다.

2. 이 Service Registry 인스턴스에 구성할 설정을 선택합니다.

   표 3.1. 인증 설정

   설정	설명
   HTTP 기본 인증	인증이 이미 활성화된 경우에만 표시됩니다. Service Registry 사용자는 OAuth 외에도 HTTP 기본 인증을 사용하여 인증할 수 있습니다. 기본적으로 선택되지 않습니다.

   표 3.2. 권한 부여 설정

   설정	설명
   익명 읽기 액세스	인증이 이미 선택된 경우에만 표시됩니다. 선택한 경우 서비스 레지스트리는 인증 정보 없이 익명 사용자의 요청에 대한 읽기 전용 액세스 권한을 부여합니다. 이 설정은 이 인스턴스를 사용하여 스키마 또는 API를 외부에 게시하려는 경우에 유용합니다. 기본적으로 선택되지 않습니다.
   아티팩트 소유자 전용 권한 부여	인증이 이미 활성화된 경우에만 표시됩니다. 선택하면 아티팩트를 생성한 사용자만 해당 아티팩트를 수정할 수 있습니다. 기본적으로 선택되지 않습니다.
   아티팩트 그룹 소유자 전용 권한 부여	인증이 이미 활성화되어 있고 Artifact 소유자 전용 인증이 선택된 경우에만 표시됩니다. 선택하면 아티팩트 그룹을 생성한 사용자만 해당 아티팩트 그룹에 대한 쓰기 권한이 있습니다(예: 해당 그룹에서 아티팩트를 추가하거나 제거하는 등). 기본적으로 선택되지 않습니다.
   인증된 읽기 액세스	인증이 이미 활성화된 경우에만 표시됩니다. 선택한 경우 서비스 레지스트리는 사용자 역할에 관계없이 인증된 사용자의 요청에 최소한 읽기 전용 액세스 권한을 부여합니다. 기본적으로 선택되지 않습니다.

   표 3.3. 호환성 설정

   설정	설명
   레거시 ID 모드(호환 API)	선택하면 Confluent Schema Registry compatibility API가 contentId 대신 globalId 를 아티팩트 식별자로 사용합니다. 이 설정은 v1 Core Registry API를 기반으로 레거시 서비스 레지스트리 인스턴스에서 마이그레이션할 때 유용합니다. 기본적으로 선택되지 않습니다.

   표 3.4. 웹 콘솔 설정

   설정	설명
   다운로드 링크 만료	예를 들어 인스턴스에서 아티팩트 데이터를 내보낼 때 보안상의 이유로 만료되기 전에 .zip 다운로드 파일에 생성된 링크가 활성화되는 시간(초)입니다. 기본값은 30초입니다.
   UI 읽기 전용 모드	선택하면 서비스 레지스트리 웹 콘솔이 읽기 전용으로 설정되어 생성, 읽기, 업데이트 또는 삭제 작업이 방지됩니다. Core Registry API를 사용하여 변경한 내용은 이 설정의 영향을 받지 않습니다. 기본적으로 선택되지 않습니다.

   표 3.5. 추가 속성

   설정	설명
   아티팩트 버전 삭제	선택하는 경우 Core Registry API를 사용하여 이 인스턴스의 아티팩트 버전을 삭제할 수 있습니다. 기본적으로 선택되지 않습니다.

절차

1. 소스 서비스 레지스트리 인스턴스의 웹 콘솔에서 Artifacts 탭을 확인합니다.
2. 아티팩트 업로드 옆에 있는 옵션 아이콘(다시 수직점)을 클릭하고 Download all artifacts (.zip file) 를 선택하여 이 서비스 레지스트리 인스턴스의 데이터를 .zip 다운로드 파일로 내보냅니다.
3. 대상 서비스 레지스트리 인스턴스의 웹 콘솔에서 Artifacts 탭을 확인합니다.
4. 아티팩트 업로드 옆에 있는 옵션 아이콘을 클릭하고 여러 아티팩트 업로드 를 선택합니다.
5. 끌어서 놓거나 이전에 내보낸 .zip 다운로드 파일을 찾습니다.
6. 업로드 를 클릭하고 데이터를 가져올 때까지 기다립니다.

절차

1. /groups/{group}/artifacts 작업을 사용하여 서비스 레지스트리에 아티팩트를 추가합니다. 다음 예제 curl 명령은 공유 가격 애플리케이션에 대한 간단한 스키마 아티팩트를 추가합니다.

   $ curl -X POST -H "Content-Type: application/json; artifactType=AVRO" \
     -H "X-Registry-ArtifactId: share-price" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data '{"type":"record","name":"price","namespace":"com.example", \
      "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \
     MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts

   • 이 예제에서는 공유 오류의 아티팩트 ID가 있는 Apache Avro 스키마 아티팩트를 추가합니다. 고유한 아티팩트 ID를 지정하지 않으면 서비스 레지스트리가 UUID로 자동으로 생성합니다.
   • MY-REGISTRY-URL 은 서비스 레지스트리가 배포된 호스트 이름입니다. 예: my-cluster-service-registry-myproject.example.com.
   • 이 예제에서는 API 경로에서 my-group 의 그룹 ID를 지정합니다. 고유한 그룹 ID를 지정하지 않으면 API 경로에 ../groups/default 를 지정해야 합니다.

2. 응답에 아티팩트가 추가되었는지 확인하기 위해 예상 JSON 본문이 포함되어 있는지 확인합니다. 예를 들면 다음과 같습니다.

   {"createdBy":"","createdOn":"2021-04-16T09:07:51+0000","modifiedBy":"",
   "modifiedOn":"2021-04-16T09:07:51+0000","id":"share-price","version":"1",
   "type":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2}

   • 아티팩트를 추가할 때 버전이 지정되지 않았으므로 기본 버전 1 이 자동으로 생성됩니다.
   • 이는 서비스 레지스트리에 두 번째 아티팩트가 추가되었으므로 글로벌 ID 및 콘텐츠 ID의 값은 2 입니다.

3. API 경로에서 아티팩트 ID를 사용하여 서비스 레지스트리에서 아티팩트 콘텐츠를 검색합니다. 이 예에서 지정된 ID는 공유 값을 갖습니다.

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" \
    MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts/share-price
    {"type":"record","name":"price","namespace":"com.example",
     "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}

절차

1. /groups/{group}/artifacts 작업을 사용하여 레지스트리에 아티팩트 버전을 추가합니다. 다음 예제 curl 명령은 공유 가격 애플리케이션에 대한 간단한 아티팩트를 추가합니다.

   $ curl -X POST -H "Content-Type: application/json; artifactType=AVRO" \
     -H "X-Registry-ArtifactId: my-share-price" -H "X-Registry-Version: 1.1.1" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data '{"type":"record","name":" p","namespace":"com.example", \
      "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \
      MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts

   • 이 예제에서는 my-share- 의 아티팩트 ID와 1.1.1 버전의 Avro 스키마 아티팩트를 추가합니다. 버전을 지정하지 않으면 서비스 레지스트리가 기본 버전 1 을 자동으로 생성합니다.
   • MY-REGISTRY-URL 은 서비스 레지스트리가 배포된 호스트 이름입니다. 예: my-cluster-service-registry-myproject.example.com.
   • 이 예제에서는 API 경로에서 my-group 의 그룹 ID를 지정합니다. 고유한 그룹 ID를 지정하지 않으면 API 경로에 ../groups/default 를 지정해야 합니다.

2. 응답에 사용자 정의 아티팩트 버전이 추가되었는지 확인하기 위해 예상 JSON 본문이 포함되어 있는지 확인합니다. 예를 들면 다음과 같습니다.

   {"createdBy":"","createdOn":"2021-04-16T10:51:43+0000","modifiedBy":"",
   "modifiedOn":"2021-04-16T10:51:43+0000","id":"my-share-price","version":"1.1.1",
   "type":"AVRO","globalId":3,"state":"ENABLED","groupId":"my-group","contentId":3}

   • 아티팩트를 추가할 때 1.1.1 의 사용자 지정 버전이 지정되었습니다.
   • 이는 레지스트리에 세 번째 아티팩트가 추가되었으므로 글로벌 ID 및 콘텐츠 ID의 값은 3 입니다.

3. API 경로의 아티팩트 ID 및 버전을 사용하여 레지스트리에서 아티팩트 콘텐츠를 검색합니다. 이 예에서 지정된 ID는 my-share- expensive이며 버전은 1.1.1 입니다.

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" \
   MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts/my-share-price/versions/1.1.1
   {"type":"record","name":"price","namespace":"com.example",
     "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}

절차

1. /groups/{group}/artifacts 작업을 사용하여 중첩된 아티팩트 참조를 생성할 item Id 스키마 아티팩트를 추가합니다.

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts \
      -H "Content-Type: application/json; artifactType=AVRO" \
      -H "X-Registry-ArtifactId: ItemId" \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      --data '{"namespace": "com.example.common", "type": "record", "name": "ItemId", "fields":[{"name":"id", "type":"int"}]}'

   • 이 예제에서는 items Id 의 아티팩트 ID를 사용하여 Avro 스키마 아티팩트를 추가합니다. 고유한 아티팩트 ID를 지정하지 않으면 서비스 레지스트리가 UUID로 자동으로 생성합니다.
   • MY-REGISTRY-URL 은 서비스 레지스트리가 배포된 호스트 이름입니다. 예: my-cluster-service-registry-myproject.example.com.
   • 이 예제에서는 API 경로에서 my-group 의 그룹 ID를 지정합니다. 고유한 그룹 ID를 지정하지 않으면 API 경로에 ../groups/default 를 지정해야 합니다.

2. 응답에 아티팩트가 추가되었는지 확인하기 위해 예상 JSON 본문이 포함되어 있는지 확인합니다. 예를 들면 다음과 같습니다.

   {"name":"ItemId","createdBy":"","createdOn":"2022-04-14T10:50:09+0000","modifiedBy":"","modifiedOn":"2022-04-14T10:50:09+0000","id":"ItemId","version":"1","type":"AVRO","globalId":1,"state":"ENABLED","groupId":"my-group","contentId":1,"references":[]}

3. /groups/{group}/artifacts 작업을 사용하여 item Id 스키마에 아티팩트 참조를 포함하는 item 스키마 아티팩트를 추가합니다.

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts \
   -H 'Content-Type: application/create.extended+json' \
   -H "X-Registry-ArtifactId: Item" \
   -H 'X-Registry-ArtifactType: AVRO' \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   --data-raw '{
       "content": "{\r\n \"namespace\":\"com.example.common\",\r\n  \"name\":\"Item\",\r\n  \"type\":\"record\",\r\n  \"fields\":[\r\n   {\r\n  \"name\":\"itemId\",\r\n   \"type\":\"com.example.common.ItemId\"\r\n        }\r\n    ]\r\n}",
       "references": [
           {
               "groupId": "my-group",
               "artifactId": "ItemId",
               "name": "com.example.common.ItemId",
               "version": "1"
           }
       ]
   }'

   • 아티팩트 참조의 경우 application/json 콘텐츠 유형을 확장하는 application/create.extended+json 의 사용자 정의 콘텐츠 유형을 지정해야 합니다.

4. 응답에 아티팩트가 참조로 생성되었는지 확인하기 위해 예상 JSON 본문이 포함되어 있는지 확인합니다. 예를 들면 다음과 같습니다.

   {"name":"Item","createdBy":"","createdOn":"2022-04-14T11:52:15+0000","modifiedBy":"","modifiedOn":"2022-04-14T11:52:15+0000","id":"Item","version":"1","type":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2, "references":[{"artifactId":"ItemId","groupId":"my-group","name":"ItemId","version":"1"}] }

5. 참조를 포함하는 아티팩트의 글로벌 ID를 지정하여 서비스 레지스트리에서 아티팩트 참조를 검색합니다. 이 예에서 지정된 글로벌 ID는 2 입니다.

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v2/ids/globalIds/2/references

6. 응답에 이 아티팩트 참조에 필요한 JSON 본문이 포함되어 있는지 확인합니다. 예를 들면 다음과 같습니다.

   [{"groupId":"my-group","artifactId":"ItemId","version":"1","name":"com.example.common.ItemId"}]

절차

1. 기존 소스 서비스 레지스트리 인스턴스에서 서비스 레지스트리 데이터를 내보냅니다.

   $ curl MY-REGISTRY-URL/apis/registry/v2/admin/export \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --output my-registry-data.zip

   MY-REGISTRY-URL 은 소스 서비스 레지스트리가 배포된 호스트 이름입니다. 예: my-cluster-source-registry-myproject.example.com.

2. 레지스트리 데이터를 대상 서비스 레지스트리 인스턴스로 가져옵니다.

   $ curl -X POST "MY-REGISTRY-URL/apis/registry/v2/admin/import" \
     -H "Content-Type: application/zip" -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data-binary @my-registry-data.zip

   MY-REGISTRY-URL 은 대상 서비스 레지스트리가 배포된 호스트 이름입니다. 예: my-cluster-target-registry-myproject.example.com.

절차

1. apicurio-registry-maven-plugin 을 사용하여 아티팩트를 등록하도록 Maven pom.xml 파일을 업데이트합니다. 다음 예제에서는 Apache Avro 및 GraphQL 스키마를 등록하는 방법을 보여줍니다.

   <plugin>
     <groupId>io.apicurio</groupId>
     <artifactId>apicurio-registry-maven-plugin</artifactId>
     <version>${apicurio.version}</version>
     <executions>
         <execution>
           <phase>generate-sources</phase>
           <goals>
               <goal>register</goal>  1
           </goals>
           <configuration>
               <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
               <authServerUrl>MY-AUTH-SERVER</authServerUrl>
               <clientId>MY-CLIENT-ID</clientId>
               <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
               <artifacts>
                   <artifact>
                       <groupId>TestGroup</groupId> 4
                       <artifactId>FullNameRecord</artifactId>
                       <file>${project.basedir}/src/main/resources/schemas/record.avsc</file>
                       <ifExists>FAIL</ifExists>
                   </artifact>
                   <artifact>
                       <groupId>TestGroup</groupId>
                       <artifactId>ExampleAPI</artifactId> 5
                       <type>GRAPHQL</type>
                       <file>${project.basedir}/src/main/resources/apis/example.graphql</file>
                       <ifExists>RETURN_OR_UPDATE</ifExists>
                       <canonicalize>true</canonicalize>
                   </artifact>
               </artifacts>
           </configuration>
       </execution>
     </executions>
    </plugin>

   1

   스키마 아티팩트를 서비스 레지스트리에 업로드하는 실행 대상으로 register 를 지정합니다.

   2

   ../apis/registry/v2 끝점을 사용하여 서비스 레지스트리 URL을 지정합니다.

   3

   인증이 필요한 경우 인증 서버 및 클라이언트 자격 증명을 지정할 수 있습니다.

   4

   서비스 레지스트리 아티팩트 그룹 ID를 지정합니다. 고유한 그룹 ID를 사용하지 않으려면 기본 그룹을 지정할 수 있습니다.

   5

   지정된 그룹 ID, 아티팩트 ID 및 위치를 사용하여 여러 아티팩트를 등록할 수 있습니다.

2. 예를 들어 mvn package 명령을 사용하여 Maven 프로젝트를 빌드합니다.

절차

1. apicurio-registry-maven-plugin 을 사용하여 아티팩트를 다운로드하도록 Maven pom.xml 파일을 업데이트합니다. 다음 예제에서는 Apache Avro 및 GraphQL 스키마를 다운로드하는 방법을 보여줍니다.

   <plugin>
     <groupId>io.apicurio</groupId>
     <artifactId>apicurio-registry-maven-plugin</artifactId>
     <version>${apicurio.version}</version>
     <executions>
       <execution>
         <phase>generate-sources</phase>
         <goals>
           <goal>download</goal> 1
         </goals>
         <configuration>
             <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
             <authServerUrl>MY-AUTH-SERVER</authServerUrl>
             <clientId>MY-CLIENT-ID</clientId>
             <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
             <artifacts>
                 <artifact>
                     <groupId>TestGroup</groupId> 4
                     <artifactId>FullNameRecord</artifactId> 5
                     <file>${project.build.directory}/classes/record.avsc</file>
                     <overwrite>true</overwrite>
                 </artifact>
                 <artifact>
                     <groupId>TestGroup</groupId>
                     <artifactId>ExampleAPI</artifactId>
                     <version>1</version>
                     <file>${project.build.directory}/classes/example.graphql</file>
                     <overwrite>true</overwrite>
                 </artifact>
             </artifacts>
         </configuration>
       </execution>
     </executions>
   </plugin>

   1

   실행 대상으로 다운로드를 지정합니다.

   2

   ../apis/registry/v2 끝점을 사용하여 서비스 레지스트리 URL을 지정합니다.

   3

   인증이 필요한 경우 인증 서버 및 클라이언트 자격 증명을 지정할 수 있습니다.

   4

   서비스 레지스트리 아티팩트 그룹 ID를 지정합니다. 고유 그룹을 사용하지 않으려면 기본 그룹을 지정할 수 있습니다.

   5

   아티팩트 ID를 사용하여 여러 아티팩트를 지정된 디렉터리에 다운로드할 수 있습니다.

2. 예를 들어 mvn package 명령을 사용하여 Maven 프로젝트를 빌드합니다.

절차

1. apicurio-registry-maven-plugin 을 사용하여 아티팩트를 테스트하도록 Maven pom.xml 파일을 업데이트합니다. 다음 예제에서는 Apache Avro 스키마를 테스트하는 방법을 보여줍니다.

   <plugin>
     <groupId>io.apicurio</groupId>
     <artifactId>apicurio-registry-maven-plugin</artifactId>
     <version>${apicurio.version}</version>
     <executions>
         <execution>
           <phase>generate-sources</phase>
           <goals>
               <goal>test-update</goal>  1
           </goals>
           <configuration>
               <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
               <authServerUrl>MY-AUTH-SERVER</authServerUrl>
               <clientId>MY-CLIENT-ID</clientId>
               <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
               <artifacts>
                   <artifact>
                       <groupId>TestGroup</groupId> 4
                       <artifactId>FullNameRecord</artifactId>
                       <file>${project.basedir}/src/main/resources/schemas/record.avsc</file> 5
                   </artifact>
               </artifacts>
           </configuration>
       </execution>
     </executions>
    </plugin>

   1

   스키마 아티팩트를 테스트하기 위한 실행 목표로 test-update 를 지정합니다.

   2

   ../apis/registry/v2 끝점을 사용하여 서비스 레지스트리 URL을 지정합니다.

   3

   인증이 필요한 경우 인증 서버 및 클라이언트 자격 증명을 지정할 수 있습니다.

   4

   서비스 레지스트리 아티팩트 그룹 ID를 지정합니다. 고유 그룹을 사용하지 않으려면 기본 그룹을 지정할 수 있습니다.

   5

   아티팩트 ID를 사용하여 지정된 디렉터리에서 여러 아티팩트를 테스트할 수 있습니다.

2. 예를 들어 mvn package 명령을 사용하여 Maven 프로젝트를 빌드합니다.

절차

1. apicurio-registry-maven-plugin 을 사용하도록 Maven pom.xml 파일을 업데이트하여 Exchange 스키마에 대한 중첩된 참조가 포함된 skopeo Key 스키마를 등록합니다.

   <plugin>
       <groupId>io.apicurio</groupId>
       <artifactId>apicurio-registry-maven-plugin</artifactId>
       <version>${apicurio-registry.version}</version>
       <executions>
           <execution>
               <phase>generate-sources</phase>
               <goals>
                   <goal>register</goal> 1
               </goals>
               <configuration>
                   <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
                   <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                   <clientId>MY-CLIENT-ID</clientId>
                   <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
                   <artifacts>
                       <artifact>
                           <groupId>test-group</groupId> 4
                           <artifactId>TradeKey</artifactId>
                           <version>2.0</version>
                           <type>AVRO</type>
                           <file>
                               ${project.basedir}/src/main/resources/schemas/TradeKey.avsc
                           </file>
                           <ifExists>RETURN_OR_UPDATE</ifExists>
                           <canonicalize>true</canonicalize>
                           <references>
                               <reference> 5
                                   <name>com.kubetrade.schema.common.Exchange</name>
                                   <groupId>test-group</groupId>
                                   <artifactId>Exchange</artifactId>
                                   <version>2.0</version>
                                   <type>AVRO</type>
                                   <file>
                                       ${project.basedir}/src/main/resources/schemas/Exchange.avsc
                                   </file>
                                   <ifExists>RETURN_OR_UPDATE</ifExists>
                                   <canonicalize>true</canonicalize>
                               </reference>
                           </references>
                       </artifact>
                   </artifacts>
               </configuration>
           </execution>
       </executions>
   </plugin>

   1

   서비스 레지스트리에 스키마 아티팩트를 업로드하려면 register 를 실행 목표로 지정합니다.

   2

   ../apis/registry/v2 끝점을 사용하여 서비스 레지스트리 URL을 지정합니다.

   3

   인증이 필요한 경우 인증 서버 및 클라이언트 자격 증명을 지정할 수 있습니다.

   4

   서비스 레지스트리 아티팩트 그룹 ID를 지정합니다. 고유한 그룹 ID를 사용하지 않으려면 기본 그룹을 지정할 수 있습니다.

   5

   그룹 ID, 아티팩트 ID, 버전, 유형 및 위치를 사용하여 서비스 레지스트리 아티팩트 참조를 지정합니다. 이러한 방식으로 여러 아티팩트 참조를 등록할 수 있습니다.

2. 예를 들어 mvn package 명령을 사용하여 Maven 프로젝트를 빌드합니다.

절차

1. apicurio-registry-maven-plugin 을 사용하도록 Maven pom.xml 파일을 업데이트하여 Exchange 스키마에 대한 중첩된 참조가 포함된 skopeo Key 스키마를 등록합니다.

   <plugin>
       <groupId>io.apicurio</groupId>
       <artifactId>apicurio-registry-maven-plugin</artifactId>
       <version>${apicurio-registry.version}</version>
       <executions>
           <execution>
               <phase>generate-sources</phase>
               <goals>
                   <goal>register</goal> 1
               </goals>
               <configuration>
                   <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> 2
                   <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                   <clientId>MY-CLIENT-ID</clientId>
                   <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
                   <artifacts>
                       <artifact>
                           <groupId>test-group</groupId> 4
                           <artifactId>TradeKey</artifactId>
                           <version>2.0</version>
                           <type>AVRO</type>
                           <file>
                               ${project.basedir}/src/main/resources/schemas/TradeKey.avsc 5
                           </file>
                           <ifExists>RETURN_OR_UPDATE</ifExists>
                           <canonicalize>true</canonicalize>
                           <analyzeDirectory>true</analyzeDirectory> 6
                       </artifact>
                   </artifacts>
               </configuration>
           </execution>
       </executions>
   </plugin>

   1

   서비스 레지스트리에 스키마 아티팩트를 업로드하려면 register 를 실행 목표로 지정합니다.

   2

   ../apis/registry/v2 끝점을 사용하여 서비스 레지스트리 URL을 지정합니다.

   3

   인증이 필요한 경우 인증 서버 및 클라이언트 자격 증명을 지정할 수 있습니다.

   4

   참조가 포함된 상위 아티팩트 그룹 ID를 지정합니다. 고유한 그룹 ID를 사용하지 않으려면 기본 그룹을 지정할 수 있습니다.

   5

   상위 아티팩트 파일의 위치를 지정합니다. 참조된 모든 아티팩트도 동일한 디렉터리에 있어야 합니다.

   6

   동일한 디렉터리의 아티팩트에 대한 모든 참조를 자동으로 탐지하고 등록하려면 < analyzeDirectory > 옵션을 true로 설정합니다. 이러한 방식으로 여러 아티팩트 참조를 등록할 수 있습니다.

2. 예를 들어 mvn package 명령을 사용하여 Maven 프로젝트를 빌드합니다.

절차

1. Maven 프로젝트에 다음 종속성을 추가합니다.

   <dependency>
       <groupId>io.apicurio</groupId>
       <artifactId>apicurio-registry-client</artifactId>
       <version>${apicurio-registry.version}</version>
   </dependency>

2. 다음과 같이 서비스 레지스트리 클라이언트를 생성합니다.

   public class ClientExample {
   
       public static void main(String[] args) throws Exception {
          // Create a registry client
          String registryUrl = "https://my-registry.my-domain.com/apis/registry/v2";
          RegistryClient client = RegistryClientFactory.create(registryUrl);
       }
   }

   • https://my-registry.my-domain.com 서비스 레지스트리 URL 예를 지정하면 클라이언트는 /apis/registry/v2 를 자동으로 추가합니다.
   • 서비스 레지스트리 클라이언트를 생성할 때 추가 옵션은 다음 섹션의 Java 클라이언트 구성을 참조하십시오.

1. 간단한 Avro 스키마 아티팩트.
2. 서비스 레지스트리를 노출하는 OpenShift 경로 이름입니다.

1. 스키마 아티팩트를 레지스트리에 업로드하는 실행 대상으로 register 를 지정합니다.
2. ../apis/registry/v2 끝점을 사용하여 서비스 레지스트리 URL을 지정합니다.
3. 서비스 레지스트리 아티팩트 그룹 ID를 지정합니다.
4. 지정된 그룹 ID, 아티팩트 ID 및 위치를 사용하여 여러 아티팩트를 업로드할 수 있습니다.

1. 두 개 이상의 URL 노드에 대해 속성을 등록할 수 있습니다.
2. 아티팩트 ID에 따라 스키마가 이미 존재하는지 확인합니다.

절차

1. 서비스 레지스트리의 URL로 클라이언트를 구성합니다. 예를 들면 다음과 같습니다.

   String registryUrl = "https://registry.example.com/apis/registry/v2";
   Properties props = new Properties();
   props.putIfAbsent(SerdeConfig.REGISTRY_URL, registryUrl);

2. Service Registry deserializer를 사용하여 클라이언트를 구성합니다. 예를 들면 다음과 같습니다.

   // Configure Kafka settings
   props.putIfAbsent(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, SERVERS);
   props.putIfAbsent(ConsumerConfig.GROUP_ID_CONFIG, "Consumer-" + TOPIC_NAME);
   props.putIfAbsent(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, "true");
   props.putIfAbsent(ConsumerConfig.AUTO_COMMIT_INTERVAL_MS_CONFIG, "1000");
   props.putIfAbsent(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
   // Configure deserializer settings
   props.putIfAbsent(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG,
       AvroKafkaDeserializer.class.getName()); 1
   props.putIfAbsent(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG,
       AvroKafkaDeserializer.class.getName()); 2

   • 1. Service Registry에서 제공하는 deserializer입니다.
   • 2. deserialization은 Apache Avro JSON 형식입니다.

절차

1. 서비스 레지스트리의 URL로 클라이언트를 구성합니다. 예를 들면 다음과 같습니다.

   String registryUrl = "https://registry.example.com/apis/registry/v2";
   Properties props = new Properties();
   props.putIfAbsent(SerdeConfig.REGISTRY_URL, registryUrl);

2. 직렬화자를 사용하여 클라이언트를 구성하고 서비스 레지스트리에서 스키마를 조회하는 전략을 구성합니다. 예를 들면 다음과 같습니다.

   props.put(CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG, "my-cluster-kafka-bootstrap:9092");
   props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, AvroKafkaSerializer.class.getName()); 1
   props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, AvroKafkaSerializer.class.getName()); 2
   props.put(SerdeConfig.FIND_LATEST_ARTIFACT, Boolean.TRUE); 3

   • 1. 서비스 레지스트리에서 제공하는 메시지 키의 serializer입니다.
   • 2. Service Registry에서 제공하는 메시지 값에 대한 serializer입니다.
   • 3. lookup 전략으로 스키마의 글로벌 ID를 찾습니다.

절차

1. 서비스 레지스트리 URL을 사용하여 Java 클라이언트를 생성하고 구성합니다.

   String registryUrl = "https://registry.example.com/apis/registry/v2";
   
   RegistryService client = RegistryClient.cached(registryUrl);

2. serializer 및 deserializer를 구성합니다.

   Serializer<LogInput> serializer = new AvroKafkaSerializer<LogInput>(); 1
   
   Deserializer<LogInput> deserializer = new AvroKafkaDeserializer <LogInput>(); 2
   
   Serde<LogInput> logSerde = Serdes.serdeFrom(
       serializer,
       deserializer
   );
   
   Map<String, Object> config = new HashMap<>();
   config.put(SerdeConfig.REGISTRY_URL, registryUrl);
   config.put(AvroKafkaSerdeConfig.USE_SPECIFIC_AVRO_READER, true);
   logSerde.configure(config, false); 3

   • 1. 서비스 레지스트리에서 제공하는 Avro serializer입니다.
   • 2. 서비스 레지스트리에서 제공하는 Avro deserializer입니다.
   • 3. Avro 형식으로 서비스 레지스트리 URL과 Avro 리더를 구성합니다.

3. Kafka Streams 클라이언트를 생성합니다.

   KStream<String, LogInput> input = builder.stream(
       INPUT_TOPIC,
       Consumed.with(Serdes.String(), logSerde)
   );

1. 서비스 레지스트리의 필수 URL입니다.
2. 다른 ID 형식을 지원하고 서비스 레지스트리 SerDe 서비스와 호환되도록 ID 처리를 확장합니다. 예를 들어 기본 ID 형식을 Long 에서 Integer 로 변경하면 Confluent ID 형식이 지원됩니다.
3. Confluent ID의 처리를 단순화합니다. true 로 설정하면 글로벌 ID 조회에 Integer 가 사용됩니다. ID_HANDLER 옵션과 함께 설정을 사용해서는 안 됩니다.

1. 아티팩트 확인자 전략과 Kafka SerDe 및 아티팩트 ID 간 매핑을 구현하는 Java 클래스입니다. 기본값은 주제 ID 전략입니다. 이 클래스는 serializer 클래스에서만 사용됩니다.
2. 스키마 확인자를 구현하는 Java 클래스입니다. 기본값은 DefaultSchemaResolver 입니다. 이는 serializer 및 deserializer 클래스에서 사용됩니다.

1. Service Registry Kafka 변환기와 함께 사용하는 데 필요한 직렬화기입니다.
2. Service Registry Kafka 변환기와 함께 사용하는 데 필요한 역직렬러입니다.