De Postman ou OpenAPI à un récepteur HTTP dans SAP CPI

La plupart des API REST que vous connectez depuis SAP CPI arrivent avec un fichier OpenAPI ou Swagger, une collection Postman, ou les deux. Tout ce dont l'adaptateur récepteur HTTP a besoin s'y trouve : le serveur, le chemin, les paramètres, les headers et la structure du body. Le travail consiste à placer chaque élément dans le bon champ sans perdre un caractère.

Cet article transpose pas à pas une opération OpenAPI et une requête Postman vers le récepteur HTTP, et liste les détails qui font le plus souvent échouer le premier appel.

Ce dont le récepteur HTTP a besoin

• Address : l'URL complète de l'opération. Elle peut contenir des expressions Simple, comme ${property.orderId} pour un paramètre de chemin.
• Query : la chaîne de requête sans le ?, par exemple notify=true.
• Method : GET, POST, PUT, PATCH ou DELETE.
• Authentication : aucune, Basic, Client Certificate, OAuth2 Client Credentials et d'autres, avec des identifiants stockés dans le tenant, jamais saisis dans le canal.
• Request Headers : les noms des headers de message envoyés à l'API, séparés par |.
• Le body : le Message Body tel qu'il arrive à l'adaptateur, généralement construit dans un Content Modifier ou un mapping.

Lire une opération OpenAPI ou Swagger

Prenons cette opération OpenAPI 3, qui crée une expédition pour une commande :

openapi: 3.0.3
servers:
  - url: https://api.example.com/v1
paths:
  /orders/{orderId}/shipments:
    post:
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: string } }
        - { name: notify, in: query, schema: { type: boolean } }
        - { name: X-Request-Id, in: header, schema: { type: string } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                carrier: { type: string }
                trackingNumber: { type: string }

1. Address : assemblez l'URL du serveur et le chemin. En Swagger 2.0, le serveur est réparti entre schemes, host et basePath.
2. Paramètres de chemin comme {orderId} : remplacez chacun par une expression, par exemple ${property.orderId}.
3. Paramètres de requête (in: query) : déplacez-les dans le champ Query.
4. Paramètres de header (in: header) : définissez-les comme headers de message dans un Content Modifier et listez leurs noms dans Request Headers.
5. Body de la requête : construisez le JSON dans un Content Modifier, en suivant le schéma sous requestBody.
6. Schémas de sécurité : créez l'identifiant correspondant dans le tenant et sélectionnez-le sous Authentication.

Le résultat : un Content Modifier et le canal

Pour cette opération, le Content Modifier placé avant l'adaptateur et le canal récepteur HTTP se présentent ainsi :

Content Modifier
  Header   Content-Type   application/json
  Header   X-Request-Id   ${property.requestId}
  Body     {
             "carrier": "${property.carrier}",
             "trackingNumber": "${property.trackingNumber}"
           }

HTTP receiver
  Address           https://api.example.com/v1/orders/${property.orderId}/shipments
  Query             notify=true
  Method            POST
  Request Headers   Content-Type|X-Request-Id

Le Content Modifier définit le header Content-Type à application/json, le header X-Request-Id et le body JSON, avec des valeurs tirées d'exchange properties définies plus tôt dans le flux. Request Headers liste exactement les deux headers que l'API doit recevoir ; tous les autres restent dans le tenant.

À partir d'une requête Postman

Une requête Postman contient les mêmes informations, à d'autres endroits :

• L'URL commence souvent par une variable Postman comme {{baseUrl}}. Dans SAP CPI, la même syntaxe {{…}} désigne un paramètre externalisé, défini au déploiement : l'emplacement naturel pour l'URL de base, qui change entre test et production.
• Les variables de chemin (:orderId) et les paramètres de requête vont dans les champs Address et Query, comme ci-dessus.
• L'onglet Headers devient des headers de Content Modifier, plus leurs noms dans Request Headers.
• Un body JSON brut devient le body du Content Modifier, chaque valeur de test étant remplacée par une expression.
• L'onglet Authorization indique quelle authentification configurer. Ne copiez pas de jeton de Postman dans l'iFlow ; stockez les identifiants dans le tenant.

Les détails qui font échouer le premier appel

• Request Headers réglé sur * envoie chaque header de message à l'API, y compris les headers internes. Listez uniquement les headers attendus par l'API.
• Un header Content-Type absent ou erroné : beaucoup d'API rejettent un body JSON sans application/json.
• Les valeurs dans l'URL doivent être compatibles URL : un ID contenant des espaces ou des barres obliques doit être encodé avant d'entrer dans l'adresse.
• Réponses d'erreur : avec Throw Exception on Failure désactivé, le flux continue et ${header.CamelHttpResponseCode} contient le code de statut, ce qui permet à un Router de traiter les erreurs.
• Les noms de champs du body JSON sont sensibles à la casse pour la plupart des API ; copiez-les depuis le schéma, pas de mémoire.

Vous appelez plutôt un service OData ? Consultez l'article sur le récepteur OData. Pour les expressions utilisées dans l'adresse et le body, voir Expressions Camel Simple dans SAP CPI.

Ce qu'apporte Kitegra

L'extension de navigateur Kitegra exploite la spécification d'API pour vous. Fournissez-lui un fichier OpenAPI ou Swagger, en JSON ou YAML, ou une collection Postman, et dans le designer de SAP Integration Suite elle suggère les URL, chemins, paramètres de requête, headers de requête et bodies JSON d'exemple issus de cette spécification.

La spécification reste dans votre navigateur : Kitegra n'enregistre jamais les spécifications d'API. L'extension n'enregistre, ne déploie et ne modifie jamais le contenu d'un iFlow, et votre tenant ne change que lorsque vous cliquez sur l'une de quatre actions nommées, qui peuvent être désactivées.

Pour appeler de la même façon l'endpoint HTTPS de votre propre iFlow, voir tester un iFlow HTTPS avec une service key.

Sans compte Kitegra, elle fonctionne sur 5 iFlows par module. Le forfait Free en couvre 50, Starter 100 et Pro 300. Avec les forfaits d'équipe, chaque membre bénéficie de Pro, avec 300 iFlows par module sur Startup Team et sans limite sur Growth Team et Scale Team. Pendant le lancement d'Kitegra, tous les outils sont ouverts à toute personne connectée, y compris avec le forfait Free. Comparez les forfaits.

Essayez-le dans votre prochain iFlow

Découvrez ce que fait Kitegra dans le designer de SAP Integration Suite, ou voyez-le aux côtés des autres extensions Chrome de Kitegra.

Questions fréquentes