Service Registry 用户指南

流程

1. 在 Artifacts 选项卡中，浏览存储在 Service Registry 中的工件列表，或者输入搜索字符串以查找工件。您可以从列表中选择按特定条件搜索，如名称、组、标签或全局 ID。

   图 3.1. Service Registry web 控制台中的工件

   

   View larger image

   

2. 点工件查看以下详情：

   • 概述 ：显示工件版本元数据，如工件名称、工件 ID、全局 ID、内容 ID、标签、属性等。另外，也显示可针对工件内容配置的有效性和兼容性的规则。
   • 文档 （仅限 OpenAPI 和 AsyncAPI）：显示自动生成的 REST API 文档。
   • 内容 ：显示完整工件内容的只读视图。对于 JSON 内容，您可以点 JSON 或 YAML 来显示您首选的格式。
   • 参考 ：显示此工件引用的所有工件的只读视图。您还可以单击 引用此工件的 View 工件。
3. 如果添加了此工件的额外版本，您可以从页面标头中的 Version 列表中选择它们。
4. 要将工件内容保存到本地文件，如 my-openapi.json 或 my-protobuf-schema.proto，然后点击页面末尾的 Download。

流程

1. 在 Artifacts 选项卡中，点 Upload artifact，并指定以下详情：

   • Group & ID ：使用默认空设置自动生成工件 ID，并将工件 添加到默认 工件组中。或者，您可以输入可选的工件组名称或 ID。
   • 类型 ：使用默认 Auto-Detect 设置来自动检测工件类型，或者从列表中选择工件类型，如 Avro Schema 或 OpenAPI。您必须手动选择 Kafka Connect Schema 工件类型，无法自动检测到。

   • 工件 ：使用以下选项之一指定工件位置：

     • 从文件: 点 Browse，然后选择一个文件，或者拖放文件。例如，my-openapi.json 或 my-schema.proto。或者，您可以在文本框中输入文件内容。
     • 从 URL ：输入有效且可访问的 URL，然后单击 Fetch。例如： https://petstore3.swagger.io/api/v3/openapi.json。

2. 点 Upload 并查看工件详情：

   • 概述 ：显示工件版本元数据，如工件名称、工件 ID、全局 ID、内容 ID、标签、属性等。另外，也显示可针对工件内容配置的有效性和兼容性的规则。
   • 文档 （仅限 OpenAPI 和 AsyncAPI）：显示自动生成的 REST API 文档。
   • 内容 ：显示完整工件内容的只读视图。对于 JSON 内容，您可以点 JSON 或 YAML 来显示您首选的格式。

   • 参考 ：显示此工件引用的所有工件的只读视图。您还可以单击 引用此工件的 View 工件。您只能使用 Service Registry Maven 插件或 REST API 添加工件引用。

     以下示例显示了 OpenAPI 工件示例：

     图 3.2. Service Registry web 控制台中的工件详情

     

     View larger image

     

3. 在 Overview 选项卡上，点 Edit 铅笔图标编辑工件元数据，如 name 或 description。

   您还可以输入一个可选的、以逗号分隔的标签列表来搜索，或者添加与工件关联的任意属性的键值对。要添加属性，请执行以下步骤：

   1. 单击 Add property。
   2. 输入键名称和值。
   3. 重复前两个步骤来添加多个属性。
   4. 点击 Save。
4. 要将工件内容保存到本地文件，如 my-protobuf-schema.proto 或 my-openapi.json，请单击页面末尾的 Download。
5. 要添加新的工件版本，点页面标头中的 Upload new version，拖放或点 Browse 上传文件，如 my-avro-schema.json 或 my-openapi.json。

6. 要删除工件，请在页面标头中点 Delete。

   警告

   删除工件会删除工件及其所有版本，且无法撤销。

流程

1. 在 Artifacts 选项卡中，浏览 Service Registry 中的工件列表，或者输入搜索字符串来查找工件。您可以从列表中选择按特定条件搜索，如工件名称、组、标签或全局 ID。
2. 点工件查看其版本详情和内容规则。

3. 在 特定于 工件的规则中，点 Enable 为工件内容配置有效性、兼容性或完整性规则，并从列表中选择适当的规则配置。例如，对于 Validity 规则，请选择 Full。

   图 3.3. Service Registry web 控制台中的工件内容规则

   

   View larger image

   
4. 要访问全局规则，请点 Global rules 选项卡。点 Enable 为所有工件内容配置全局有效性、兼容性或完整性规则，然后从列表中选择适当的规则配置。
5. 要禁用工件规则或全局规则，请点规则旁边的垃圾箱图标。

流程

1. 在 Artifacts 选项卡中，浏览存储在 Service Registry 中的工件列表，或者输入搜索字符串来查找特定的 OpenAPI 工件。您可以从列表中选择按名称、组、标签或全局 ID 等条件进行搜索。
2. 点列表中的 OpenAPI 工件来查看其详情。

3. 在 Version metadata 部分中，点 Generate client SDK，并在对话框中配置以下设置：

   • 语言 ：选择生成客户端 SDK 的编程语言，例如 Java。
   • 生成的客户端类名称 ：输入客户端 SDK 的类名称，如 MyJavaClientSDK。
   • 生成的客户端软件包名称 ：输入客户端 SDK 的软件包名称，例如 io.my.example.sdk

4. 点 Show advanced settings 配置可选的以逗号分隔的路径模式列表来包含或排除：

   • 包括路径模式 ：输入生成客户端 SDK 时要包括的具体路径，例如： **/ netobserv, **/my-path8:0:1::。如果此字段为空，则会包括所有路径。

   • 排除路径模式 ：在生成客户端 SDK 时输入要排除的具体路径，例如： beyond /my-other-pathAttr。如果此字段为空，则不会排除任何路径。

     图 3.4. 在 Service Registry web 控制台中生成 Java 客户端 SDK

     

     View larger image

     
5. 当您在对话框中配置了设置后，点 Generate and download。
6. 在对话框中输入 client SDK 的文件名，如 my-client-java.zip，然后单击 Save 以下载。

流程

1. 在 Artifacts 选项卡中，浏览存储在 Service Registry 中的工件列表，或者输入搜索字符串以查找工件。您可以从列表中选择按名称、组、标签或全局 ID 等条件进行搜索。
2. 点您要重新分配的工件。
3. 在 Version metadata 部分中，单击 Owner 字段旁边的铅笔图标。
4. 在 New owner 字段中，选择或输入帐户名称。
5. 单击 更改所有者。

流程

1. 在 Service Registry web 控制台中点 Settings 选项卡。

2. 选择您要为此 Service Registry 实例配置的设置：

   Expand

   表 3.1. 身份验证设置

   设置	描述
   HTTP 基本身份验证	仅在已经启用身份验证时显示。选择后，除了 OAuth 外，Service Registry 用户可以使用 HTTP 基本身份验证进行身份验证。默认不选择。

   Show more
   Expand

   表 3.2. 授权设置

   设置	描述
   匿名读取访问	仅在已经选择身份验证时显示。选择后，Service Registry 会为没有任何凭证的匿名用户授予只读访问权限。如果要使用此实例在外部发布模式或 API，则此设置很有用。默认不选择。
   工件仅所有者授权	仅在已经启用身份验证时显示。选择后，只有创建工件的用户才能修改该工件。默认不选择。
   工件组所有者-仅限授权	仅在已经启用身份验证并选择了 Artifact owner-only 授权 时显示。选择后，只有创建工件组的用户具有对该工件组的写入权限，例如在该组中添加或删除工件。默认不选择。
   经过身份验证的读访问权限	仅在已经启用身份验证时显示。选择后，无论其用户角色是什么，Service Registry 会至少授予来自任何经过身份验证的用户的请求的只读访问权限。默认不选择。

   Show more
   Expand

   表 3.3. 兼容性设置

   设置	描述
   旧 ID 模式（兼容性 API）	选择后，Confluent Schema Registry 兼容性 API 使用 globalId 而不是 contentId 作为工件标识符。当从基于 v1 Core Registry API 的传统 Service Registry 实例迁移时，此设置很有用。默认不选择。

   Show more
   Expand

   表 3.4. Web 控制台设置

   设置	描述
   下载链接到期	生成的到 .zip 下载文件的链接秒数在因为安全原因（例如，从实例导出工件数据时）之前处于活跃状态。默认值为 30 秒。
   UI 只读模式	选择后，Service Registry web 控制台被设置为 read-only，从而导致创建、读取、更新或删除操作。使用 Core Registry API 所做的更改不受此设置的影响。默认不选择。

   Show more
   Expand

   表 3.5. 其他属性

   设置	描述
   删除工件版本	选择后，用户可以使用 Core Registry API 删除此实例中的工件版本。默认不选择。

   Show more

流程

1. 在源 Service Registry 实例的 web 控制台中，查看 Artifacts 选项卡。
2. 点 Upload artifact 旁的选项图标（三个垂直点），然后选择 Download all artifacts (.zip file)，将这个 Service Registry 实例的数据导出到 .zip 下载文件。
3. 在目标 Service Registry 实例的 web 控制台中，查看 Artifacts 选项卡。
4. 点 Upload artifact 旁的选项图标，然后选择 Upload multiple artifacts。
5. 拖放或浏览到您之前导出的 .zip 下载文件。
6. 点 Upload，并等待数据导入。

流程

1. 使用 /groups/{group}/artifacts 操作向 Service Registry 添加工件。以下示例 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

   Copy to Clipboard Toggle word wrap
   • 这个示例添加了一个 Apache Avro 模式工件，工件 ID 为 share-price。如果没有指定唯一的工件 ID，Service Registry 会自动生成一个 UUID。
   • MY-REGISTRY-URL 是在其上部署 Service Registry 的主机名。例如： 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}

   Copy to Clipboard Toggle word wrap
   • 添加工件时没有指定 version，因此会自动创建默认版本 1。
   • 这是添加到 Service Registry 的第二个工件，因此全局 ID 和内容 ID 的值为 2。

3. 使用 API 路径中的工件 ID 从 Service Registry 检索工件内容。在本例中，指定的 ID 是 share-price:

   $ 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"}]}

   Copy to Clipboard Toggle word wrap

流程

1. 使用 /groups/{group}/artifacts 操作在 registry 中添加工件版本。以下示例 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

   Copy to Clipboard Toggle word wrap
   • 这个示例添加了一个 Avro 模式工件，工件 ID 为 my-share-price 和 1.1.1 版本。如果没有指定版本，Service Registry 会自动生成默认版本 1。
   • MY-REGISTRY-URL 是在其上部署 Service Registry 的主机名。例如： 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}

   Copy to Clipboard Toggle word wrap
   • 在添加工件时，指定了 1.1.1 的自定义版本。
   • 这是添加到 registry 中的第三个工件，因此全局 ID 和内容 ID 的值为 3。

3. 使用 API 路径中的工件 ID 和版本，从 registry 检索工件内容。在本例中，指定的 ID 是 my-share-price，版本为 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"}]}

   Copy to Clipboard Toggle word wrap

流程

1. 添加 ItemId 模式工件，您要使用 /groups/{group}/artifacts 操作创建嵌套工件引用：

   $ 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"}]}'

   Copy to Clipboard Toggle word wrap
   • 这个示例添加了一个 Avro schema 工件，工件 ID 为 ItemId。如果没有指定唯一的工件 ID，Service Registry 会自动生成一个 UUID。
   • MY-REGISTRY-URL 是在其上部署 Service Registry 的主机名。例如： 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":[]}

   Copy to Clipboard Toggle word wrap

3. 添加 Item 模式工件，它包括使用 /groups/{group}/artifacts 操作的到 ItemId 模式的工作引用：

   $ 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"
           }
       ]
   }'

   Copy to Clipboard Toggle word wrap
   • 对于工件引用，您必须指定 application/create.extended+json 的自定义内容类型，该类型扩展 application/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"}] }

   Copy to Clipboard Toggle word wrap

5. 通过指定包含引用的工件的全局 ID，从 Service Registry 检索工件引用。在本例中，指定的全局 ID 为 2：

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

   Copy to Clipboard Toggle word wrap

6. 验证响应是否包含此工件引用的预期 JSON 正文。例如：

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

   Copy to Clipboard Toggle word wrap

流程

1. 从现有源 Service Registry 实例导出 Service Registry 数据：

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

   Copy to Clipboard Toggle word wrap

   MY-REGISTRY-URL 是在其上部署源 Service Registry 的主机名。例如： my-cluster-source-registry-myproject.example.com。

2. 将 registry 数据导入到目标 Service Registry 实例中：

   $ 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

   Copy to Clipboard Toggle word wrap

   MY-REGISTRY-URL 是在其上部署目标 Service Registry 的主机名。例如： my-cluster-target-registry-myproject.example.com。

流程

1. 更新 Maven pom.xml 文件，以使用 apicurio-registry-maven-plugin 来注册工件。以下示例显示了注册 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>

   Copy to Clipboard Toggle word wrap

   1

   指定 register 作为执行目标，将 schema 工件上传到 Service Registry。

   2

   使用 ./ apis/registry/v2 端点指定 Service Registry URL。

   3

   如果需要身份验证，您可以指定身份验证服务器和客户端凭证。

   4

   指定 Service Registry 工件组 ID。如果您不想使用唯一的组 ID，您可以指定 默认组。

   5

   您可以使用指定的组 ID、工件 ID 和位置注册多个工件。

2. 构建您的 Maven 项目，例如使用 mvn package 命令。

流程

1. 更新 Maven pom.xml 文件，以使用 apicurio-registry-maven-plugin 下载工件。以下示例显示了下载 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>

   Copy to Clipboard Toggle word wrap

   1

   指定 download 作为执行目标。

   2

   使用 ./ apis/registry/v2 端点指定 Service Registry URL。

   3

   如果需要身份验证，您可以指定身份验证服务器和客户端凭证。

   4

   指定 Service Registry 工件组 ID。如果您不想使用唯一组，您可以指定 默认组。

   5

   您可以使用工件 ID 将多个工件下载到指定的目录中。

2. 构建您的 Maven 项目，例如使用 mvn package 命令。

流程

1. 更新 Maven pom.xml 文件，以使用 apicurio-registry-maven-plugin 测试工件。以下示例显示了测试 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>

   Copy to Clipboard Toggle word wrap

   1

   指定 test-update 作为测试 schema 工件的执行目标。

   2

   使用 ./ apis/registry/v2 端点指定 Service Registry URL。

   3

   如果需要身份验证，您可以指定身份验证服务器和客户端凭证。

   4

   指定 Service Registry 工件组 ID。如果您不想使用唯一组，您可以指定 默认组。

   5

   您可以使用工件 ID 测试指定目录中的多个工件。

2. 构建您的 Maven 项目，例如使用 mvn package 命令。

流程

1. 更新您的 Maven pom.xml 文件，以使用 apicurio-registry-maven-plugin 注册 TradeKey 模式，其中包含对 Exchange 模式的嵌套引用，如下所示：

   <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>

   Copy to Clipboard Toggle word wrap

   1

   指定 register 作为执行目标，将 schema 工件上传到 Service Registry。

   2

   使用 ./ apis/registry/v2 端点指定 Service Registry URL。

   3

   如果需要身份验证，您可以指定身份验证服务器和客户端凭证。

   4

   指定 Service Registry 工件组 ID。如果您不想使用唯一的组 ID，您可以指定 默认组。

   5

   使用其组 ID、工件 ID、版本、类型和位置指定 Service Registry 工件引用。您可以以这种方式注册多个工件引用。

2. 构建您的 Maven 项目，例如使用 mvn package 命令。

流程

1. 更新您的 Maven pom.xml 文件，以使用 apicurio-registry-maven-plugin 注册 TradeKey 模式，其中包含对 Exchange 模式的嵌套引用，如下所示：

   <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>

   Copy to Clipboard Toggle word wrap

   1

   指定 register 作为执行目标，将 schema 工件上传到 Service Registry。

   2

   使用 ./ apis/registry/v2 端点指定 Service Registry URL。

   3

   如果需要身份验证，您可以指定身份验证服务器和客户端凭证。

   4

   指定包含引用的父工件组 ID。如果您不想使用唯一的组 ID，您可以指定 默认组。

   5

   指定父工件文件的位置。所有引用的工件还必须位于同一目录中。

   6

   将 & lt;analyzeDirectory > 选项设置为 true，以自动检测并注册同一目录中对工件的所有引用。您可以以这种方式注册多个工件引用。

2. 构建您的 Maven 项目，例如使用 mvn package 命令。

流程

1. 在您的 Maven 项目中添加以下依赖项：

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

   Copy to Clipboard Toggle word wrap

2. 创建 Service Registry 客户端，如下所示：

   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"; 

   1

   
          RegistryClient client = RegistryClientFactory.create(registryUrl); 

   2

   
       }
   }

   Copy to Clipboard Toggle word wrap

   1

   如果您指定了 https://my-registry.my-domain.com 的示例 Service Registry URL，客户端会自动附加 /apis/registry/v2。

   2

   有关创建 Service Registry 客户端时的更多选项，请参阅下一节中的 Java 客户端配置。

流程

1. 使用 Service Registry 的 URL 配置客户端。例如：

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   1

   Service Registry 提供的反序列化器。

   2

   反序列化采用 Apache Avro JSON 格式。

流程

1. 使用 Service Registry 的 URL 配置客户端。例如：

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

   Copy to Clipboard Toggle word wrap

2. 使用 serializer 配置客户端，并在 Service Registry 中查找架构。例如：

   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

   Copy to Clipboard Toggle word wrap

   1

   Service Registry 提供的消息键的序列化器。

   2

   Service Registry 提供的 message 值的序列化器。

   3

   查找策略，以查找该模式的全局 ID。

流程

1. 使用 Service Registry URL 创建并配置 Java 客户端：

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   1

   Service Registry 提供的 Avro serializer。

   2

   Service Registry 提供的 Avro deserializer。

   3

   配置 Service Registry URL 和 Avro reader，以 Avro 格式进行 deserialization。

3. 创建 Kafka Streams 客户端：

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

   Copy to Clipboard Toggle word wrap

1. Service Registry 所需的 URL。
2. 扩展 ID 处理以支持其他 ID 格式，并将它们与 Service Registry SerDes 服务兼容。例如，将默认 ID 格式从 Long 改为 Integer 支持 Confluent ID 格式。
3. 简化 Confluent ID 的处理。如果设置为 true，则使用 Integer 用于全局 ID 查找。设置不应与 ID_HANDLER 选项一起使用。

1. 用于 Service Registry Kafka 转换所需的序列化器。
2. 用于 Service Registry Kafka 转换所需的反序列化器。