Usando a API de REST producer

O Event Streams fornece uma API de REST para ajudar a conectar seus sistemas existentes ao seu cluster Kafka do Event Streams. Usando a API, é possível integrar o Event Streams com qualquer sistema que suporte APIs RESTful.

A API do produtor REST está disponível como parte dos planos Standard e Enterprise do Event Streams.

A API de REST producer é uma interface REST escalável para produzir mensagens para o Event Streams por meio de um terminal HTTP seguro. Envie dados do evento para Event Streams, use a tecnologia Kafka para manipular feeds de dados e aproveite os recursos do Event Streams para gerenciar seus dados.

Use a API para conectar sistemas existentes ao Event Streams. Crie solicitações de produção de seus sistemas para o Event Streams, incluindo a especificação da chave da mensagem, dos cabeçalhos e dos tópicos para os quais você deseja gravar mensagens.

Acessando a API do produtor REST

Deve-se recuperar os detalhes da URL e da credencial necessários para se conectar à API de um objeto de credenciais de serviço ou de uma chave de serviço da instância de serviço. Para obter mais informações sobre a criação desses objetos, consulte Conectando-se ao Event Streams.

A URL para o terminal da API é fornecida na propriedade kafka_http_url.

Autenticação

O mecanismo de autenticação suportado é usar um token de acesso. Para obter seu token usando a CLI do IBM Cloud, primeiro efetue login no IBM Cloud e, em seguida, execute o comando a seguir:

ibmcloud iam oauth-tokens

Coloque este token no cabeçalho de autorização da solicitação de HTTP no formulário Bearer<token>. A chave de API ou os tokens JWT são suportados.

Produzindo mensagens usando a API do produtor REST

Use o terminal v2 da API do produtor para enviar mensagens do tipo text, binary, JSON ou avro para tópicos. Com o terminal v2, é possível usar o registro do esquema Event Streams especificando o esquema para o tipo de dados avro.

O código a seguir mostra um exemplo de envio de uma mensagem do tipo text usando 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 obter mais informações sobre a API, consulte Event Streams Referência da API do Produtor REST.

Produzindo mensagens que se adequam a um esquema

Com o terminal v2 da API do produtor REST, é possível produzir uma mensagem de forma que a chave e o valor da mensagem estejam em conformidade com um esquema. É possível especificar esquemas diferentes para a chave e o valor. O serializador suportado é confluent e o tipo de dados suportado é avro. Os esquemas são criados e armazenados no Event Streams Schema Registry. Para obter mais informações, consulte Event Streams Registro de esquema.

As estratégias de nomenclatura de esquema a seguir são permitidas:

  • Estratégia de nomenclatura de tópico: o nome do tópico é usado para derivar o ID do artefato de esquema. O ID assume o formato "<topicName>-key" para a chave e "<topicName>-value" para o valor, em que topicName é o nome do tópico.

  • Estratégia de nomenclatura de registro: o nome do registro no esquema é usado para derivar o ID do artefato de esquema. O ID assume o formato "<composite-recordName>-key" para a chave e "<composite-recordName>-value" para o valor. Se o campo de namespace do esquema for especificado, o composto-recordName usará o valor de "\ < namespace>. \ <recordName>", caso contrário, usará o valor de "\ <recordName>".

  • TopicRecord estratégia de nomenclatura: o nome do tópico e o nome do registro são usados para derivar o ID do artefato do esquema.. O ID assume o formato "<topicName>-<recordName>-key" para a chave e "<topicName>-<composite-recordName>-value" para o valor, em que topicName é o nome do tópico. Se o campo de namespace do esquema for especificado, o composto-recordName usará o valor de "\ < namespace>. \ <recordName>", caso contrário, usará o valor de "\ <recordName>".

O código a seguir mostra um exemplo de envio de uma mensagem que está em conformidade com um esquema especificado no campo schema usando 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"

Migrando do terminal existente para o terminal v2 da API do produtor REST

Foram feitas várias melhorias no terminal v2 para um melhor uso e alinhamento com os padrões de API. Para aproveitar ao máximo essas melhorias, faça mudanças nos aplicativos existentes.

As considerações a seguir podem ajudá-lo a planejar a migração:

  1. Acessando a API do produtor REST:

    É possível acessar o terminal v2 da mesma maneira que a URL existente, que é obter o valor da propriedade kafka_http_url para a instância de serviço. O caminho a ser usado é /v2/topics/<topic_name>/records.

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

  2. Autenticação:

    O mecanismo de autenticação suportado é um token de acesso. Para aprimorar a segurança, a autenticação básica usando chaves API não é mais aceita.

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

  3. Cabeçalhos:

    Configure o Content-Type e os cabeçalhos Accept para application/json.

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

  4. Carga útil:

    Forneça a carga útil para o terminal v2 em formato JSON. A chave de mensagem, os cabeçalhos e os dados podem ser definidos na carga útil. É possível especificar os cabeçalhos na forma de uma lista, com valores que são codificados em base64. No entanto, a chave de mensagem e os cabeçalhos são opcionais.

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

    Deve-se especificar um dos tipos de dados suportados a seguir para o tipo de campo sob o objeto de chave e valor:

    a. Texto: os dados fornecidos são validados como formato de texto simples que consiste em uma sequência linear de caracteres.

    b. Binário: os dados que são fornecidos são validados como formato binário base64-encoded.

    c. JSON: os dados que são fornecidos são validados como formato JSON.

    d. Avro: os dados são validados como formato de dados Apache Avro.

  5. Resposta de erro:

    A resposta de erro contém trace, error message, error code, more_info e target propriedades.

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

Limitações

Ao utilizar a API do produtor REST, uma limitação existe no tamanho máximo da mensagem que é passada como payload de solicitação. O tamanho máximo da carga útil é limitado a 64 K.

Referência da API

Para obter detalhes completos da API do terminal v2, consulte Event Streams REST Producer v2 API reference.

Para obter detalhes completos da API do terminal existente, consulte Event Streams Referência da API do Produtor REST.