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 来显示您首选的格式。
3. 如果添加了此工件的额外版本，您可以从页面标头中的 Version 列表中选择它们。
4. 要将工件内容保存到本地文件，例如 my-protobuf-schema.proto，请单击页面末尾的 Download。

流程

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

   • group 和 ID ：使用默认空设置自动生成工件 ID，并将工件 添加到默认 工件组中。或者，您可以输入可选的工件组名称或 ID。

   • 类型 ：使用默认 Auto-Detect 设置来自动检测工件类型，或从列表中选择工件类型，如 Avro Schema 或 OpenAPI。

     注意

     Service Registry 无法自动检测 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 来显示您首选的格式。

     以下示例显示了 Protobuf 模式工件示例：

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

     

     View larger image

     

3. 在 Overview 选项卡上，点击 Edit 铅笔图标以编辑工件元数据，如名称或描述。

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

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

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

   警告

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

流程

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

3. 在 Content rules 中，点 Enable 为工件内容配置有效规则或兼容性规则，并从列表中选择适当的规则配置，例如：完全了解有效期规则。

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

   

   View larger image

   
4. 若要访问全局规则，请单击 Service Registry 实例，再单击 Global rules 选项卡。点击 Enable 为所有工件内容配置全局有效规则或兼容性规则，并从列表中选择适当的规则配置。
5. 要禁用工件规则或全局规则，请点击规则旁边的垃圾箱图标。

流程

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

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

   Expand

   表 3.1. 身份验证设置

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

   Show more
   Expand

   表 3.2. 授权设置

   设置	描述
   匿名读访问	仅在已经选择身份验证时显示。选择了 Service Registry 时，Service Registry 会为来自匿名用户的请求提供只读访问权限，而无需任何凭证。如果要使用这个实例在外部发布架构或 API，则此设置很有用。默认未选择。
   工件所有者授权	仅在已经启用身份验证时显示。选择后，只有创建工件的用户才能修改该工件。默认未选择。
   工件组所有者授权	只有在已经启用身份验证并且选择了 Artifact 所有者授权时，才会显示。选择后，只有创建工件组的用户才具有对该工件组的写入权限，例如，在该组中添加或删除工件。默认未选择。
   经身份验证的读取访问权限	仅在已经启用身份验证时显示。选择了后，Service Registry 会为任何经过身份验证的用户授予对来自任何经过身份验证的用户请求的只读访问权限，而不考虑用户角色。默认未选择。

   Show more
   Expand

   表 3.3. 兼容性设置

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

   Show more
   Expand

   表 3.4. Web 控制台设置

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

   Show more

流程

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

流程

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

流程

1. 使用 /groups/{group}/artifacts 操作向 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
   • 这个示例添加了一个 Avro schema 工件 ID，其工件 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
   • 在添加工件时没有指定版本，因此会自动创建默认版本 1。
   • 这是添加到 registry 的第二个工件，因此全局 ID 和内容 ID 的值为 2。

3. 在 API 路径中使用其工件 ID 从 registry 检索工件内容。在这个示例中，指定的 ID 是 shared -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，其工件 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. 使用其工件 ID 和 API 路径中的版本从 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. 使用 /groups/{group}/artifacts 操作添加包含对 Item Id 架构的 artifact 引用的 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"
           }
       ]
   }'

   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":[1]}

   Copy to Clipboard Toggle word wrap

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

   $ curl 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 实例导出 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 是在其上部署源服务注册表的主机名。例如： 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. 指定 register 作为将 schema 工件上传到 registry 的执行目标。
2. 使用 ../apis/registry/v2 端点指定 Service Registry URL。
3. 如果需要身份验证，您可以指定身份验证服务器和客户端凭证。
4. 指定 Service Registry 工件组 ID。如果您不想使用唯一组 ID，可以指定 default 组。
5. 您可以使用指定的组 ID、工件 ID 和位置来注册多个工件。

1. 将 download 指定为执行目标。
2. 使用 ../apis/registry/v2 端点指定 Service Registry URL。
3. 如果需要身份验证，您可以指定身份验证服务器和客户端凭证。
4. 指定 Service Registry 工件组 ID。如果您不想使用唯一组，您可以指定 default 组。
5. 您可以使用工件 ID 将多个工件下载到指定目录中。

1. 指定 register 作为将 schema 工件上传到 registry 的执行目标。
2. 使用 ../apis/registry/v2 端点指定 Service Registry URL。
3. 如果需要身份验证，您可以指定身份验证服务器和客户端凭证。
4. 指定 Service Registry 工件组 ID。如果您不想使用唯一组 ID，可以指定 default 组。
5. 使用其组 ID、工件 ID、版本、类型和位置指定 Service Registry 工件引用。您可以以这种方式注册多个构件引用。

1. 指定 test-update 作为测试 schema 工件的执行目的。
2. 使用 ../apis/registry/v2 端点指定 Service Registry URL。
3. 如果需要身份验证，您可以指定身份验证服务器和客户端凭证。
4. 指定 Service Registry 工件组 ID。如果您不想使用唯一组，您可以指定 default 组。
5. 您可以使用工件 ID 从指定目录中测试多个工件。

流程

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";
           RegistryClient client = RegistryClientFactory.create(registryUrl);
       }
   }

   Copy to Clipboard Toggle word wrap
   • 如果您指定了 https://my-registry.my-domain.com 的示例 registry URL，客户端将自动附加 /apis/registry/v2。
   • 有关创建 Service Registry 客户端时的更多信息，请参阅下一节中的 Java 客户端配置。

1. 简单 Avro 模式工件。
2. 公开 Service Registry 的 OpenShift 路由名称。

1. 指定 register 作为将 schema 工件上传到 registry 的执行目标。
2. 使用 ../apis/registry/v2 端点指定 Service Registry URL。
3. 指定 Service Registry 工件组 ID。
4. 您可以使用指定的组 ID、工件 ID 和位置来上传多个工件。

1. 您可以针对多个 URL 节点注册属性。
2. 查看该架构是否已存在基于工件 ID。

流程

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 提供的 deserializer。
   • 2.deserialization 是 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. 使用序列化程序和策略配置客户端，以在 Service 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. Service Registry 提供的消息键的序列化器。
   • 2.Service Registry 提供的消息值的序列化器。
   • 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.以 Avro 格式配置 Service Registry URL 和 Avro 读取器进行反序列化。

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 SerDe 服务兼容。例如，将默认 ID 格式从 Long 改为 Integer 支持 Confluent ID 格式。
3. 简化 Confluent ID 的处理。如果设置为 true，则使用 Integer 用于全局 ID 查找。此设置不应与 ID_HANDLER 选项一起使用。

1. 实现工件解析器策略的 Java 类，并在 Kafka SerDe 和工件 ID 之间映射。默认为主题 ID 策略。这仅由 serializer 类使用。
2. 实现 schema 解析器的 Java 类。默认为 DefaultSchemaResolver。这被 serializer 和 deserializer 类使用。

1. 与 Service Registry Kafka converter 搭配使用所需的序列化器。
2. 与 Service Registry Kafka converter 搭配使用所需的 deserializer。