REST-Producer-API verwenden

Event Streams stellt eine REST-API bereit, die Sie beim Verbinden Ihrer vorhandenen Systeme mit Ihrem Event Streams-Kafka-Cluster unterstützt. Mithilfe der API können Sie Event Streams in jedes System integrieren, das REST-konforme APIs unterstützt.

Die REST-Producer-API ist nur als Teil der Pläne Event Streams Standard und Enterprise verfügbar.

Die REST-Producer-API ist eine skalierbare REST-Schnittstelle für die Erstellung von Nachrichten an Event Streams über einen sicheren HTTP-Endpunkt. Senden Sie Ereignisdaten an Event Streams, verwenden Sie die Kafka-Technologie, um Datenfeeds zu verarbeiten, und nutzen Sie die Funktionen von Event Streams, um Ihre Daten zu verwalten.

Verwenden Sie die API, um vorhandene Systeme mit Event Streams zu verbinden. Erstellen Sie Erstellungsanforderungen aus Ihren Systemen in Event Streams, einschließlich der Angabe des Nachrichtenschlüssels, der Header und der Topics, an die Nachrichten geschrieben werden sollen.

Auf REST-Producer-API zugreifen

Sie müssen die URL und die Berechtigungsnachweisdetails, die für die Verbindung mit der API erforderlich sind, von einem Serviceberechtigungsnachweisobjekt oder Serviceschlüssel für die Serviceinstanz abrufen. Weitere Informationen zum Erstellen dieser Objekte finden Sie unter Verbindung zu Event Streams herstellen.

Die URL für den Endpunkt der API wird in der Eigenschaft kafka_http_url angegeben.

Authentifizierung

Das unterstützte Authentifizierungsverfahren ist die Verwendung eines Trägertokens. Wenn Sie Ihr Token über die IBM Cloud-Befehlszeilenschnittstelle abrufen möchten, melden Sie sich zuerst bei IBM Cloud an und führen Sie dann den folgenden Befehl aus:

ibmcloud iam oauth-tokens

Fügen Sie dieses Token in den Berechtigungsheader der HTTP-Anforderung im Format Bearer<token> ein. Es werden sowohl API-Schlüssel als auch JWT-Token unterstützt.

Nachrichten mit der REST-Producer-API erzeugen

Verwenden Sie den Endpunkt v2 der Producer-API, um Nachrichten des Typs text, binary, JSON oder avro an Themen zu senden. Mit dem Endpunkt v2 können Sie die Schemaregistry von Event Streams verwenden, indem Sie das Schema für den Avro-Datentyp angeben.

Der folgende Code zeigt ein Beispiel für das Senden einer Nachricht des Typs text mithilfe von '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"

Weitere Informationen über die API finden Sie unter Event Streams REST Producer API reference.

Nachrichten erzeugen, die einem Schema entsprechen

Mit dem Endpunkt v2 der REST-Producer-API können Sie eine Nachricht so erstellen, dass Nachrichtenschlüssel und -wert einem Schema entsprechen. Sie können verschiedene Schemas für den Schlüssel und Wert angeben. Die unterstützte Serialisierungsmethode ist confluent und der unterstützte Datentyp ist avro. Die Schemas werden in der Event Streams-Schemaregistry erstellt und gespeichert. Weitere Informationen finden Sie unter Event Streams-Schemaregistry.

Die folgenden Strategien zur Schemabenennung sind zulässig:

  • Themenbenennungsstrategie: Der Name des Themas wird verwendet, um die Schemaartefakt-ID abzuleiten. Die ID hat das Format "<topicName>-key" für den Schlüssel und "<topicName>-value" für den Wert, wobei topicName der Name des Themas ist.

  • Datensatzbenennungsstrategie: Der Name des Datensatzes im Schema wird verwendet, um die Schemaartefakt-ID abzuleiten. Die ID hat das Format "<composite-recordName>-key" für den Schlüssel und "<composite-recordName>-value" für den Wert. Wenn das Feld für den Schemanamensbereich angegeben ist, nimmt der zusammengesetzterecordName den Wert "< Namensbereich>. <recordName>" an, andernfalls den Wert "\ <recordName>".

  • Benennungsstrategie TopicRecord: Sowohl der Name des Themas als auch der Name des Datensatzes werden verwendet, um die Schemaartefakt-ID abzuleiten. Die ID hat das Format "<topicName>-<recordName>-key" für den Schlüssel und "<topicName>-<composite-recordName>-value" für den Wert, wobei 'topicName' der Name des Themas ist. Wenn das Feld für den Schemanamensbereich angegeben ist, nimmt der zusammengesetzterecordName den Wert "< Namensbereich>. <recordName>" an, andernfalls den Wert "\ <recordName>".

Der folgende Code zeigt ein Beispiel für das Senden einer Nachricht, die einem Schema entspricht, das im Feld schema mit 'curl' angegeben ist:

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"

Migration aus einem vorhandenen Endpunkt auf den Endpunkt v2 der REST-Producer-API

Es wurden mehrere Verbesserungen am Endpunkt v2 vorgenommen, um die Verwendung und Ausrichtung an den API-Standards zu verbessern. Um diese Verbesserungen optimal zu nutzen, nehmen Sie Änderungen an Ihren vorhandenen Anwendungen vor.

Die folgenden Hinweise können Ihnen bei der Planung der Migration helfen:

  1. Zugriff auf die REST-Producer-API:

    Sie können auf den Endpunkt v2 genauso wie auf die vorhandene URL zugreifen, indem Sie den Wert der Eigenschaft kafka_http_url für die Serviceinstanz abrufen. Der zu verwendende Pfad ist /v2/topics/<topic_name>/records.

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

  2. Authentifizierung:

    Das unterstützte Authentifizierungsverfahren ist ein Trägertoken. Zur Erhöhung der Sicherheit wird die Basisauthentifizierung mit API-Schlüsseln nicht mehr akzeptiert.

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

  3. Header:

    Setzen Sie den Inhaltstyp und die Accept-Header auf application/json.

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

  4. Nutzdaten:

    Geben Sie die Nutzdaten für den Endpunkt v2 im JSON-Format an. Der Nachrichtenschlüssel, die Header und Daten können in den Nutzdaten definiert werden. Sie können die Header in Form einer Liste mit Werten angeben, die mit base64 codiert sind. Der Nachrichtenschlüssel und die Header sind jedoch optional.

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

    Sie müssen einen der folgenden unterstützten Datentypen für den Feldtyp unter dem Schlüssel- und Wertobjekt angeben:

    a. Text: Die bereitgestellten Daten werden als einfaches Textformat validiert, das aus einer linearen Folge von Zeichen besteht.

    b. Binär: Die bereitgestellten Daten werden im base64-encoded Binärformat validiert.

    c. JSON: Die bereitgestellten Daten werden im Format JSON validiert.

    d. Avro: Die Daten werden im Apache Avro-Datenformatvalidiert.

  5. Fehlerantwort:

    Die Fehlerantwort enthält die Eigenschaften trace, error message, error code, more_info und 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"
  }
 }
}

Einschränkungen

Wenn Sie die REST-Producer-API verwenden, gilt eine Begrenzung für die maximale Größe der Nachricht, die als Anforderungsnutzdaten übergeben wird. Die maximale Größe der Nutzdaten ist auf 64 K begrenzt.

API-Referenz

Vollständige Details zur Endpunkt-API von v2 finden Sie unter Event Streams REST Producer v2 API reference.

Ausführliche Informationen zur vorhandenen Endpunkt-API finden Sie unter Event Streams REST-Producer-API-Referenz.