Uso de la API REST de productor

Event Streams proporciona una API REST para ayudar a conectar los sistemas existentes al clúster Kafka de Event Streams. Mediante la API, puede integrar Event Streams con cualquier sistema que dé soporte a las API RESTful.

La API de productor REST solo está disponible como parte de los planes Estándar y Empresa de Event Streams.

La API REST de productor es una interfaz REST escalable para la producción de mensajes en Event Streams a través de un punto final HTTP seguro. Envíe datos de sucesos a Event Streams, utilice la tecnología Kafka para manejar canales de información de datos y aproveche las características de Event Streams para gestionar los datos.

Utilice la API para conectar los sistemas existentes a Event Streams. Cree solicitudes de producción desde sus sistemas a Event Streams, especificando la clave de mensaje, las cabeceras y los temas en los que desea escribir mensajes.

Acceso a la API de productor REST

Debe recuperar los detalles de URL y de credenciales necesarios para conectarse a la API desde un objeto de credenciales de servicio o una clave de servicio para la instancia de servicio. Para obtener más información sobre la creación de estos objetos, consulte Conexión a Event Streams.

El URL del punto final de la API se proporciona en la propiedad kafka_http_url.

Autenticación

El mecanismo de autenticación admitido es utilizar una señal portadora. Para obtener la señal utilizando la CLI de IBM Cloud, primero inicie sesión en IBM Cloud y, a continuación, ejecute el mandato siguiente:

ibmcloud iam oauth-tokens

Coloque esta señal en la cabecera de autorización de la solicitud HTTP en forma de Bearer<token>. Se admiten tanto señales de clave de API como señales JWT.

Producción de mensajes utilizando la API de productor REST

Utilice el punto final v2 de la API de productor para enviar mensajes de tipo text, binary, JSON o avro a los temas. Con el punto final v2 puede utilizar el registro de esquema Event Streams especificando el esquema para el tipo de datos avro.

El código siguiente muestra un ejemplo de envío de un mensaje de tipo text utilizando 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"

Para obtener más información sobre la API, consulte Referencia de la API del productor REST deEvent Streams.

Producción de mensajes que se ajustan a un esquema

Con el punto final v2 de la API de productor REST, puede generar un mensaje de forma que la clave y el valor del mensaje se ajusten a un esquema. Puede especificar distintos esquemas para la clave y el valor. El serializador soportado es confluent y el tipo de datos soportado es avro. Los esquemas se crean y almacenan en el registro de esquemas de Event Streams. Para obtener más información, consulte Registro de esquemas deEvent Streams.

Se permiten las siguientes estrategias de denominación de esquema:

Estrategia de denominación de tema: el nombre del tema se utiliza para derivar el ID de artefacto de esquema. El ID adopta el formato "<topicName>-key" para la clave y "<topicName>-value" para el valor, donde topicName es el nombre de tema.
Estrategia de denominación de registro: el nombre del registro en el esquema se utiliza para derivar el ID de artefacto de esquema. El ID adopta el formato "<composite-recordName>-key" para la clave y "<composite-recordName>-value" para el valor. Si se especifica el campo de espacio de nombres de esquema, el compuesto-recordName toma el valor de "\ < namespace>. \ <recordName>", de lo contrario, toma el valor de "\ <recordName>".
Estrategia de denominación TopicRecord: tanto el nombre del tema como el nombre del registro se utilizan para derivar el ID de artefacto de esquema. El ID toma el formato "<topicName>-<recordName>-key" para la clave y "<topicName>-<composite-recordName>-value" para el valor, donde topicName es el nombre de tema. Si se especifica el campo de espacio de nombres de esquema, el compuesto-recordName toma el valor de "\ < namespace>. \ <recordName>", de lo contrario, toma el valor de "\ <recordName>".

El código siguiente muestra un ejemplo de envío de un mensaje que se ajusta a un esquema que se especifica en el campo schema utilizando 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"

Migración del punto final existente al punto final de v2 de la API de productor REST

Se han realizado varias mejoras en el punto final v2 para un mejor uso y alineación con los estándares de la API. Para aprovechar al máximo estas mejoras, realice cambios en las aplicaciones existentes.

Las siguientes consideraciones pueden ayudarle a planificar la migración:

Acceso a la API de productor REST:

Puede acceder al punto final v2 de la misma forma que el URL existente, que es obteniendo el valor de la propiedad kafka_http_url para la instancia de servicio. La vía de acceso que se va a utilizar es /v2/topics/<topic_name>/records.
```
Example URL: https://service-instance-adsf1234asdf1234asdf1234-0000.us-south.containers.appdomain.cloud/v2/topics/topic_name/records
```
Autentificación:

El mecanismo de autenticación admitido es una señal portadora. Para mejorar la seguridad, la autenticación básica utilizando claves de API ya no se acepta.
```
Example Header:  -H "Authorization: Bearer $token"
```

Headers:

Establezca las cabeceras Content-Type y Accept en application/json.

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

Payload:

Proporcione la carga útil para el punto final v2 en formato JSON. La clave de mensaje, las cabeceras y los datos se pueden definir en la carga útil. Puede especificar las cabeceras en forma de una lista, con valores codificados en base64. Sin embargo, la clave de mensaje y las cabeceras son opcionales.
```
Example payload:
{
  "headers": [
  {
   "name": "colour",
   "value": "YmxhY2s="
  },
  "key": {
   "type": "text",
   "data": "Test Key"
  },
  "value": {
   "type": "text",
   "data": "Test Value"
  }
 }
```
Debe especificar uno de los siguientes tipos de datos admitidos para el tipo de campo bajo la clave y el objeto de valor:

a. Texto: los datos que se proporcionan se validan como formato de texto sin formato que consta de una secuencia lineal de caracteres.

b. Binario: los datos que se proporcionan se validan como formato binario base64-encoded.

c. JSON: los datos que se proporcionan se validan como formato JSON.

d. Avro: los datos se validan como Formato de datos Apache Avro.

Respuesta de error:

La respuesta de error contiene las propiedades trace, error message, error code, more_info y 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"
  }
 }
}

Limitaciones

Cuando se utiliza la API de productor REST, existe una limitación en el tamaño máximo del mensaje que se pasa como carga útil de solicitud. El tamaño máximo de la carga útil está limitado a 64 K.

Referencia de API

Para obtener todos los detalles de la API de punto final v2, consulte Referencia de API deEvent Streams REST Producer v2.

Para obtener todos los detalles de la API de punto final existente, consulte Event Streams Referencia de la API del productor REST.