Apicurio Registry 用户指南

流程

1. 连接到 Apicurio Registry web 控制台：

   http://MY_REGISTRY_URL/ui

2. 点 Upload artifact，并指定以下内容：

   • group 和 ID ：使用默认空设置自动生成 ID 和 默认组，或者输入可选的工件组或 ID。

   • 类型 ：使用默认 Auto-Detect 设置来自动检测工件类型，或者从下拉菜单中选择工件类型，例如 Avro Schema 或 OpenAPI。

     注意

     Apicurio Registry 服务器无法自动检测 Kafka Connect Schema 工件类型。您必须手动选择此工件类型。

   • 工件: Drag 和 drop or click Browse 以上传文件，如 my-schema.json 或 my-openapi.json。

3. 点 Upload，查看 Artifact Details ：

   图 3.1. Apicurio Registry Web 控制台中的工件详情

   
   • info ：显示工件名称和可选的组、描述、生命周期状态、创建和最后一次修改。点击 Edit Artifact Metadata 铅笔图标编辑工件名称和描述或添加标签，然后点 Download 向本地下载工件文件。另外，还显示您可以启用和配置的构件 内容规则。
   • 文档 （仅限OpenAPI）：显示自动生成的 REST API 文档。
   • 内容 ：显示完整工件内容的只读视图。
4. 在 内容 规则中，单击 Enable 来配置 Validity Rule 或 Compatibility Rule，然后从下拉菜单中选择相应的规则配置。如需了解更多详细信息，请参阅 第 9 章 Apicurio Registry artifact 引用。
5. 点 Upload new version 添加新工件版本，然后拖放或点击 Browse 上传该文件，如 my-schema.json 或 my-openapi.json。

6. 要删除工件，点 Upload new version 旁边的垃圾桶图标。

   警告

   删除工件会删除工件及其所有版本，无法撤消。工件版本是不可变的，不能单独删除。

流程

1. 连接到 Apicurio Registry web 控制台：

   http://MY_REGISTRY_URL/ui

2. 浏览存储在 registry 中的工件列表，或者输入搜索字符串来查找工件。您可以选择根据特定 名称、组、描述 或 标签搜索。

   图 3.2. 在 Apicurio Registry web 控制台中浏览工件

   

3. 点击 View artifact 查看 Artifact Details ：

   • info ：显示工件名称和可选的组、描述、生命周期状态、创建和最后一次修改。点击 Edit Artifact Metadata 铅笔图标编辑工件名称和描述或添加标签，然后点 Download 向本地下载工件文件。另外，还显示您可以启用和配置的构件 内容规则。
   • 文档 （仅限OpenAPI）：显示自动生成的 REST API 文档。
   • 内容 ：显示完整工件内容的只读视图。
4. 如果添加了其他版本，可选择 从下拉菜单查看不同的工件版本。

流程

1. 连接到 Apicurio Registry web 控制台：

   http://MY_REGISTRY_URL/ui

2. 对于工件规则，浏览 registry 中存储的工件列表，或者输入搜索字符串来查找工件。您可以选择根据特定的工件 名称、组、描述 或 标签搜索。
3. 单击 View artifact，以查看 Artifact Details。

4. 在 Content Rules 中，点 Enable 来配置 Validity Rule 或 Compatibility Rule，然后从下拉菜单中选择相应的规则配置。如需了解更多详细信息，请参阅 第 9 章 Apicurio Registry artifact 引用。

   图 3.3. 在 Apicurio Registry web 控制台中配置内容规则

   
5. 对于全局规则，请单击工具栏右上角的 Manage global rules，再单击 Enable 以配置全局 Validity Rule 或 Compatibility Rule，然后从下拉菜单选择适当的规则配置。如需了解更多详细信息，请参阅 第 9 章 Apicurio Registry artifact 引用。
6. 要禁用工件规则或全局规则，请点击规则旁边的垃圾箱图标。

流程

1. 使用 /groups/{group}/artifacts 操作向注册表添加工件。以下示例 curl 命令为共享价格应用程序添加简单的工件：

   $ curl -X POST -H "Content-type: application/json; artifactType=AVRO" \
     -H "X-Registry-ArtifactId: share-price" \ 

   1

   
     --data '{"type":"record","name":"price","namespace":"com.example", \
      "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \ 

   2

   
     http://MY-REGISTRY-HOST/apis/registry/v2/groups/my-group/artifacts 

   3

   Copy to Clipboard Toggle word wrap

   1

   这个示例添加了一个 Avro schema 工件，其工件 ID 为 share-price。如果您没有指定唯一的工件 ID，Apicurio Registry 会自动生成一个作为 UUID。

   2

   MY-REGISTRY-HOST 是部署 Apicurio Registry 的主机名。例如： my-cluster-service-registry-myproject.example.com。

   3

   本例在 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", 

   1

   
   "type":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2} 

   2

   Copy to Clipboard Toggle word wrap

   1

   在添加工件时没有指定版本，因此会自动创建默认版本 1。

   2

   这是添加到 registry 的第二个工件，因此全局 ID 和内容 ID 的值为 2。

3. 使用 API 路径中的工件 ID，从 registry 检索工件内容。在这个示例中，指定的 ID 是 share-price ：

   $ curl http://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 操作在注册表中添加工件版本。以下示例 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" \ 

   1

   
     --data '{"type":"record","name":" p","namespace":"com.example", \
      "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \ 

   2

   
      http://MY-REGISTRY-HOST/apis/registry/v2/groups/my-group/artifacts 

   3

   Copy to Clipboard Toggle word wrap

   1

   这个示例添加了一个 Avro schema 工件，其工件 ID 为 my-share-price 和 1.1.1 版本。如果没有指定版本，Apicurio Registry 会自动生成默认版本 1。

   2

   MY-REGISTRY-HOST 是部署 Apicurio Registry 的主机名。例如： my-cluster-service-registry-myproject.example.com。

   3

   本例在 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", 

   1

   
   "type":"AVRO","globalId":3,"state":"ENABLED","groupId":"my-group","contentId":3} 

   2

   Copy to Clipboard Toggle word wrap

   1

   在添加工件时，指定了自定义 1.1.1 版本。

   2

   这是添加到 registry 中的第三个工件，因此全局 ID 和内容 ID 的值为 3。

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

   $ curl http://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. 从现有源 Apicurio Registry 实例导出 registry 数据：

   $ curl http://MY-REGISTRY-HOST/apis/registry/v2/admin/export \
     --output my-registry-data.zip

   Copy to Clipboard Toggle word wrap

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

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

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

   Copy to Clipboard Toggle word wrap

   MY-REGISTRY-HOST 是部署目标 Apicurio Registry 的主机名。例如： my-cluster-target-registry-myproject.example.com。

流程

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. 按照以下方法创建 registry 客户端：

   public class ClientExample {
   
       private static final RegistryRestClient client;
   
        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 的示例 registry URL，客户端将自动附加 /apis/registry/v2。

   2

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

3. 创建客户端后，您可以通过客户端使用 Apicurio Registry REST API 中的所有操作。如需了解更多详细信息，请参阅 Apicurio Registry REST API 文档。

流程

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

   Copy to Clipboard Toggle word wrap

   1

   由 Apicurio Registry 提供的 deserializer。

   2

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

流程

1. 使用 Apicurio 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 和策略配置客户端，以在 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

   Copy to Clipboard Toggle word wrap

   1

   Apicurio Registry 提供的消息键的 serializer。

   2

   Apicurio Registry 提供的消息值的 serializer。

   3

   查找策略，用于查找 schema 的全局 ID。

流程

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

   Apicurio Registry 提供的 Avro serializer。

   2

   Apicurio Registry 提供的 Avro deserializer。

   3

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

3. 创建 Kafka Streams 客户端：

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

   Copy to Clipboard Toggle word wrap