Utilizzo dell'API del produttore REST

Event Streams fornisce un'API REST per aiutarti a connettere i tuoi sistemi esistenti al tuo cluster Kafka Event Streams. Utilizzando l'API, puoi integrare Event Streams con qualsiasi sistema che supporta le API RESTful.

L'API del produttore REST è disponibile solo come parte dei piani Standard ed Enterprise Event Streams.

L'API del produttore REST è un'interfaccia REST scalabile per la produzione di messaggi in Event Streams su un endpoint HTTP sicuro. Invia i dati evento a Event Streams, utilizza la tecnologia Kafka per gestire i feed di dati e sfrutta le funzionalità di Event Streams per gestire i dati.

Utilizza l'API per connettere i sistemi esistenti a Event Streams. Crea le richieste di produzione dai tuoi sistemi in Event Streams, specificando anche la chiave del messaggio, le intestazioni e gli argomenti che vuoi scrivere nel messaggio.

Accesso all'API del produttore REST

Devi richiamare i dettagli dell'URL e delle credenziali necessari per la connessione all'API da un oggetto di credenziali del servizio o da una chiave del servizio per l'istanza del servizio. Per ulteriori informazioni sulla creazione di questi oggetti, vedi Connessione a Event Streams.

L'URL per l'endpoint dell'API viene fornito nella proprietà kafka_http_url .

Autenticazione

Il meccanismo di autenticazione supportato consiste nell'utilizzare un token di connessione. Per ottenere il tuo token utilizzando la CLI IBM Cloud, accedi prima a IBM Cloud ed esegui quindi il seguente comando:

ibmcloud iam oauth-tokens

Collocare questo token nell'intestazione di autorizzazione della richiesta HTTP nel modulo Bearer<token>. Sono supportati sia la chiave API che i token JWT.

Produzione di messaggi utilizzando l'API del produttore REST

Utilizza l'endpoint v2 dell'API del produttore per inviare messaggi di tipo text, binary, JSON o avro agli argomenti. Con l'endpoint v2 è possibile utilizzare il registro di schemi Event Streams specificando lo schema per il tipo di dati avro.

Il seguente codice mostra un esempio di invio di un messaggio di tipo text utilizzando curl:

curl -v -X POST \
-H "Authorization: Bearer $token" -H "Content-Type: application/json" -H "Accept: application/json" \
-d '{
  "headers": [
    {
      "name": "colour",
      "value": "YmxhY2s="
    }
  ],
  "key": {
    "type": "text",
    "data": "Test Key"
  },
  "value": {
    "type": "text",
    "data": "Test Value"
  }
}' \
"$kafka_http_url/v2/topics/$topic_name/records"

Per ulteriori informazioni sull'API, vedi Event Streams REST Producer API reference.

Produzione di messaggi conformi ad uno schema

Con l'endpoint v2 dell'API del produttore REST è possibile produrre un messaggio in modo che la chiave e il valore del messaggio siano conformi a uno schema. È possibile specificare schemi differenti per la chiave e il valore. Il serializer supportato è confluent e il tipo di dati supportato è avro. Gli schemi vengono creati e archiviati nel registro dello schema Event Streams. Per ulteriori informazioni, vedi Event Streams schema registry.

Sono ammesse le seguenti strategie di denominazione dello schema:

  • Strategia di denominazione degli argomenti: il nome dell'argomento viene utilizzato per derivare l'ID risorsa utente dello schema. L'ID ha il formato "\ <topicName> -key" per la chiave e "\ <topicName> -value" per il valore, dove topicName è il nome dell'argomento.

  • Strategia di denominazione record: il nome del record nello schema viene utilizzato per derivare l'ID risorsa utente dello schema. L'ID assume il formato "\ < composite-recordName> -key" per la chiave e "< composite-recordName> -value" per valore. Se viene specificato il campo dello spazio dei nomi dello schema, il composito -recordName assume il valore di "\ < namespace>. \ <recordName>", altrimenti assume il valore di "\ <recordName>".

  • Strategia di denominazione TopicRecord: sia il nome dell'argomento che il nome del record vengono utilizzati per derivare l'ID risorsa utente dello schema. L'ID assume il formato "\ <topicName> - \ <recordName> -key" per la chiave e "\ <topicName> - \ < composite -recordName> -value" per il valore, dove topicName è il nome dell'argomento. Se viene specificato il campo dello spazio dei nomi dello schema, il composito -recordName assume il valore di "\ < namespace>. \ <recordName>", altrimenti assume il valore di "\ <recordName>".

Il seguente codice mostra un esempio di invio di un messaggio conforme a un schema che viene specificato nel campo schema utilizzando curl:

curl -v -X POST \
-H "Authorization: Bearer $token" -H "Content-Type: application/json" -H "Accept: application/json" \
-d '{
  "value": {
    "type": "avro",
    "schema": "{\"namespace\": \"com.eventstreams.samples\",\"type\": \"record\",\"name\": \"recordValueName\",\"fields\": [{\"name\": \"valueName\", \"type\": \"string\"}]}",
    "schema_name_strategy": "record",
    "data": "{\"valueName\": \"sampleValueName\"}"
  }
}' \
"$kafka_http_url/v2/topics/$topic_name/records?serializer=confluent"

Migrazione dall'endpoint esistente all'endpoint v2 dell'API del produttore REST

Sono stati apportati diversi miglioramenti all'endpoint v2 per un migliore utilizzo e allineamento con gli standard API. Per sfruttare al massimo questi miglioramenti, apportare modifiche alle applicazioni esistenti.

Le seguenti considerazioni possono aiutare a pianificare la migrazione:

  1. Accesso all'API del produttore REST:

    Puoi accedere all'endpoint v2 allo stesso modo dell'URL esistente, ottenendo il valore della proprietà kafka_http_url per l'istanza del servizio. Il percorso da utilizzare è /v2/topics/<topic_name>/records.

    Example URL: https://service-instance-adsf1234asdf1234asdf1234-0000.us-south.containers.appdomain.cloud/v2/topics/topic_name/records

  2. Autenticazione:

    Il meccanismo di autenticazione supportato è un token di connessione. Per migliorare la sicurezza, l'autenticazione di base utilizzando le chiavi API non viene più accettata.

    Example Header:  -H "Authorization: Bearer $token"

  3. Intestazioni:

    Impostare le intestazioni Content-Type e Accept su application/json.

    Example Headers:  -H "Content-Type: application/json" -H "Accept: application/json"

  4. Payload:

    Fornire il payload per l'endpoint v2 in formato JSON. La chiave del messaggio, le intestazioni e i dati possono essere definiti nel payload. Puoi specificare le intestazioni sotto forma di un elenco, con valori codificati base64. Tuttavia, la chiave del messaggio e le intestazioni sono facoltative.

    Example payload:
{
  "headers": [
  {
   "name": "colour",
   "value": "YmxhY2s="
  },
  "key": {
   "type": "text",
   "data": "Test Key"
  },
  "value": {
   "type": "text",
   "data": "Test Value"
  }
 }

    È necessario specificare uno dei seguenti tipi di dati supportati per il tipo di campo sotto l'oggetto chiave e valore:

    a. Testo: i dati forniti vengono convalidati come formato testo semplice costituito da una sequenza lineare di caratteri.

    b. Binario: i dati forniti vengono convalidati come formato binario base64-encoded.

    c. JSON: i dati forniti vengono convalidati come formato JSON.

    d. Avro: i dati vengono convalidati come formato datiApache Avro.

  5. Risposta di errore:

    La risposta di errore contiene proprietà trace, error message, error code, more_info e target.

    Example error response:
{
 "trace": "a222e93c-e5f9-435d-b275-5d4919ea87ed",
 "error": {
  "code": "invalid_type",
  "message": "'type' field in 'value' object is required ...",
  "more_info": "https://cloud.ibm.com/apidocs/event-streams/restproducer_v2",
  "target": {
   "type": "field",
   "name": "type"
  }
 }
}

Limitazioni

Quando si utilizza l'API del produttore REST, esiste una limitazione sulla dimensione massima del messaggio passato come payload della richiesta. La dimensione massima del payload è limitata a 64 K.

Riferimento API

Per i dettagli completi dell'API dell'endpoint v2, vedi Event Streams REST Producer v2 API reference.

Per i dettagli completi dell'API dell'endpoint esistente, vedi Event Streams REST Producer API reference.