Usando o Registro do Esquema Event Streams

Esquema 1

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

Esquema 2

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

Esquema 3

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

O esquema 1 e o Schema 2 são esquemas distintos e o registro armazena-os como esquemas separados. Eles não podem ser usados de forma intercambiável porque listam os campos author e title em uma ordem diferente. Os dados codificados com Schema 1 não seriam decodificados corretamente se o processo de decodificação utilizasse o Schema 2.

Ao usar o SerDes para criar o novo esquema na ordem do Esquema 1, Esquema 2 e Esquema 3, o resultado seria dois novos esquemas. O esquema 1 e o Schema 2 são diferentes mas o Schema 3 é o equivalente a Schema 2.

Ao criar esquemas usando a API REST, os esquemas são considerados correspondentes apenas se forem textualmente os mesmos, incluindo toda a ordenação de atributo e campos descritivos. Isso é para permitir o caso em que você deseja que o Schema 3 seja um esquema diferente.

Autenticação

Para acessar o Registro de Esquema, também é necessário um conjunto de credenciais que possa ser usado para autenticar com o registro.. Há duas opções, autenticação básica com uma chave de API ou autenticação de token de acesso.

Os exemplos neste documento mostram o uso da chave de API, mas qualquer opção pode ser usada.

curl -u token:$APIKEY ...

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

Erros

Se for encontrada uma condição de erro, o Schema Registry retornará um código de status non-2XX range HTTP. O corpo da resposta contém um objeto JSON no seguinte formato:

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

As propriedades do objeto JSON de erro são as seguintes:

Configure um estado do esquema

Esse terminal é usado para configurar o estado de um esquema no registro para ENABLED ou DISABLED O estado de um esquema pode ser configurado emitindo uma solicitação PUT para o terminal /artifacts/{schema-id}/state (em que {schema-id} é o ID do esquema). Se a solicitação for bem-sucedida, será retornada uma resposta vazia e um código de status 204 (sem conteúdo).

Exemplo de solicitação curl:

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

A configuração de um estado de esquema requer:

• Acesso da função de administrador ao recurso de esquema que corresponde ao esquema modificado.

Configurar um estado de versão de esquema....

Esse terminal é usado para definir o estado de uma versão de esquema no registro para ENABLED ou DISABLED O estado de uma versão de esquema pode ser configurado emitindo uma solicitação PUT para o terminal /artifacts/{schema-id}/versions/{version}/state (em que {schema-id} é o ID do esquema e {version} é o número da versão do esquema). Se a solicitação for bem-sucedida, será retornada uma resposta vazia e um código de status 204 (sem conteúdo).

Exemplo de solicitação curl:

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

A configuração de um estado da versão do esquema requer:

• Acesso da função de administrador ao recurso de esquema que corresponde ao esquema que está sendo modificado.

Criar um esquema

Esse terminal é usado para armazenar um esquema no registro. Os dados do esquema são enviados como o corpo da solicitação POST. Uma ID para o esquema pode ser incluída usando o cabeçalho de solicitação ‘X-Registry-ArtifactId'. Se esse cabeçalho não estiver presente na solicitação, será gerada uma ID. O cabeçalho do tipo de conteúdo deve ser configurado como “application/json”.

Exemplo de solicitação 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"}]}'

Resposta de exemplo:

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

A criação de um esquema requer pelo menos ambos:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.
• Acesso da função de escritor ao recurso de esquema que corresponde ao esquema criado.

Um evento rastreador de atividade é gerado para relatar a ação. Para obter mais informações, consulte Eventos do Activity Tracker.

Listar esquemas

Você pode gerar uma lista das IDs de todos os esquemas armazenados no registro fazendo uma solicitação GET para o ponto de extremidade /artifacts. É possível formatar a resposta usando o parâmetro jsonformat (apenas os formatos string e object são suportados. O formato de sequência é o padrão e retorna uma matriz de IDs de artefatos (sequências). Apenas os artefatos ativados são incluídos na matriz quando essas opções são configuradas O formato do objeto retorna um objeto JSON que contém uma matrizes em que cada entrada na matriz corresponde a um artefato no registro Ambos os artefatos ativados e desativados são retornados quando essa opção é configurada

Exemplo de solicitação curl:

curl -u token:$APIKEY $URL/artifacts

ou

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

ou

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

Resposta de exemplo quando jsonformat é sequência ou não fornecido (padronizado para sequência):

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

Exemplo de resposta quando jsonformat é objeto:

{"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}

A listagem de esquemas exige pelo menos:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.

Estado e exclusão de esquemas

A exclusão do esquema é um processo de dois estágios O primeiro estágio de exclusão preserva o esquema no registro, mas o oculta de algumas operações.. O segundo estágio remove permanentemente o esquema, mas só pode ser aplicado após o primeiro estágio O processo de exclusão de dois estágios aplica-se no nível do artefato e também no nível da versão

Os dois estágios de exclusão são feitos tendo um status ativado ou desativado associado a artefatos e versões (primeiro estágio) e excluindo APIs para recursos e versões (segundo estágio).

Um artefato ou versão que foi desativado pode ser descoberto usando uma propriedade 'state' que é retornada por operações que listam artefatos ou versões ou obtendo os detalhes de um artefato ou versão. Os esquemas desativados contam para a cota de esquema de 1000 esquemas por instância Corporativa

Excluir um esquema

Os esquemas são excluídos do registro por meio de uma solicitação DELETE para o ponto de extremidade /artifacts/{schema-id} (em que {schema-id} é a ID do esquema). Se bem-sucedido, uma resposta vazia e um código de status de 204 (sem conteúdo) serão retornados.

Exemplo de solicitação curl:

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

A exclusão de um esquema exige pelo menos ambos:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.
• Acesso da função de administrador ao recurso de esquema que corresponde ao esquema excluído.

Um evento rastreador de atividade é gerado para relatar a ação. Para obter mais informações, consulte Eventos do Activity Tracker.

Criar uma nova versão de um esquema

Para criar uma nova versão de um esquema, faça uma solicitação POST para o ponto de extremidade /artifacts/{schema-id}/versions, (em que {schema-id} é a ID do esquema). O corpo da solicitação deve conter a nova versão do esquema.

Se a solicitação for bem-sucedida, o novo esquema será criado como a versão mais recente do esquema, com um número de versão apropriado, e será retornada uma resposta com o código de status 200 (OK) e uma carga útil que contém metadados que descrevem a nova versão (incluindo o número da versão).

Exemplo de solicitação 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"}]}'

Resposta de exemplo:

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

A criação de uma nova versão de um esquema exige pelo menos ambos:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.
• Acesso da função de escritor ao recurso de esquema que corresponde ao esquema que recebe uma nova versão.

Um evento rastreador de atividade é gerado para relatar a ação. Para obter mais informações, consulte Eventos do Activity Tracker.

Obter a versão mais recente de um esquema

Para recuperar a versão mais recente de um determinado esquema, faça uma solicitação GET para o ponto de extremidade /artifacts/{schema-id} (em que {schema-id} é a ID do esquema). Se bem-sucedido, a versão mais recente do esquema será retornada na carga útil da resposta.

Exemplo de solicitação curl:

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

Resposta de exemplo:

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

Para obter a versão mais recente de um esquema, é necessário:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.
• Acesso da função de leitor ao recurso de esquema que corresponde ao esquema recuperado.

Obtendo uma versão específica de um esquema

Para recuperar uma versão específica de um esquema, faça uma solicitação GET para o ponto de extremidade /artifacts/{schema-id}/versions/{version} (em que {schema-id} é a ID do esquema e {version} é o número da versão específica que você precisa recuperar). Se bem-sucedido, a versão especificada do esquema será retornada na carga útil da resposta.

Exemplo de solicitação de curl

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

Resposta de exemplo:

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

Para obter a versão mais recente de um esquema, é necessário:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.
• Acesso da função de leitor ao recurso de esquema que corresponde ao esquema recuperado.

Listando todas as versões de um esquema

Para listar todas as versões de um esquema atualmente armazenadas no registro, faça uma solicitação GET para o ponto de extremidade /artifacts/{schema-id}/versions (em que {schema-id} é a ID do esquema). Se bem-sucedido, uma lista de todos os números de versão atuais para o esquema será retornada na carga útil da resposta. É possível formatar a resposta usando o parâmetro jsonformat (apenas os formatos number e object são suportados. Se você especificar 'number' (o padrão), a resposta será uma matriz de valores numéricos que correspondem às versões ativadas do artefato (versões desativadas são omitidas). Ele é o mesmo formato que o terminal gerado atualmente Se você especificar 'object', a resposta será um objeto JSON que contém uma matriz de objetos JSON representando versões do artefato. As versões ativadas e desativadas estão incluídas na matriz.

Exemplo de solicitação curl:

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

ou

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

ou

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

Exemplo de resposta quando jsonformat é número ou não fornecido (padronizando para número):

[1,3,4,6,7]

Exemplo de resposta quando jsonformat é objeto:

{"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}

A obtenção da lista de versões disponíveis de um esquema exige pelo menos ambos:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.
• Acesso da função de leitor ao recurso de esquema que corresponde ao esquema recuperado.

Excluindo uma versão de um esquema

As versões do esquema são excluídas do registro por meio de uma solicitação DELETE para o ponto de extremidade /artifacts/{schema-id}/versions/{version} (em que {schema-id} é a ID do esquema e {version} é o número da versão do esquema). Se bem-sucedido, uma resposta vazia e um código de status de 204 (sem conteúdo) serão retornados. A exclusão da única versão restante de um esquema também exclui o esquema.

Exemplo de solicitação curl:

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

A exclusão de uma versão de esquema requer pelo menos ambos:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.
• Acesso da função de administrador ao recurso de esquema que corresponde ao esquema excluído.

Um evento rastreador de atividade é gerado para relatar a ação. Para obter mais informações, consulte Eventos do Activity Tracker.

Obtendo o ID exclusivo global específico de uma versão de esquema

Para recuperar um ID exclusivo global específico de uma versão de esquema, faça uma solicitação GET para o ponto de extremidade /artifacts/{artifactId}/versions/{version}/meta (em que {artifactId} é o ID do artefato e {version} é o número da versão específica que você precisa recuperar). Se bem-sucedido, o ID exclusivo global específico de uma versão de esquema será retornado na carga útil da resposta.

Exemplo de solicitação curl:

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

Resposta de exemplo:

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

A obtenção do ID exclusivo global de uma versão de esquema requer pelo menos os dois tipos de acesso a seguir:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.
• Acesso da função de leitor ao recurso de esquema que corresponde ao esquema recuperado.

Atualizando uma regra global

As regras de compatibilidade global podem ser atualizadas emitindo uma solicitação PUT para o ponto de extremidade /rules/ {rule-type} (em que {rule-type} identifica o tipo de regra global a ser atualizada - atualmente, o único tipo compatível é COMPATIBILITY), com a nova configuração de regra no corpo da solicitação. Se a solicitação for bem-sucedida, a configuração de regra atualizada recentemente será retornada na carga útil da resposta com um código de status de 200 (OK).

O documento JSON que é enviado no corpo da solicitação deve ter as seguintes propriedades:

Exemplo de solicitação curl:

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

Resposta de exemplo:

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

A atualização de uma configuração de regra global exige pelo menos:

• Acesso de função de gerenciador ao tipo de recurso de cluster Event Streams.

Um evento rastreador de atividade é gerado para relatar a ação. Para obter mais informações, consulte Eventos do Activity Tracker.

Obtendo o valor atual de uma regra global

O valor atual de uma regra global é recuperado por meio da emissão de uma solicitação GET para o ponto de extremidade /rules/ {rule-type} (em que {rule-type} é o tipo de regra global a ser recuperada - atualmente, o único tipo suportado é COMPATIBILITY). Se a solicitação for bem-sucedida, a configuração de regra atual será retornada na carga útil da resposta, com um código de status de 200 (OK).

Exemplo de solicitação curl:

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

Resposta de exemplo:

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

A obtenção da configuração de regra global exige pelo menos:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.

Criando uma regra por esquema

As regras podem ser aplicadas a um esquema específico, substituindo quaisquer regras globais que tenham sido definidas, fazendo uma solicitação POST para o ponto de extremidade /artifacts/{schema-id}/rules (em que {schema-id} é a ID do esquema), com o tipo e o valor da nova regra contidos no corpo da solicitação (atualmente, o único tipo suportado é COMPATIBILITY). Se bem-sucedido, uma resposta vazia e um código de status de 204 (sem conteúdo) serão retornados.

Exemplo de solicitação curl:

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

A criação de regras por esquema exige pelo menos:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.
• Acesso da função de administrador ao recurso de esquema ao qual a regra se aplica.

Um evento rastreador de atividade é gerado para relatar a ação. Para obter mais informações, consulte Eventos do Activity Tracker.

Obtendo uma regra por esquema

Para recuperar o valor atual de um tipo de regra aplicada a um esquema específico, é feita uma solicitação GET para o ponto de extremidade /artifacts/{schema-id}/rules/{rule-type} (em que {schema-id} é a ID do esquema e {rule-type} é o tipo de regra global a ser recuperada - atualmente, o único tipo suportado é COMPATIBILITY). Se a solicitação for bem-sucedida, o valor da regra atual será retornado na carga útil da resposta, com um código de status de 200 (OK).

Exemplo de solicitação curl:

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

Resposta de exemplo:

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

A obtenção de regras por esquema exige pelo menos:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.
• Acesso de função de leitor ao recurso de esquema ao qual a regra se aplica.

Atualizando uma regra por esquema

As regras aplicadas a um esquema específico são modificadas por meio de uma solicitação PUT para o ponto de extremidade /artifacts/{schema-id}/rules/{rule-type} (em que {schema-id} é a ID do esquema e {rule-type} é o tipo de regra global a ser recuperada - atualmente, o único tipo suportado é COMPATIBILITY). Se a solicitação for bem-sucedida, a configuração de regra atualizada recentemente será retornada na carga útil da resposta com um código de status de 200 (OK).

Exemplo de solicitação curl:

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

Resposta de exemplo:

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

A atualização de uma regra por esquema exige pelo menos:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.
• Acesso de função de gerenciador ao recurso de esquema ao qual a regra se aplica.

Um evento rastreador de atividade é gerado para relatar a ação. Para obter mais informações, consulte Eventos do Activity Tracker.

Excluindo uma regra por esquema

As regras aplicadas a um esquema específico são excluídas por meio de uma solicitação DELETE para o ponto de extremidade /artifacts/{schema-id}/rules/{rule-type} (em que {schema-id} é a ID do esquema e {rule-type} é o tipo de regra global a ser recuperada - atualmente, o único tipo suportado é COMPATIBILITY). Se a solicitação for bem-sucedida, uma resposta vazia será retornada, com um código de status de 204 (sem conteúdo).

Exemplo de solicitação curl:

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

A exclusão de uma regra por esquema exige pelo menos:

• Acesso de função de leitor ao tipo de recurso de cluster do Event Streams.
• Acesso de função de gerenciador ao recurso de esquema ao qual a regra se aplica.

Um evento rastreador de atividade é gerado para relatar a ação. Para obter mais informações, consulte Eventos do Activity Tracker.