模式 1

{
  "type": "record",
  "name": "book",
  "fields": [
    {
      "name": "title",
      "type": "string"
    },
    {
      "name": "author",
      "type": "string"
    }
  ]
}

模式 2

{
  "type": "record",
  "name": "book",
  "fields": [
    {
      "name": "author",
      "type": "string"
    },
    {
      "name": "title",
      "type": "string"
    }
  ]
}

模式 3

{
  "type": "record",
  "name": "book",
  "fields": [
    {
      "type": "string"
      "name": "author",
    },
    {
      "type": "string"
      "name": "title",
    }
  ]
}

模式 1 和模式 2 是不同的模式，注册表将它们存储为单独的模式。 它们无法互换使用，因为它们以不同的顺序列出 author 和 title 字段。 如果解码过程使用了模式 2，那么将无法正确解码使用模式 1 编码的数据。

使用 SerDes 按顺序“模式 1”，“模式 2”和“模式 3”创建新模式时，结果将是两个新模式。 模式 1 和模式 2 不同，但模式 3 等同于模式 2。

使用 REST API 创建模式时，仅当模式文本相同 (包括所有属性排序和描述性字段) 时，才会将其视为匹配。 这是为了允许您希望模式 3 成为其他模式的情况。

认证

要访问模式注册表，您还需要一组可用于向注册表进行认证的凭证。 有两个选项，即使用 API 密钥的基本认证或不记名令牌认证。

本文档中的示例显示了如何使用 API 密钥，但可以使用任一选项。

curl -u token:$APIKEY ...

curl -H "Authorization: Bearer $TOKEN" ...

错误

如果遇到错误情况，架构注册表将返回一个 non-2XX 范围 HTTP 状态代码。 响应主体包含一个JSON对象，格式如下：

{
    "error_code":404,
    "message":"No artifact with id 'my-schema' might be found."
}

错误 JSON 对象的属性如下：

设置模式状态

此端点用于将注册表中模式的状态设置为 ENABLED 或 DISABLED。 可以通过向 /artifacts/{schema-id}/state 端点发出 PUT 请求来设置模式的状态 (其中 {schema-id} 是模式的标识)。 如果请求成功，则返回一个空响应和状态代码204（无内容）。

示例 curl 请求：

curl -u token:$APIKEY –X PUT $URL/artifacts/my-schema/state -d '{"state": "DISABLED"}'

设置模式状态需要:

• 经理角色访问与被修改的架构匹配的架构资源。

设置模式版本状态

此端点用于将注册表中模式版本的状态设置为 ENABLED 或 DISABLED。 可以通过向 /artifacts/{schema-id}/versions/{version}/state 端点发出 PUT 请求来设置模式版本的状态 (其中 {schema-id} 是模式的标识，{version} 是模式版本的版本号)。 如果请求成功，则返回一个空响应和状态代码204（无内容）。

示例 curl 请求：

curl -u token:$APIKEY –X PUT $URL/artifacts/my-schema/versions/1/state -d '{"state": "DISABLED"}'

设置模式版本状态需要:

• 经理角色访问与正在修改的模式匹配的模式资源。

创建模式

此端点用于在注册表中存储模式。 模式数据作为 POST 请求的主体发送。 可以通过使用 ‘X-Registry-ArtifactId' 请求头来包含模式标识符。 如果请求中不存在此标头，则生成一个ID。 内容类型头必须设置为“application/json”。

示例 curl 请求：

curl -u token:$APIKEY -H 'Content-Type: application/json' -H 'X-Registry-ArtifactId: my-schema' $URL/artifacts -d '{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}'

示例响应：

{"id":"my-schema","type":"AVRO","version":1,"createdBy":"","createdOn":1579267788258,"modifiedBy":"","modifiedOn":1579267788258,"globalId":75}

创建模式至少需要两个角色：

• Event Streams 集群资源类型的读取者角色访问权。
• 创建的架构所对应的架构资源访问权限。

这将生成 Activity Tracker 事件以报告相应操作。 有关更多信息，请参阅 Activity Tracker 事件。

列出模式

您可以通过向 /artifacts 终端发送GET请求，生成一个包含注册表中所有模式ID的列表。 您可以使用 jsonformat 参数来格式化响应 (仅支持 string 和 object 格式)。 字符串格式是缺省值，它返回工件标识 (字符串) 的数组。 仅当设置了此选项时，才会在数组中包含已启用的工件。 对象格式返回一个 JSON 对象，该对象包含一个数组，其中数组中的每个条目都对应于注册表中的工件。 设置此选项时，将返回已启用和已禁用的工件。

示例 curl 请求：

curl -u token:$APIKEY $URL/artifacts

或

curl -u token:$APIKEY $URL/artifacts?jsonformat=string

或

curl -u token:$APIKEY $URL/artifacts?jsonformat=object

jsonformat 为字符串或未提供 (缺省为字符串) 时的示例响应:

["my-schema-2","my-schema-4"]

jsonformat 为对象时的响应示例:

{"artifacts":[{"id":"my-schema","state":"DISABLED"},{"id":"my-schema-2","state":"ENABLED"},{"id":"my-schema-3","state":"DISABLED"},{"id":"my-schema-4","state":"ENABLED"}],"count":4}

列出模式至少需要以下角色：

• Event Streams 集群资源类型的读取者角色访问权。

模式的状态和删除

模式删除是一个两阶段过程。 删除的第一阶段会将模式保留在注册表中，但会将其隐藏在某些操作中。 第二个阶段将永久除去模式，但只能在第一个阶段之后应用。 两阶段删除过程适用于工件级别，也适用于版本级别。

通过具有与工件和版本相关联的已启用或已禁用状态 (第一个阶段) 以及删除资源和版本的 API (第二个阶段) 来完成两个删除阶段。

可以使用列示工件或版本的操作所返回的 "state" 属性或者通过获取工件或版本的详细信息来发现已禁用的工件或版本。 已禁用的模式将计入每个企业实例 1000 个模式的模式配额。

删除模式

通过向 /artifacts/{schema-id} 终端发送DELETE请求（其中 {schema-id} 是架构的ID），架构将从注册表中删除。 如果成功，将返回空响应和状态码 204（无内容）。

示例 curl 请求：

curl -u token:$APIKEY -X DELETE $URL/artifacts/my-schema

删除模式至少需要两个角色：

• Event Streams 集群资源类型的读取者角色访问权。
• 经理角色访问与被删除模式匹配的模式资源。

这将生成 Activity Tracker 事件以报告相应操作。 有关更多信息，请参阅 Activity Tracker 事件。

创建模式的新版本

要创建架构的新版本，请向 /artifacts/{schema-id}/versions 端点发送POST请求（其中 {schema-id} 是架构的ID）。 请求主体必须包含模式的新版本。

如果请求成功，则新架构将作为架构的最新版本创建，并带有适当的版本号，同时返回状态码为200（OK）的响应，以及包含描述新版本（包括版本号）的元数据的有效负载。

示例 curl 请求：

curl -u token:$APIKEY -H 'Content-Type: application/json' $URL/artifacts/my-schema/versions -d '{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}'

示例响应：

{"id":"my-schema","type":"AVRO","version":2,"createdBy":"","createdOn": 1579267978382,"modifiedBy":"","modifiedOn":1579267978382,"globalId":83}

创建模式的新版本至少需要两个角色：

• Event Streams 集群资源类型的读取者角色访问权。
• 当模式资源与获取新版本的模式匹配时，写入器角色可以访问该资源。

这将生成 Activity Tracker 事件以报告相应操作。 有关更多信息，请参阅 Activity Tracker 事件。

获取模式的最新版本

要检索特定架构的最新版本，请向 /artifacts/{schema-id} 端点发送GET请求（其中 {schema-id} 是架构的ID）。 如果成功，将在响应的有效内容中返回模式的最新版本。

示例 curl 请求：

curl -u token:$APIKEY $URL/artifacts/my-schema

示例响应：

{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}

获取模式的最新版本至少需要两个角色：

• Event Streams 集群资源类型的读取者角色访问权。
• 读取器角色访问与检索到的架构匹配的架构资源。

获取模式的特定版本

要检索特定版本的架构，请向 /artifacts/{schema-id}/versions/{version} 端点发送GET请求（其中 {schema-id} 是架构的ID，{version} 是您要检索的特定版本的版本号）。 如果成功，将在响应的有效内容中返回模式的指定版本。

示例 curl 请求

curl -u token:$APIKEY $URL/artifacts/my-schema/versions/3

示例响应：

{"type":"record","name":"Citizen","fields":[{"name": "firstName","type":"string"},{"name":"lastName","type":"string"},{"name":"age","type":"int"},{"name":"phoneNumber","type":"string"}]}

获取模式的最新版本至少需要两个角色：

• Event Streams 集群资源类型的读取者角色访问权。
• 读取器角色访问与检索到的架构匹配的架构资源。

列出模式的所有版本

要列出当前存储在注册表中的模式的所有版本，请向 /artifacts/{schema-id}/versions 端点发送GET请求（其中 {schema-id} 是模式的ID）。 如果成功，将在响应的有效内容中返回模式的所有当前版本号的列表。 您可以使用 jsonformat 参数来格式化响应 (仅支持 number 和 object 格式)。 如果指定 "number" (缺省值)，那么响应是对应于工件的已启用版本 (将省略禁用版本) 的数字值的数组。 它与当前生成的端点格式相同。 如果指定了 "object"，那么响应是一个 JSON 对象，其中包含表示工件版本的 JSON 对象数组。 已启用和已禁用的版本都包含在阵列中。

示例 curl 请求：

curl -u token:$APIKEY $URL/artifacts/my-schema/versions

或

curl -u token:$APIKEY $URL/artifacts/my-schema/versions?jsonformat=number

或

curl -u token:$APIKEY $URL/artifacts/my-schema/versions?jsonformat=object

当 jsonformat 为 number 或未提供 (缺省为 number) 时的示例响应:

[1,3,4,6,7]

jsonformat 为对象时的响应示例:

{"versions":[{"id":1,"state":"ENABLED"},{"id":2,"state":"DISABLED"},{"id":3,"state":"ENABLED"},{"id":4,"state":"ENABLED"},{"id":5,"state":"DISABLED"},{"id":6,"state":"ENABLED"},{"id":7,"state":"ENABLED"}],"count":7}

获取模式的可用版本列表至少需要两个角色：

• Event Streams 集群资源类型的读取者角色访问权。
• 读取器角色访问与检索到的架构匹配的架构资源。

删除模式的版本

通过向 /artifacts/{schema-id}/versions/{version} 端点发送DELETE请求，可以从注册表中删除架构版本（其中 {schema-id} 是架构的ID，{version} 是架构版本的版本号）。 如果成功，将返回空的响应和状态码 204（无内容）。 删除唯一剩余的架构版本也会删除该架构。

示例 curl 请求：

curl -u token:$APIKEY -X DELETE $URL/artifacts/my-schema/versions/3

删除模式版本至少需要两个角色：

• Event Streams 集群资源类型的读取者角色访问权。
• 经理角色访问与被删除模式匹配的模式资源。

这将生成 Activity Tracker 事件以报告相应操作。 有关更多信息，请参阅 Activity Tracker 事件。

获取模式版本的特定全局唯一标识

要检索架构版本的特定全局唯一ID，请向 /artifacts/{artifactId}/versions/{version}/meta 端点发送GET请求（其中 {artifactId} 是工件的ID，{version} 是您要检索的特定版本的版本号）。 如果成功，那么将在响应的有效内容中返回模式版本的特定全局唯一标识。

示例 curl 请求：

curl -u token:$APIKEY $URL/artifacts/9030f450-45fb-4750-bb37-771ad49ee0e8/versions/1/meta

示例响应：

{"id":"9030f450-45fb-4750-bb37-771ad49ee0e8","type":"AVRO","version":1,"createdOn":1682340169202,"modifiedOn":1682340169202,"globalId":1}

获取模式版本的全局唯一标识至少需要以下两种类型的访问权:

• Event Streams 集群资源类型的读取者角色访问权。
• 读取器角色访问与检索到的架构匹配的架构资源。

更新全局规则

可通过向/rules/ {rule-type} 终端发送PUT请求来更新全局兼容性规则（其中，{rule-type} 标识要更新的全局规则类型——目前仅支持COMPATIBILITY类型），并在请求正文中包含新的规则配置。 如果请求成功，将在响应的有效内容中返回新更新的规则配置以及状态码 200（正常）。

请求正文中发送的JSON文档必须具有以下属性：

示例 curl 请求：

curl -u token:$APIKEY -X PUT $URL/rules/COMPATIBILITY -d '{"type":"COMPATIBILITY","config":"BACKWARD"}'

示例响应：

{"type":"COMPATIBILITY","config":"BACKWARD"}

更新全局规则配置至少需要以下角色：

• Event Streams 集群资源类型的管理者角色访问权。

这将生成 Activity Tracker 事件以报告相应操作。 有关更多信息，请参阅 Activity Tracker 事件。

获取全局规则的当前值

通过向/rules/ {rule-type} 终端发送GET请求，可以获取全局规则的当前值（其中 {rule-type} 是要获取的全局规则的类型——目前仅支持兼容性类型）。 如果请求成功，将在响应的有效内容中返回当前规则配置以及状态码 200（正常）。

示例 curl 请求：

curl -u token:$APIKEY $URL/rules/COMPATIBILITY

示例响应：

{"type":"COMPATIBILITY","config":"BACKWARD"}

获取全局规则配置至少需要以下角色：

• Event Streams 集群资源类型的读取者角色访问权。

创建基于模式的规则

规则可以应用于特定架构，通过向 /artifacts/{schema-id}/rules 端点发送POST请求（其中 {schema-id} 是架构的ID），覆盖任何已设置的通用规则，请求正文中包含新规则的类型和值（目前仅支持兼容性类型）。 如果成功，将返回空的响应和状态码 204（无内容）。

示例 curl 请求：

curl -u token:$APIKEY $URL/artifacts/my-schema/rules -d '{"type":"COMPATIBILITY","config":"FORWARD"}'

创建基于模式的规则至少需要以下角色：

• Event Streams 集群资源类型的读取者角色访问权。
• 经理角色可访问规则所适用的架构资源。

这将生成 Activity Tracker 事件以报告相应操作。 有关更多信息，请参阅 Activity Tracker 事件。

获取基于模式的规则

要检索应用于特定架构的规则类型的当前值，请向 /artifacts/{schema-id}/rules/{rule-type} 端点发送GET请求（其中 {schema-id} 是架构的ID，{rule-type} 是要检索的全局规则的类型——目前仅支持的类型是兼容性）。 如果请求成功，将在响应的有效内容中返回当前规则值以及状态码 200（正常）。

示例 curl 请求：

curl -u token:$APIKEY $URL/artifacts/my-schema/rules/COMPATIBILITY

示例响应：

{"type":"COMPATIBILITY","config":"FORWARD"}

获取基于模式的规则至少需要以下角色：

• Event Streams 集群资源类型的读取者角色访问权。
• 要应用规则的模式资源的读取者角色访问权。

更新基于模式的规则

通过向 /artifacts/{schema-id}/rules/{rule-type} 终端发送PUT请求，可以修改特定架构的规则（其中 {schema-id} 是架构的ID，{rule-type} 是要检索的全局规则的类型——目前仅支持兼容性类型）。 如果请求成功，将在响应的有效内容中返回新更新的规则配置以及状态码 200（正常）。

示例 curl 请求：

curl -u token:$APIKEY -X PUT $URL/artifacts/my-schema/rules/COMPATIBILITY -d '{"type":"COMPATIBILITY","config":"BACKWARD"}'

示例响应：

{"type":"COMPATIBILITY","config":"BACKWARD"}

更新基于模式的规则至少需要以下角色：

• Event Streams 集群资源类型的读取者角色访问权。
• 要应用规则的模式资源的管理者角色访问权。

这将生成 Activity Tracker 事件以报告相应操作。 有关更多信息，请参阅 Activity Tracker 事件。

删除基于模式的规则

通过向 /artifacts/{schema-id}/rules/{rule-type} 终端发送DELETE请求，可以删除特定架构所适用的规则（其中，{schema-id} 是架构的ID，{rule-type} 是要检索的全局规则的类型——目前仅支持兼容性类型）。 如果请求成功，将返回空的响应和状态码 204（无内容）。

示例 curl 请求：

curl -u token:$APIKEY -X DELETE $URL/artifacts/my-schema/rules/COMPATIBILITY

删除基于模式的规则至少需要以下角色：

• Event Streams 集群资源类型的读取者角色访问权。
• 要应用规则的模式资源的管理者角色访问权。

这将生成 Activity Tracker 事件以报告相应操作。 有关更多信息，请参阅 Activity Tracker 事件。