Partilhar via

Biblioteca de cliente Json Serializer do Registro do 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, controle de versão e gerenciamento de esquema. Este pacote fornece um serializador Json capaz de serializar e desserializar cargas úteis contendo dados serializados por Json.

Ligações principais:

Primeiros passos

Pré-requisitos

Instalar o pacote @azure/schema-registry-json

Instale a biblioteca de cliente do Azure Text Analytics para JavaScript com npm:

npm install @azure/schema-registry-json

Conceitos-chave

JsonSchemaSerializer

Fornece API para serializar e desserializar de JSON encapsulado em uma mensagem com um campo de tipo de conteúdo contendo 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 contendo dados JSON.

  • contentType: uma cadeia de caracteres do seguinte formato application/json+<Schema ID> onde a parte application/json sinaliza que esta mensagem tem uma carga serializada em Json, e a parte <Schema Id> é a ID do Esquema, o serviço Registro de Esquema atribuído ao esquema usado para serializar essa carga.

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

Exemplos

Serializar e desserializar uma EventData do @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 de desserialização onde a validação de esquema pode ser implementada. Para ver como a validação pode ser implementada, verifique a amostra de schemaRegistryJsonWithValidation.

Solução de problemas

O serializador Json se comunica com o serviço Schema Registry conforme necessário para registrar ou consultar esquemas e essas chamadas de serviço podem lançar um RestError. Além disso, erros do tipo Error serão lançados quando a serialização ou desserialização falhar. A propriedade cause conterá o erro subjacente que foi lançado do analisador JSON.

Registo

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 tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Próximos passos

Por favor, dê uma olhada no exemplos diretório para obter exemplos detalhados sobre como usar esta biblioteca.

Contribuição

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

Quando você envia uma solicitação pull, um CLA-bot determinará automaticamente se você precisa fornecer um CLA e decorar o 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 Microsoft Open Source Code of Conduct. Para obter mais informações, consulte o de perguntas frequentes sobre o Código de Conduta ou entre em contato com opencode@microsoft.com para obter perguntas ou comentários adicionais.

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

Impressões