Accès à l'API REST Producer

Pour la connexion à l'API, vous devez extraire l'URL et les données d'identification d'un objet de données d'identification de service ou d'une clé de service de l'instance de service. Pour plus d'informations sur la création de ces objets, voir Connexion à Event Streams.

L'URL du nœud final de l'API est fournie dans la propriété kafka_http_url.

Authentification

Le mécanisme d'authentification pris en charge consiste à utiliser un jeton bearer. Pour obtenir votre jeton à l'aide de l'interface de ligne de commande IBM Cloud, connectez-vous d'abord à IBM Cloud, puis exécutez la commande suivante:

ibmcloud iam oauth-tokens

Placez ce jeton dans l'en-tête d'autorisation de la requête HTTP au format Bearer<token>. La clé d'API et les jetons JWT sont pris en charge.

Génération de messages à l'aide de l'API de fournisseur REST

Utilisez le noeud final v2 de l'API du fournisseur pour envoyer des messages de type text, binary, JSON ou avro aux rubriques. Avec le noeud final v2, vous pouvez utiliser le registre de schéma Event Streams en spécifiant le schéma pour le type de données avro.

Le code suivant illustre un exemple d'envoi d'un message de type text à l'aide de 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"

Pour plus d'informations sur l'API, voir Event Streams REST Producer API reference.

Génération de messages conformes à un schéma

Avec le noeud final v2 de l'API du fournisseur REST, vous pouvez produire un message de sorte que la clé et la valeur du message soient conformes à un schéma. Vous pouvez spécifier différents schémas pour la clé et la valeur. Le sérialiseur pris en charge est confluent et le type de données pris en charge est avro. Les schémas sont créés et stockés dans le registre de schémas Event Streams. Pour plus d'informations, voir Registre de schémaEvent Streams.

Les stratégies de dénomination de schéma suivantes sont autorisées :

• Stratégie de dénomination des rubriques : le nom de la rubrique est utilisé pour dériver l'ID d'artefact de schéma. L'ID prend la forme "<topicName>-key" pour la clé et "<topicName>-value" pour la valeur, où topicName est le nom de la rubrique.

• Stratégie de dénomination des enregistrements : le nom de l'enregistrement dans le schéma est utilisé pour dériver l'ID d'artefact de schéma. L'ID prend la forme "<composite-recordName>-key" pour la clé et "<composite-recordName>-value" pour la valeur. Si la zone d'espace de nom de schéma est spécifiée, le composite-recordName prend la valeur "\ < namespace>. \ <recordName>" ; sinon, il prend la valeur "\ <recordName>".

• Stratégie de dénomination TopicRecord: le nom de la rubrique et le nom de l'enregistrement sont utilisés pour dériver l'ID d'artefact de schéma. L'ID prend la forme "<topicName>-<recordName>-key" pour la clé et "<topicName>-<composite-recordName>-value" pour la valeur, où topicName est le nom de la rubrique. Si la zone d'espace de nom de schéma est spécifiée, le composite-recordName prend la valeur "\ < namespace>. \ <recordName>" ; sinon, il prend la valeur "\ <recordName>".

Le code suivant illustre un exemple d'envoi d'un message conforme à un schéma spécifié dans la zone schema à l'aide de 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"

Migration à partir du noeud final existant vers le noeud final v2 de l'API REST Producer

Plusieurs améliorations ont été apportées au noeud final v2 pour une meilleure utilisation et un meilleur alignement avec les normes d'API. Pour tirer le meilleur parti de ces améliorations, apportez des modifications à vos applications existantes.

Les considérations suivantes peuvent vous aider à planifier la migration :

1. Accès à l'API REST Producer :

   Vous pouvez accéder au noeud final v2 de la même manière que l'URL existante, c'est-à-dire en obtenant la valeur de la propriété kafka_http_url pour l'instance de service. Le chemin à utiliser est /v2/topics/<topic_name>/records.

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

2. Authentification :

   Le mécanisme d'authentification pris en charge est un jeton bearer. Pour améliorer la sécurité, l'authentification de base à l'aide de clés d'API n'est plus acceptée.

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

3. En-têtes:

   Définissez les en-têtes Content-Type et Accept sur application/json.

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

4. Contenu :

   Indiquez le contenu du noeud final v2 au format JSON. La clé de message, les en-têtes et les données peuvent être définis dans le contenu. Vous pouvez spécifier les en-têtes sous la forme d'une liste, avec des valeurs codées par base64. Toutefois, la clé de message et les en-têtes sont facultatifs.

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

   Vous devez spécifier l'un des types de données pris en charge suivants pour le type de zone sous l'objet clé et valeur :

   a. Texte: les données fournies sont validées sous la forme d'un format de texte en clair composé d'une séquence linéaire de caractères.

   b. Binaire: les données fournies sont validées au format binaire base64-encoded.

   c. JSON: les données fournies sont validées au format JSON.

   d. Avro: les données sont validées en tant que Format de données Apache Avro.

5. Réponse d'erreur :

   La réponse d'erreur contient les propriétés trace, error message, error code, more_info et 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"
     }
    }
   }
   

Limitations

Lorsque vous utilisez l'API du fournisseur REST, une limitation s'applique à la taille maximale du message transmis en tant que charge de la demande. La taille maximale du contenu est limitée à 64 K.

Référence d'interface de programme d'application

Pour plus de détails sur l'API de noeud final v2, voir Event Streams REST Producer v2 API reference.

Pour plus de détails sur l'API de noeud final existante, voir Event Streams REST Producer API reference.