綱目 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 range 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} 是綱目的 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} 是綱目的 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。 如果請求中沒有此標頭，則會產生一個 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 格式)。 字串格式是預設值，它會傳回構件 ID (字串) 的陣列。 當設定這個選項時，只會將已啟用的構件包含在陣列中。 物件格式會傳回包含陣列的 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 (第二階段) 來完成。

您可以使用列出構件或版本的作業所傳回的「狀況」內容，或取得構件或版本的詳細資料，來探索已停用的構件或版本。 已停用的綱目會計入每個企業實例 1000 個綱目的綱目配額。

刪除綱目

可透過向 /artifacts/{schema-id} 端點（其中 {schema-id} 是模式的 ID）發出 DELETE 請求，從註冊表中刪除模式。 如果成功，則會傳回空的回應和狀態碼 204（無內容）。

curl 要求範例：

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

刪除綱目至少需要兩者：

• 對 Event Streams 叢集資源類型的「讀者」角色存取權。
• 管理員角色存取與刪除的模式相符的模式資源。

會產生 Activity Tracker 事件以報告動作。 如需相關資訊，請參閱 Activity Tracker 事件。

建立綱目的新版本

若要建立模式的新版本，請向 /artifacts/{schema-id}/versions 端點（其中 {schema-id} 是模式的 ID）發出 POST 請求。 要求的內文必須包含綱目的新版本。

如果請求成功，新模式將被建立為模式的最新版本，並帶有適當的版本號，同時會傳回狀態代碼為 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} 端點（其中 {schema-id} 是模式的 ID）發出 GET 請求。 如果成功，則會在回應的有效負載中傳回綱目的最新版本。

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 端點（其中 {schema-id} 是模式的 ID）發出 GET 請求。 如果成功，則會在回應的有效負載中傳回綱目的所有現行版本號碼清單。 您可以使用 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 為數字或未提供 (預設為數字) 時的回應範例:

[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} 端點（其中 {schema-id} 是模式的 ID，{version} 是模式版本的版本號）發出 DELETE 請求，從註冊表中刪除。 如果成功，則會傳回空的回應和狀態碼 204（無內容）。 刪除模式的唯一剩餘版本也會刪除模式。

curl 要求範例：

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

刪除綱目版本至少需要兩者：

• 對 Event Streams 叢集資源類型的「讀者」角色存取權。
• 管理員角色存取與刪除的模式相符的模式資源。

會產生 Activity Tracker 事件以報告動作。 如需相關資訊，請參閱 Activity Tracker 事件。

取得綱目版本的特定廣域唯一 ID

若要擷取模式版本的特定全局唯一 ID，請向 /artifacts/{artifactId}/versions/{version}/meta 端點提出 GET 請求（其中 {artifactId} 是工件的 ID，{version} 是您需要擷取的特定版本的版本號碼）。 如果成功，則會在回應的有效負載中傳回綱目版本的特定廣域唯一 ID。

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}

取得綱目版本的廣域唯一 ID 至少需要下列兩種類型的存取權:

• 對 Event Streams 叢集資源類型的「讀者」角色存取權。
• 讀者角色存取與擷取的模式相符的模式資源。

更新廣域規則

全局相容性規則可以透過向 /rules/ {rule-type} 端點（其中 {rule-type} 識別要更新的全局規則類型 - 目前唯一支援的類型是 COMPATIBILITY）發出 PUT 請求來更新，並在請求的正文中提供新的規則設定。 如果要求成功，則會在回應的有效負載中傳回剛更新的規則配置與狀態碼 200 (OK)。

在請求體中傳送的 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} 是要擷取的全局規則類型 - 目前唯一支援的類型是 COMPATIBILITY)。 如果要求成功，則會在回應的有效負載中傳回現行規則配置與狀態碼 200 (OK)。

curl 要求範例：

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

回應範例：

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

取得廣域規則配置至少需要：

• 對 Event Streams 叢集資源類型的「讀者」角色存取權。

建立每一綱目規則

可透過向 /artifacts/{schema-id}/rules 端點（其中 {schema-id} 是模式的 ID）發出 POST 請求，在請求正文中包含新規則的類型和值（目前唯一支援的類型是 COMPATIBILITY），將規則套用至特定模式，覆寫已設定的任何全局規則。 如果成功，則會傳回空的回應和狀態碼 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} 是要檢索的全局規則類型 - 目前唯一支援的類型是 COMPATIBILITY）。 如果要求成功，則會在回應的有效負載中傳回現行規則值與狀態碼 200 (OK)。

curl 要求範例：

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

回應範例：

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

取得每一綱目規則至少需要：

• 對 Event Streams 叢集資源類型的「讀者」角色存取權。
• 對套用規則的綱目資源的「讀者」角色存取權。

更新每一綱目規則

應用於特定模式的規則可透過向 /artifacts/{schema-id}/rules/{rule-type} 端點（其中 {schema-id} 是模式的 ID，{rule-type} 是要擷取的全局規則類型 - 目前唯一支援的類型是 COMPATIBILITY）發出 PUT 請求來修改。 如果要求成功，則會在回應的有效負載中傳回剛更新的規則配置與狀態碼 200 (OK)。

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} 是要擷取的全局規則類型 - 目前唯一支援的類型是 COMPATIBILITY）。 如果要求成功，則會傳回空的回應和狀態碼 204（無內容）。

curl 要求範例：

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

刪除每一綱目規則至少需要：

• 對 Event Streams 叢集資源類型的「讀者」角色存取權。
• 對套用規則的綱目資源的「管理員」角色存取權。

會產生 Activity Tracker 事件以報告動作。 如需相關資訊，請參閱 Activity Tracker 事件。