Partilhar via

Biblioteca de cliente do Serializador Json do Registo de Esquemas do Azure para JavaScript – versão 1.0.0-beta.1

  • Artigo

O Registo de Esquemas do Azure é um serviço de repositório de esquemas alojado por Hubs de Eventos do Azure, que fornece armazenamento de esquemas, controlo de versões e gestão. Este pacote fornece um serializador Json capaz de serializar e anular a serialização de payloads que contêm dados serializados Json.

Ligações principais:

Introdução

Pré-requisitos

Instalar o pacote @azure/schema-registry-json

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

npm install @azure/schema-registry-json

Conceitos-chave

JsonSerializer

Fornece a API para serializar e anular a serialização do JSON moldado numa mensagem com um campo de tipo de conteúdo que contém o ID de esquema. Utiliza SchemaRegistryClient a partir do pacote @azure/schema-registry para obter IDs de esquema da definição de esquema ou vice-versa. A API fornecida tem cache interna para evitar chamar o serviço de registo de esquemas sempre que possível.

Mensagens

Por predefinição, o serializador irá criar mensagens estruturadas da seguinte forma:

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

  • contentType: uma cadeia do seguinte formato application/json+<Schema ID> em que a application/json parte sinaliza que esta mensagem tem um payload serializado em Json e a <Schema Id> parte é o ID do Esquema que o serviço de Registo de Esquemas atribuiu ao esquema utilizado para serializar este payload.

Nem todos os serviços de mensagens suportam a mesma estrutura de mensagens. Para permitir a integração com esses serviços, o serializador pode atuar em estruturas de mensagens personalizadas ao definir a opção messageAdapter no construtor com um produtor e consumidor de mensagens correspondentes. As bibliotecas de cliente de mensagens do Azure exportam adaptadores predefinidos para os respetivos tipos de mensagens.

Exemplos

Serializar e anular a serialização de um @azure/event-hubs's' EventData

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

const client = new SchemaRegistryClient(
  "<fully qualified namespace>",
  new DefaultAzureCredential()
);
const serializer = new JsonSerializer(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);

O serializador não verifica se o valor desserializado corresponde ao esquema, mas fornece uma opção para implementar essa validação. A aplicação pode transmitir uma função de chamada de retorno de validação como uma das opções para o método de desserialização onde a validação do esquema pode ser implementada. Para ver como a validação pode ser implementada, veja o schemaRegistryJsonWithValidation exemplo.

Resolução de problemas

O serializador Json comunica com o serviço Registo de Esquemas conforme necessário para registar ou consultar esquemas e essas chamadas de serviço podem gerar um RestError. Além disso, serão apresentados erros do tipo Error quando a serialização ou a desserialização falharem. A cause propriedade irá conter o erro subjacente que foi gerado a partir do analisador JSON.

Registo

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos e respostas HTTP, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Passos seguintes

Veja o diretório de exemplos para obter exemplos detalhados sobre como utilizar esta biblioteca.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

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

Impressões