Utilizzo del registro dello schema Event Streams

Schema 1

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

Schema 2

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

Schema 3

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

Lo schema 1 e lo schema 2 sono schemi distinti e il registro li memorizza come schemi separati. Non possono essere utilizzati in modo intercambiabile perché elencano i campi author e title in un ordine diverso. I dati codificati con lo schema 1 non verranno decodificati correttamente se il processo di decodifica ha utilizzato lo schema 2.

Quando si utilizza SerDes per creare il nuovo schema nell'ordine Schema 1, Schema 2 e Schema 3, il risultato sarà due nuovi schemi. Lo schema 1 e lo schema 2 sono diversi ma lo schema 3 è l'equivalente dello schema 2.

Quando si creano gli schemi utilizzando l'API REST, gli schemi vengono considerati corrispondenti solo se sono testualmente gli stessi, inclusi tutti i campi descrittivi e di ordinamento degli attributi. Ciò consente il caso in cui si desidera che lo schema 3 sia uno schema diverso.

Autenticazione

Per accedere al registro schema, è necessaria anche una serie di credenziali che possono essere utilizzate per l'autenticazione con il registro. Esistono due opzioni, l'autenticazione di base con una chiave API o l'autenticazione del token di connessione.

Gli esempi in questo documento mostrano l'utilizzo della chiave API, ma è possibile utilizzare entrambe le opzioni.

curl -u token:$APIKEY ...

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

Errori

Se si verifica una condizione di errore, il registro dello schema restituisce un codice di stato di tipo " non-2XX " ( HTTP ). Il corpo della risposta contiene un oggetto JSON nel formato seguente:

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

Le proprietà dell'oggetto JSON di errore sono le seguenti:

Imposta uno stato schema

Questo punto finale viene utilizzato per impostare lo stato di uno schema nel registro su ENABLED o DISABLED. Lo stato di uno schema può essere impostato emettendo una richiesta PUT all'endpoint /artifacts/{schema-id}/state (dove {schema-id} è l'ID dello schema). Se la richiesta ha esito positivo, viene restituita una risposta vuota e un codice di stato di 204 (nessun contenuto).

Richiesta curl di esempio:

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

L'impostazione dello stato di uno schema richiede:

• Accesso ruolo gestore alla risorsa dello schema che corrisponde allo schema modificato.

Imposta uno stato di versione dello schema

Questo endpoint viene utilizzato per impostare lo stato di una versione di uno schema nel registro su ENABLED o DISABLED. Lo stato di una versione dello schema può essere impostato emettendo una richiesta PUT all'endpoint /artifacts/{schema-id}/versions/{version}/state (dove {schema-id} è l'ID dello schema e {version} è il numero di versione della versione dello schema). Se la richiesta ha esito positivo, viene restituita una risposta vuota e un codice di stato di 204 (nessun contenuto).

Richiesta curl di esempio:

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

L'impostazione di uno stato di versione dello schema richiede:

• Accesso del ruolo gestore alla risorsa dello schema che corrisponde allo schema che si sta modificando.

Crea uno schema

Questo endpoint viene utilizzato per memorizzare uno schema nel registro. I dati dello schema vengono inviati come corpo della richiesta POST. È possibile includere un ID per lo schema utilizzando il file ‘X-Registry-ArtifactId' intestazione della richiesta. Se questa intestazione non è presente nella richiesta, viene generato un ID. L'intestazione del tipo di contenuto deve essere impostata su "application/json".

Richiesta curl di esempio:

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"}]}'

Risposta di esempio:

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

La creazione di uno schema richiede almeno entrambi:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.
• Accesso del ruolo writer alla risorsa dello schema che corrisponde allo schema creato.

Un evento del programma di traccia dell'attività viene generato per segnalare l'azione. Per ulteriori informazioni, vedi Eventi di Activity Tracker.

Elenca schemi

È possibile creare un elenco di ID di tutti gli schemi memorizzati nel registro effettuando una richiesta GET all'endpoint /artifacts. È possibile formattare la risposta utilizzando il parametro jsonformat (sono supportati solo i formati string e object ). Il formato stringa è quello predefinito e restituisce un array di ID risorsa utente (stringhe). Solo le risorse utente abilitate sono incluse nell'array quando questa opzione è impostata. Il formato dell'oggetto restituisce un oggetto JSON che contiene un array in cui ciascuna voce nell'array corrisponde a una risorsa utente nel registro. Quando questa opzione è impostata, vengono restituite entrambe le risorse abilitate e disabilitate.

Richiesta curl di esempio:

curl -u token:$APIKEY $URL/artifacts

oppure

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

oppure

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

Risposta di esempio quando jsonformat è stringa o non è fornito (valore predefinito stringa):

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

Risposta di esempio quando jsonformat è oggetto:

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

L'elenco degli schemi richiede almeno:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.

Stato ed eliminazione degli schemi

L'eliminazione dello schema è un processo a due fasi. La prima fase dell'eliminazione conserva lo schema nel registro, ma lo nasconde ad alcune operazioni. La seconda fase rimuove definitivamente lo schema, ma può essere applicata solo dopo la prima fase. Il processo di eliminazione in due fasi si applica a livello di risorsa utente e anche a livello di versione.

Le due fasi dell'eliminazione vengono eseguite con uno stato abilitato o disabilitato associato sia alle risorse utente che alle versioni (prima fase) ed eliminando le API per le risorse e le versioni (seconda fase).

Una risorsa utente o una versione disabilitata può essere rilevata utilizzando una proprietà 'state' restituita dalle operazioni che elencano le risorse utente o le versioni oppure richiamando i dettagli di una risorsa utente o versione. Gli schemi disabilitati vengono conteggiati nella quota di schema di 1000 schemi per istanza Enterprise.

Elimina uno schema

Gli schemi vengono eliminati dal registro immettendo una richiesta DELETE all'endpoint /artifacts/{schema-id} (dove {schema-id} è l'ID dello schema). Se l'operazione ha esito positivo, viene restituita una risposta vuota e un codice di stato di 204 (nessun contenuto).

Richiesta curl di esempio:

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

L'eliminazione di uno schema richiede almeno entrambi:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.
• Accesso ruolo gestore alla risorsa dello schema che corrisponde allo schema eliminato.

Un evento del programma di traccia dell'attività viene generato per segnalare l'azione. Per ulteriori informazioni, vedi Eventi di Activity Tracker.

Creare una nuova versione di uno schema

Per creare una nuova versione di uno schema, effettuare una richiesta POST all'endpoint /artifacts/{schema-id}/versions (dove {schema-id} è l'ID dello schema). Il contenuto della richiesta deve contenere la nuova versione dello schema.

Se la richiesta ha esito positivo, il nuovo schema viene creato come la versione più recente dello schema, con un numero di versione appropriato e viene restituita una risposta con codice di stato 200 (OK) e viene restituito un payload che contiene i metadati che descrivono la nuova versione (incluso il numero di versione).

Richiesta curl di esempio:

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"}]}'

Risposta di esempio:

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

La creazione di una nuova versione di uno schema richiede almeno entrambi:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.
• Accesso ruolo writer alla risorsa dello schema che corrisponde allo schema che ottiene una nuova versione.

Un evento del programma di traccia dell'attività viene generato per segnalare l'azione. Per ulteriori informazioni, vedi Eventi di Activity Tracker.

Ottenere la versione più recente di un schema

Per richiamare l'ultima versione di uno schema particolare, effettuare una richiesta GET all'endpoint /artifacts/{schema-id} (dove {schema-id} è l'ID dello schema). Se l'operazione ha esito positivo, l'ultima versione dello schema viene restituita nel payload della risposta.

Richiesta curl di esempio:

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

Risposta di esempio:

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

Per ottenere la versione più recente di uno schema è necessario almeno:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.
• Accesso del ruolo di lettore alla risorsa di schema che corrisponde allo schema richiamato.

Ottenimento di una versione specifica di uno schema

Per richiamare una versione specifica di uno schema, effettuare una richiesta GET all'endpoint /artifacts/{schema-id}/versions/{version} (dove {schema-id} è l'ID dello schema e {version} è il numero di versione della versione specifica che è necessario richiamare). Se l'operazione ha esito positivo, la versione specificata dello schema viene restituita nel payload della risposta.

Esempio di richiesta curl

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

Risposta di esempio:

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

Per ottenere la versione più recente di uno schema è necessario almeno:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.
• Accesso del ruolo di lettore alla risorsa di schema che corrisponde allo schema richiamato.

Elenco di tutte le versioni di un schema

Per elencare tutte le versioni di uno schema attualmente memorizzate nel registro, effettuare una richiesta GET all'endpoint /artifacts/{schema-id}/versions (dove {schema-id} è l'ID dello schema). Se l'operazione ha esito positivo, viene restituito un elenco di tutti i numeri di versione correnti per lo schema nel payload della risposta. È possibile formattare la risposta utilizzando il parametro jsonformat (sono supportati solo i formati number e object ). Se si specifica 'number' (valore predefinito), la risposta è un array di valori numerici che corrisponde alle versioni abilitate della risorsa utente (le versioni disabilitate vengono omesse). È lo stesso formato dell'endpoint attualmente generato. Se si specifica 'object', la risposta è un oggetto JSON che contiene un array di oggetti JSON che rappresentano le versioni della risorsa utente. Entrambe le versioni, abilitata e disabilitata, sono incluse nell'array.

Richiesta curl di esempio:

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

oppure

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

oppure

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

Risposta di esempio quando jsonformat è un numero o non viene fornito (valore predefinito: numero):

[1,3,4,6,7]

Risposta di esempio quando jsonformat è oggetto:

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

Il richiamo dell'elenco di versioni disponibili di uno schema richiede almeno entrambi:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.
• Accesso del ruolo di lettore alla risorsa di schema che corrisponde allo schema richiamato.

Eliminazione di una versione di uno schema

Le versioni dello schema vengono eliminate dal registro emettendo una richiesta DELETE all'endpoint /artifacts/{schema-id}/versions/{version} (dove {schema-id} è l'ID dello schema e {version} è il numero di versione della versione dello schema). Se l'operazione ha esito positivo, viene restituita una risposta vuota e un codice di stato di 204 (nessun contenuto). L'eliminazione dell'unica versione rimanente di uno schema elimina anche lo schema.

Richiesta curl di esempio:

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

L'eliminazione di una versione dello schema richiede almeno entrambi:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.
• Accesso ruolo gestore alla risorsa dello schema che corrisponde allo schema eliminato.

Un evento del programma di traccia dell'attività viene generato per segnalare l'azione. Per ulteriori informazioni, vedi Eventi di Activity Tracker.

Acquisizione dell'ID univoco globale specifico di una versione dello schema

Per richiamare un ID univoco globale specifico di una versione dello schema, effettuare una richiesta GET all'endpoint /artifacts/{artifactId}/versions/{version}/meta (dove {artifactId} è l'ID della risorsa e {version} è il numero di versione della versione specifica che è necessario richiamare). Se l'operazione ha esito positivo, l'ID univoco globale specifico di una versione dello schema viene restituito nel payload della risposta.

Richiesta curl di esempio:

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

Risposta di esempio:

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

Il richiamo dell'ID univoco globale di una versione dello schema richiede almeno i seguenti tipi di accesso:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.
• Accesso del ruolo di lettore alla risorsa di schema che corrisponde allo schema richiamato.

Aggiornamento di una regola globale

Le regole di compatibilità globale possono essere aggiornate emettendo una richiesta PUT all'endpoint /rules/{rule-type} (dove {rule-type} identifica il tipo di regola globale da aggiornare - attualmente l'unico tipo supportato è COMPATIBILITY), con la nuova configurazione della regola nel corpo della richiesta. Se la richiesta ha esito positivo, la configurazione della regola appena aggiornata viene restituita nel payload della risposta, insieme al codice di stato 200 (OK).

Il documento JSON inviato nel corpo della richiesta deve avere le seguenti proprietà:

Richiesta curl di esempio:

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

Risposta di esempio:

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

L'aggiornamento di una configurazione di regole globali richiede almeno:

• Accesso del ruolo di gestore al tipo di risorsa cluster Event Streams.

Un evento del programma di traccia dell'attività viene generato per segnalare l'azione. Per ulteriori informazioni, vedi Eventi di Activity Tracker.

Acquisizione del valore corrente di una regola globale

Il valore corrente di una regola globale viene richiamato emettendo una richiesta GET all'endpoint /rules/{rule-type} (dove {rule-type} è il tipo di regola globale da richiamare - attualmente l'unico tipo supportato è COMPATIBILITY). Se la richiesta ha esito positivo, la configurazione della regola corrente viene restituita nel payload della risposta, insieme al codice di stato 200 (OK).

Richiesta curl di esempio:

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

Risposta di esempio:

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

Il richiamo della configurazione della regola globale richiede almeno:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.

Creazione di una regola per schema

Le regole possono essere applicate a uno schema specifico, sovrascrivendo le regole globali impostate, effettuando una richiesta POST all'endpoint /artifacts/{schema-id}/rules (dove {schema-id} è l'ID dello schema), con il tipo e il valore della nuova regola contenuto nel corpo della richiesta (attualmente l'unico tipo supportato è COMPATIBILITY). Se l'operazione ha esito positivo, vengono restituiti una risposta vuota e un codice di stato di 204 (nessun contenuto).

Richiesta curl di esempio:

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

La creazione di regole per schema richiede almeno:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.
• Accesso ruolo gestore alla risorsa dello schema per cui si applica la regola.

Un evento del programma di traccia dell'attività viene generato per segnalare l'azione. Per ulteriori informazioni, vedi Eventi di Activity Tracker.

Richiamo di una regola per schema

Per richiamare il valore corrente di un tipo di regola applicato a uno schema specifico, viene effettuata una richiesta GET all'endpoint /artifacts/{schema-id}/rules/{rule-type} (dove {schema-id} è l'ID dello schema e {rule-type} è il tipo di regola globale da richiamare - attualmente l'unico tipo supportato è COMPATIBILITY). Se la richiesta ha esito positivo, il valore della regola corrente viene restituito nel payload della risposta, insieme al codice di stato 200 (OK).

Richiesta curl di esempio:

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

Risposta di esempio:

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

L'ottenimento delle regole per schema richiede almeno:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.
• Accesso ruolo di lettore alla risorsa dello schema a cui si applica la regola.

Aggiornamento di una regola per schema

Le regole applicate a uno schema specifico vengono modificate effettuando una richiesta PUT all'endpoint /artifacts/{schema-id}/rules/{rule-type} (dove {schema-id} è l'ID dello schema e {rule-type} è il tipo di regola globale da richiamare - attualmente l'unico tipo supportato è COMPATIBILITY). Se la richiesta ha esito positivo, la configurazione della regola appena aggiornata viene restituita nel payload della risposta, insieme al codice di stato 200 (OK).

Richiesta curl di esempio:

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

Risposta di esempio:

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

L'aggiornamento di una regola per schema richiede almeno:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.
• Accesso ruolo gestore alla risorsa schema a cui si applica la regola.

Un evento del programma di traccia dell'attività viene generato per segnalare l'azione. Per ulteriori informazioni, vedi Eventi di Activity Tracker.

Eliminazione di una regola per schema

Le regole applicate a uno schema specifico vengono eliminate effettuando una richiesta DELETE all'endpoint /artifacts/{schema-id}/rules/{rule-type} (dove {schema-id} è l'ID dello schema e {rule-type} è il tipo di regola globale da richiamare - attualmente l'unico tipo supportato è COMPATIBILITY). Se la richiesta ha esito positivo, viene restituita una risposta vuota, con un codice di stato di 204 (nessun contenuto).

Richiesta curl di esempio:

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

L'eliminazione di una regola per schema richiede almeno:

• Accesso del ruolo lettore al tipo di risorsa cluster Event Streams.
• Accesso ruolo gestore alla risorsa schema a cui si applica la regola.

Un evento del programma di traccia dell'attività viene generato per segnalare l'azione. Per ulteriori informazioni, vedi Eventi di Activity Tracker.