Condividi tramite

Libreria client del serializzatore JSON del Registro schemi di Azure per JavaScript - versione 1.0.0

  • Articolo

Registro schemi di Azure è un servizio di repository di schemi ospitato da Hub eventi di Azure, che fornisce l'archiviazione dello schema, il controllo delle versioni e la gestione. Questo pacchetto fornisce un serializzatore Json in grado di serializzare e deserializzare i payload contenenti dati serializzati json.

Collegamenti chiave:

Introduttiva

Prerequisiti

  • Una sottoscrizione di Azure
  • Una risorsa del Registro schemi di esistente

Installare il pacchetto @azure/schema-registry-json

Installare la libreria client di Analisi del testo di Azure per JavaScript con npm:

npm install @azure/schema-registry-json

Concetti chiave

JsonSchemaSerializer

Fornisce l'API per serializzare e deserializzare da JSON incapsulato in un messaggio con un campo tipo di contenuto contenente l'ID dello schema. Usa SchemaRegistryClient dal pacchetto @azure/schema-registry per ottenere GLI ID schema dalla definizione dello schema o viceversa. L'API fornita dispone di cache interna per evitare di chiamare il servizio registro schemi, quando possibile.

Messaggi

Per impostazione predefinita, il serializzatore creerà messaggi strutturati nel modo seguente:

  • data: matrice di byte contenente dati JSON.

  • contentType: una stringa del formato seguente application/json+<Schema ID> in cui la parte application/json segnala che questo messaggio ha un payload serializzato json e la parte <Schema Id> è l'ID schema assegnato allo schema assegnato allo schema usato per serializzare questo payload.

Non tutti i servizi di messaggistica supportano la stessa struttura dei messaggi. Per abilitare l'integrazione con tali servizi, il serializzatore può agire sulle strutture di messaggi personalizzate impostando l'opzione messageAdapter nel costruttore con un producer e un consumer di messaggi corrispondenti. Le librerie client di messaggistica di Azure esportano gli adattatori predefiniti per i tipi di messaggio.

Esempi

Serializzare e deserializzare un EventData di un @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);
});

Il serializzatore non verifica se il valore deserializzato corrisponde allo schema, ma offre un'opzione per implementare tale convalida. L'applicazione può passare una funzione di callback di convalida come una delle opzioni al metodo deserializzato in cui è possibile implementare la convalida dello schema. Per vedere come implementare la convalida, vedere l'esempio di schemaRegistryJsonWithValidation.

Risoluzione dei problemi

Il serializzatore Json comunica con il servizio registro schemi in base alle esigenze per registrare o eseguire query su schemi e tali chiamate al servizio potrebbero generare un RestError. Inoltre, gli errori di tipo Error verranno generati quando la serializzazione o la deserializzazione non riesce. La proprietà cause conterrà l'errore sottostante generato dal parser JSON.

Registrazione

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

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

setLogLevel("info");

Passaggi successivi

Per esempi dettagliati su come usare questa libreria, vedere gli esempi di directory.

Contribuire

Questo progetto accoglie contributi e suggerimenti. La maggior parte dei contributi richiede l'accettazione di un Contratto di licenza collaboratore (CLA) che dichiara di avere il diritto e, in realtà, concedere a Microsoft i diritti per l'uso del contributo. Per informazioni dettagliate, visitare https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determinerà automaticamente se è necessario fornire un cla e decorare la richiesta pull in modo appropriato (ad esempio, etichetta, commento). Seguire semplicemente le istruzioni fornite dal bot. Dovrai eseguire questa operazione una sola volta in tutti i repository usando la nostra cla.

Questo progetto ha adottato la codice di comportamento Microsoft Open Source. Per altre informazioni, vedere domande frequenti sul codice di comportamento o contattare opencode@microsoft.com con eventuali domande o commenti aggiuntivi.

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

impressioni