Apicurio Registry 用户指南

流程

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

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

   

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

   • 概述 ：显示工件元数据，如工件 ID、名称、描述、标签等。另外，还显示您可以为工件内容配置的有效性和兼容性规则。
   • 版本 ：显示所有工件版本的列表。这将为空，除非您在创建工件时上传第一个版本。

   • 分支 ：显示工件的分支列表。这将至少显示最新的 分支，但可能会根据您的配置显示其他生成的分支。

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

     

3. 点 Versions 选项卡查看所有工件版本的列表。然后，单击列表中的某个版本，或者从列表中某个版本的 Action 菜单中选择 View Version。然后，您会看到以下工件版本详情：

   • 概述 ：显示工件版本元数据，如版本名称、描述、全局 ID、内容 ID、标签等。另外，还显示为工件版本创建的任何注释。
   • 文档 （仅限 OpenAPI 和 AsyncAPI）：显示自动生成的 REST API 文档。
   • 内容 ：显示完整工件版本内容的只读视图。对于 JSON 内容，您可以点 JSON 或 YAML 来显示您首选的格式。

   • 引用 ：显示此工件版本引用的所有工件的只读视图。您还可以点引用此 工件版本的 View 工件。

     图 3.3. Apicurio Registry web 控制台中的工件版本详情

     
4. 要将工件内容保存到本地文件，如 my-openapi.json 或 my-protobuf-schema.proto，然后点 Download。

流程

1. 在 Explore 选项卡中，点 Create artifact，然后完成 Create artifact 向导：

   注意

   您可以创建一个没有内容的占位符工件，但您必须指定工件类型，因为 Apicurio Registry 无法自动检测内容类型。通过创建占位符，您可以先创建规则并在稍后添加内容。

   1. 指定 Artifact Coordinates 并点 Next ：

      • 组 ID 和 Artifact ID ：使用默认空设置自动生成工件 ID，并将工件 添加到默认 工件组中。另外，您可以输入可选的工件组或工件 ID。
      • 类型 ：使用默认 Auto-Detect 设置来自动检测工件类型（如果创建空工件时不允许），或者从列表中选择工件类型，如 Avro Schema 或 OpenAPI。您必须手动选择 Kafka Connect Schema 工件类型，该工件类型无法自动检测到。

   2. 指定 Artifact Metadata 并点 Next ：

      • Name ：输入新工件的可选友好名称。
      • 描述 ：输入新工件的可选描述。
      • 标签 ：（可选）为新工件添加一个或多个标签（名称/值对）。

   3. 指定 Version 内容 并点 Next ：

      • 版本号 ：创建第一个版本时可选添加版本字符串。

      • Content: 使用以下选项之一指定内容：

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

   4. 指定 版本元数据 ：

      • Name ：输入第一个工件版本的可选友好名称。
      • 描述 ：输入第一个工件版本的可选描述。
      • 标签 ：（可选）为第一个工件版本添加一个或多个标签（名称/值对）。

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

   • 概述 ：显示工件元数据，如工件 ID、名称、描述、标签等。另外，还显示您可以为工件内容配置的有效性和兼容性规则。
   • 版本 ：显示所有工件版本的列表。这将为空，除非您在创建工件时上传第一个版本。

   • 分支 ：显示工件的分支列表。这将至少显示最新的 分支，但可能会根据您的配置显示其他生成的分支。

     以下示例显示了 Apache Avro 工件示例：

     图 3.4. Apicurio Registry web 控制台中的工件详情

     

3. 在 Overview 选项卡中，点 Edit pencil 图标来编辑工件元数据，如名称或描述。

   您还可以为分类和搜索目的添加零个或多个标签（名称 + 值）。要添加标签，请执行以下步骤：

   1. 点 Add label。
   2. 输入键名称和值（可选）。
   3. 重复前两个步骤来添加多个属性。
   4. 点击 Save。
4. 要将工件内容保存到本地文件，如 my-protobuf-schema.proto 或 my-openapi.json，请点击页面末尾的 Download。

5. 要添加新的工件版本，请切换到 Versions 选项卡，然后在工具栏中点 Create version。从那里提供以下信息：

   1. 版本号 ：（可选）：为新版本添加版本字符串。

   2. Content: 使用以下选项之一指定内容：

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

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

   警告

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

流程（特定于组的规则）

1. 在 Explore 选项卡中，通过从 "Search for" 菜单中选择 Groups 来浏览 Apicurio Registry 中的组列表。
2. 点组查看其详情和内容规则。

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

   图 3.5. Apicurio Registry web 控制台中的特定于组的规则

   

流程（特定于工件的规则）

1. 在 Explore 选项卡中，通过从 "Search for" 菜单中选择 Artifacts 来浏览 Apicurio Registry 中的工件列表。
2. 点列表中的工件来查看其详情和内容规则。

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

   图 3.6. Apicurio Registry web 控制台中的工件内容规则

   

流程（全局规则）

1. 要访问全局规则，请点 Global rules 选项卡。

2. 点 Enable 为所有工件内容配置全局有效期、兼容性或完整性规则，然后从列表中选择适当的规则配置。

   图 3.7. Apicurio Registry web 控制台中的工件内容规则

   

流程

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

流程

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

2. 选择您要为 Apicurio Registry 配置的设置：

   Expand

   表 3.1. 身份验证设置

   设置	描述
   HTTP 基本身份验证	仅在启用了身份验证时显示（确保部署）。选择后，Apicurio Registry 用户可以使用 HTTP 基本身份验证进行身份验证，除了 OAuth 之外。默认不选择。

   Show more
   Expand

   表 3.2. 授权设置

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

   Show more
   Expand

   表 3.3. 兼容性设置

   设置	描述
   规范哈希模式（兼容性 API）	选择后，Schema Registry 兼容性 API 使用规范哈希而不是内容的常规哈希。
   传统 ID 模式（兼容性 API）	选择后，Confluent Schema Registry 兼容性 API 使用 globalId 而不是 contentId 作为工件标识符。
   返回的最大主题数（兼容性 API）	决定 Confluent Schema Registry 兼容性 API 返回的最大 Subject 数量（用于 /subjects 端点）。

   Show more
   Expand

   表 3.4. Web 控制台设置

   设置	描述
   下载链接到期	为了安全起见，生成到 .zip 下载文件的链接的秒数，例如从 Apicurio Registry 导出工件数据时。默认值为 30 秒。

   Show more
   Expand

   表 3.5. 语义版本设置

   设置	描述
   自动创建 semver 分支	启用后，自动为主('A.x')和次('A.B.x')工件版本自动创建或更新分支。
   确保所有版本号都兼容"semver"	启用后，验证所有工件版本是否都符合 Semantic Versioning 2 格式(https://semver.org)。

   Show more
   Expand

   表 3.6. 其他属性

   设置	描述
   删除工件	选择后，用户可以使用 Core Registry API 删除 Apicurio Registry 中的工件。默认不选择。
   删除工件版本	选择后，用户可以使用 Core Registry API 删除 Apicurio Registry 中的工件版本。默认不选择。
   Delete group（删除组）	选择后，用户可以使用 Core Registry API 删除 Apicurio Registry 中的组。默认不选择。
   存储只读模式	选择后，Registry 会为写入存储的操作返回错误（此属性除外）。默认情况下不启用。

   Show more

流程

1. 在源 Apicurio Registry 实例的 web 控制台中，查看 Explore 选项卡。
2. 点工具栏中 Create artifact 旁边的附加操作图标（三个垂直点），然后选择 Export all (as .ZIP)，将这个 Apicurio Registry 实例的数据导出到 .zip 下载文件中。
3. 在目标 Apicurio Registry 实例的 web 控制台中，查看 Explore 选项卡。
4. 点工具栏中 Create artifact 旁边的附加操作图标（三个垂直点），然后选择 Import from .ZIP。
5. 拖放或浏览到您之前导出的 .zip 下载文件。
6. 单击 Import 并等待导入数据。

流程

1. 使用 /groups/{groupId}/artifacts 操作向 Apicurio Registry 添加工件。以下示例 curl 命令为共享价格应用程序添加一个简单的模式工件：

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data-raw '{
       "artifactId": "share-price",
       "artifactType": "AVRO",
       "firstVersion": {
           "content": {
               "content": "{\"type\":\"record\",\"name\":\" p\",\"namespace\":\"com.example\", \"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}",
               "contentType": "application/json"
           }
       }
   }'

   • 这个示例添加了一个 Apache Avro 模式工件，工件 ID 为 share-price。如果没有指定唯一的工件 ID，Apicurio Registry 会自动生成一个作为 UUID。
   • MY-REGISTRY-URL 是在其上部署 Apicurio Registry 的主机名。例如： my-cluster-service-registry-myproject.example.com。
   • 本例在 API 路径中指定 my-group 的组 ID。如果没有指定唯一的组 ID，则必须在 API 路径中指定 ../groups/default。

2. 验证响应是否包含预期的 JSON 正文，以确认是否添加了构件。例如：

   {"artifact":{"owner":"","createdOn":"2024-09-26T17:24:21Z","modifiedBy":"","modifiedOn":"2024-09-26T17:24:21Z","artifactType":"AVRO","groupId":"my-group","artifactId":"share-price"},"version":{"version":"1","owner":"","createdOn":"2024-09-26T17:24:21Z","artifactType":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2,"artifactId":"share-price"}}

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

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

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

流程

1. 使用 /groups/{groupId}/artifacts 操作在 registry 中添加工件版本。以下示例 curl 命令为共享价格应用程序添加一个简单的工件：

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data-raw '{
       "artifactId": "my-share-price",
       "artifactType": "AVRO",
       "firstVersion": {
           "version": "1.1.1",
           "content": {
               "content": "{\"type\":\"record\",\"name\":\" p\",\"namespace\":\"com.example\", \"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}",
               "contentType": "application/json"
           }
       }
   }'

   • 这个示例添加了一个 Avro 模式工件，工件 ID 为 my-share-price 和 1.1.1 版本。如果没有指定版本，Apicurio Registry 会自动生成默认版本 1。
   • MY-REGISTRY-URL 是在其上部署 Apicurio Registry 的主机名。例如： my-cluster-service-registry-myproject.example.com。
   • 本例在 API 路径中指定 my-group 的组 ID。如果没有指定唯一的组 ID，则必须在 API 路径中指定 ../groups/default。

2. 验证响应是否包含预期的 JSON 正文，以确认是否添加了自定义工件版本。例如：

   {"artifact":{"owner":"","createdOn":"2024-09-26T17:06:21Z","modifiedBy":"","modifiedOn":"2024-09-26T17:06:21Z","artifactType":"AVRO","groupId":"my-group","artifactId":"my-share-price"},"version":{"version":"1.1.1","owner":"","createdOn":"2024-09-26T17:06:21Z","artifactType":"AVRO","globalId":4,"state":"ENABLED","groupId":"my-group","contentId":4,"artifactId":"my-share-price"}}

   • 在添加工件时，指定了 1.1.1 的自定义版本。
   • 这是添加到注册表中的第四个构件，因此全局 ID 和内容 ID 的值为 4。

3. 使用 API 路径中的工件 ID 和版本从 registry 检索工件内容。在本例中，指定的 ID 是 my-share-price，版本是 1.1.1 ：

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

流程

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

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      --data '{"artifactId":"ItemId","artifactType":"AVRO","firstVersion":{"version":"1.0.0","content":{"content":"{\"namespace\":\"com.example.common\",\"name\":\"ItemId\",\"type\":\"record\",\"fields\":[{\"name\":\"id\",\"type\":\"int\"}]}","contentType":"application/json"}}}'

   • 这个示例添加了一个 Avro schema 工件，工件 ID 为 ItemId。如果没有指定唯一的工件 ID，Apicurio Registry 会自动生成一个作为 UUID。
   • MY-REGISTRY-URL 是在其上部署 Apicurio Registry 的主机名。例如： my-cluster-service-registry-myproject.example.com。
   • 本例在 API 路径中指定 my-group 的组 ID。如果没有指定唯一的组 ID，则必须在 API 路径中指定 ../groups/default。

2. 验证响应是否包含预期的 JSON 正文，以确认是否添加了构件。例如：

   {"artifact":{"owner":"","createdOn":"2024-09-26T16:27:38Z","modifiedBy":"","modifiedOn":"2024-09-26T16:27:38Z","artifactType":"AVRO","groupId":"my-group","artifactId":"ItemId"},"version":{"version":"1.0.0","owner":"","createdOn":"2024-09-26T16:27:38Z","artifactType":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2,"artifactId":"ItemId"}}

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

   $ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
   -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   --data-raw '{
   	"artifactId": "Item",
   	"artifactType": "AVRO",
   	"firstVersion": {
   		"version": "1.0.0",
   		"content": {
   			"content": "{\"namespace\":\"com.example.common\",\"name\":\"Item\",\"type\":\"record\",\"fields\":[{\"name\":\"itemId\",\"type\":\"com.example.common.ItemId\"}]}",
   			"contentType": "application/json",
   			"references": [
   				{
   					"name": "com.example.common.ItemId",
   					"groupId": "my-group",
   					"artifactId": "ItemId",
   					"version": "1.0.0"
   				}
   			]
   		}
   	}
   }'

   • 对于工件引用，您必须指定 application/create.extended+json 的自定义内容类型，它将扩展 application/json 内容类型。

4. 验证响应是否包含预期的 JSON 正文，以确认工件是否已创建有引用。例如：

   {"artifact":{"owner":"","createdOn":"2024-09-26T16:28:45Z","modifiedBy":"","modifiedOn":"2024-09-26T16:28:45Z","artifactType":"AVRO","groupId":"my-group","artifactId":"Item"},"version":{"version":"1.0.0","owner":"","createdOn":"2024-09-26T16:28:45Z","artifactType":"AVRO","globalId":3,"state":"ENABLED","groupId":"my-group","contentId":3,"artifactId":"Item"}}

5. 通过指定包含引用的工件的协调，从 Apicurio Registry 检索工件引用：

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/Item/versions/1.0.0/references

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

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

1. 检索 dereferenced (lined) schema 内容：

   $ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/Item/versions/1.0.0/content?references=DEREFERENCE

2. 验证响应是否包含此工件内容的预期 JSON 正文，其中包含内联引用。例如：

   {"type":"record","name":"Item","namespace":"com.example.common","fields":[{"name":"itemId","type":{"type":"record","name":"ItemId","fields":[{"name":"id","type":"int"}]}}]}

流程

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

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

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

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

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

   MY-REGISTRY-URL 是部署目标 Apicurio 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/v3</registryUrl> 

   2

   
               <authServerUrl>MY-AUTH-SERVER</authServerUrl>
               <clientId>MY-CLIENT-ID</clientId>
               <clientSecret>MY-CLIENT-SECRET</clientSecret> 

   3

   
               <clientScope>MY-CLIENT-SCOPE</clientScope>
               <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

   
                       <artifactType>GRAPHQL</artifactType>
                       <file>${project.basedir}/src/main/resources/apis/example.graphql</file>
                       <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                       <canonicalize>true</canonicalize>
                   </artifact>
               </artifacts>
           </configuration>
       </execution>
     </executions>
    </plugin>

   1

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

   2

   使用 ../apis/registry/v3 端点指定 Apicurio Registry URL。

   3

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

   4

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

   5

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

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

流程

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/v3</registryUrl> 

   2

   
             <authServerUrl>MY-AUTH-SERVER</authServerUrl>
             <clientId>MY-CLIENT-ID</clientId>
             <clientSecret>MY-CLIENT-SECRET</clientSecret> 

   3

   
             <clientScope>MY-CLIENT-SCOPE</clientScope>
             <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

   指定 download 作为执行目标。

   2

   使用 ../apis/registry/v3 端点指定 Apicurio Registry URL。

   3

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

   4

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

   5

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

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

流程

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/v3</registryUrl> 

   2

   
               <authServerUrl>MY-AUTH-SERVER</authServerUrl>
               <clientId>MY-CLIENT-ID</clientId>
               <clientSecret>MY-CLIENT-SECRET</clientSecret> 

   3

   
               <clientScope>MY-CLIENT-SCOPE</clientScope>
               <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 作为测试 schema 工件的执行目标。

   2

   使用 ../apis/registry/v3 端点指定 Apicurio Registry URL。

   3

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

   4

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

   5

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

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

流程

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

   <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/v3</registryUrl> 

   2

   
                   <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                   <clientId>MY-CLIENT-ID</clientId>
                   <clientSecret>MY-CLIENT-SECRET</clientSecret> 

   3

   
                   <clientScope>MY-CLIENT-SCOPE</clientScope>
                   <artifacts>
                       <artifact>
                           <groupId>test-group</groupId> 

   4

   
                           <artifactId>TradeKey</artifactId>
                           <version>2.0</version>
                           <artifactType>AVRO</artifactType>
                           <file>
                               ${project.basedir}/src/main/resources/schemas/TradeKey.avsc
                           </file>
                           <ifExists>FIND_OR_CREATE_VERSION</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>
                                   <artifactType>AVRO</artifactType>
                                   <file>
                                       ${project.basedir}/src/main/resources/schemas/Exchange.avsc
                                   </file>
                                   <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                                   <canonicalize>true</canonicalize>
                               </reference>
                           </references>
                       </artifact>
                   </artifacts>
               </configuration>
           </execution>
       </executions>
   </plugin>

   1

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

   2

   使用 ../apis/registry/v3 端点指定 Apicurio Registry URL。

   3

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

   4

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

   5

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

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

流程

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

   <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/v3</registryUrl> 

   2

   
                   <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                   <clientId>MY-CLIENT-ID</clientId>
                   <clientSecret>MY-CLIENT-SECRET</clientSecret> 

   3

   
                   <clientScope>MY-CLIENT-SCOPE</clientScope>
                   <artifacts>
                       <artifact>
                           <groupId>test-group</groupId> 

   4

   
                           <artifactId>TradeKey</artifactId>
                           <version>2.0</version>
                           <artifactType>AVRO</artifactType>
                           <file>
                               ${project.basedir}/src/main/resources/schemas/TradeKey.avsc 

   5

   
                           </file>
                           <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                           <canonicalize>true</canonicalize>
                           <autoRefs>true</autoRefs> 

   6

   
                       </artifact>
                   </artifacts>
               </configuration>
           </execution>
       </executions>
   </plugin>

   1

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

   2

   使用 ../apis/registry/v3 端点指定 Apicurio Registry URL。

   3

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

   4

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

   5

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

   6

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

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

流程

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

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

2. 使用 Apicurio 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

   Apicurio Registry 提供的反序列化器。

   2

   反序列化为 Apache Avro JSON 格式。

流程

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

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

2. 使用 serializer 配置客户端，并使用策略在 Apicurio Registry 中查找 schema。例如：

   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

   Apicurio Registry 提供的消息键的 serializer。

   2

   Apicurio Registry 提供的消息值的 serializer。

   3

   查找 schema 的全局 ID 的查找策略。

流程

1. 使用 Apicurio Registry URL 创建和配置 Java 客户端：

   String registryUrl = "https://registry.example.com/apis/registry/v3";
   
   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(AvroSerdeConfig.USE_SPECIFIC_AVRO_READER, true);
   logSerde.configure(config, false); 

   3

   1

   Apicurio Registry 提供的 Avro serializer。

   2

   Apicurio Registry 提供的 Avro deserializer。

   3

   配置 Apicurio Registry URL 和 Avro reader 以 Avro 格式进行反序列化。

3. 创建 Kafka Streams 客户端：

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

1. Apicurio Registry 所需的 URL。
2. 扩展 ID 处理以支持其他 ID 格式，并使其与 Apicurio Registry SerDes 服务兼容。例如，您可以将它从与 Confluent 的 ID 格式兼容的默认 ID 格式改为 Long。

1. 与 Apicurio Registry Kafka 转换程序搭配使用所需的 serializer。
2. 与 Apicurio Registry Kafka converter 搭配使用所需的 deserializer。