Compartilhar via

Biblioteca de clientes do Serializador Json do Registro de Esquema do Azure para JavaScript – versão 1.0.0

  • Artigo

O Registro de Esquema do Azure é um serviço de repositório de esquema hospedado pelos Hubs de Eventos do Azure, fornecendo armazenamento de esquema, controle de versão e gerenciamento. Esse pacote fornece um serializador Json capaz de serializar e desserializar cargas que contêm dados serializados por Json.

Links de chave:

Introdução

Pré-requisitos

  • Uma assinatura do Azure
  • Um recurso existente do Registro de Esquema

Instalar o pacote @azure/schema-registry-json

Instale a biblioteca de clientes da Análise de Texto do Azure para JavaScript com npm:

npm install @azure/schema-registry-json

Principais conceitos

JsonSchemaSerializer

Fornece a API para serializar e desserializar de JSON encapsulado em uma mensagem com um campo de tipo de conteúdo que contém a ID do esquema. Usa SchemaRegistryClient do pacote @azure/schema-registry para obter IDs de esquema da definição de esquema ou vice-versa. A API fornecida tem cache interno para evitar chamar o serviço de registro de esquema quando possível.

Mensagens

Por padrão, o serializador criará mensagens estruturadas da seguinte maneira:

  • data: uma matriz de bytes que contém dados JSON.

  • contentType: uma cadeia de caracteres do seguinte formato application/json+<Schema ID> em que a parte application/json sinaliza que essa mensagem tem um conteúdo serializado por Json e a parte <Schema Id> é a ID de esquema que o serviço registro de esquema atribuído ao esquema usado para serializar esse conteúdo.

Nem todos os serviços de mensagens são compatíveis com a mesma estrutura de mensagens. Para habilitar a integração com esses serviços, o serializador pode atuar em estruturas de mensagens personalizadas definindo a opção messageAdapter no construtor com um produtor e consumidor de mensagens correspondentes. As bibliotecas de clientes de mensagens do Azure exportam adaptadores padrão para seus tipos de mensagem.

Exemplos

Serializar e desserializar um EventData de @azure/event-hubs

const { DefaultAzureCredential } = require("@azure/identity");
const { createEventDataAdapter } = require("@azure/event-hubs");
const { SchemaRegistryClient } = require("@azure/schema-registry");
const { JsonSchemaSerializer } = require("@azure/schema-registry-json");

async function main(){
  const client = new SchemaRegistryClient(
    "<fully qualified namespace>",
    new DefaultAzureCredential()
  );
  const serializer = new JsonSchemaSerializer(client, {
    groupName: "<group>",
    messageAdapter: createEventDataAdapter(),
  });

  // Example Json schema
  const schema = JSON.stringify({  
    $schema: "http://json-schema.org/draft-04/schema#",
    $id: "person",
    title: "Student",
    description: "A student in the class",
    type: "object",
    properties: {
      name: {
        type: "string",
        description: "The name of the student",
      },
    },
    required: ["name"]
  });

  // Example value that matches the Json schema above
  const value = { name: "Bob" };

  // Serialize value to a message
  const message = await serializer.serialize(value, schema);

  // Deserialize a message to value
  const deserializedValue = await serializer.deserialize(message);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

O serializador não verifica se o valor desserializado corresponde ao esquema, mas fornece uma opção para implementar essa validação. O aplicativo pode passar uma função de retorno de chamada de validação como uma das opções para o método desserializar em que a validação de esquema pode ser implementada. Para ver como a validação pode ser implementada, confira o exemplo de schemaRegistryJsonWithValidation.

Solucionando problemas

O serializador Json se comunica com o serviço do Registro de Esquema conforme necessário para registrar ou consultar esquemas e essas chamadas de serviço podem gerar um restError. Além disso, erros do tipo Error serão gerados quando a serialização ou desserialização falhar. A propriedade cause conterá o erro subjacente que foi gerado do analisador JSON.

Log

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Próximas etapas

Examine os exemplos de diretório para obter exemplos detalhados sobre como usar essa biblioteca.

Contribuindo

Este projeto recebe contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença de Colaborador) declarando que você tem o direito de, e realmente fazer, conceder-nos os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Ao enviar uma solicitação de pull, um CLA-bot determinará automaticamente se você precisa fornecer um CLA e decorar a PR adequadamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios usando nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, consulte as perguntas frequentes sobre o Código de Conduta ou entre em contato com opencode@microsoft.com com perguntas ou comentários adicionais.

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

impressões