Von Postman oder OpenAPI zum HTTP Receiver in SAP CPI

Die meisten REST-APIs, die Sie aus SAP CPI anbinden, kommen mit einer OpenAPI- oder Swagger-Datei, einer Postman-Collection oder beidem. Darin steht alles, was der HTTP-Receiver-Adapter braucht: der Server, der Pfad, die Parameter, die Header und die Struktur des Body. Die Arbeit besteht darin, jedes Teil ins richtige Feld zu übertragen, ohne ein Zeichen zu verlieren.

Dieser Artikel bildet eine OpenAPI-Operation und einen Postman-Request Schritt für Schritt auf den HTTP Receiver ab und nennt die Details, an denen der erste Aufruf am häufigsten scheitert.

Was der HTTP Receiver braucht

• Address: die vollständige URL der Operation. Sie kann Simple Expressions enthalten, etwa ${property.orderId} für einen Pfadparameter.
• Query: der Query-String ohne das ?, zum Beispiel notify=true.
• Method: GET, POST, PUT, PATCH oder DELETE.
• Authentication: keine, Basic, Client Certificate, OAuth2 Client Credentials und weitere – mit Zugangsdaten, die im Tenant hinterlegt sind, nie direkt im Kanal eingetippt.
• Request Headers: die Namen der Message Header, die an die API gesendet werden, getrennt durch |.
• Der Body: der Message Body, so wie er beim Adapter ankommt, meist in einem Content Modifier oder einem Mapping aufgebaut.

Eine OpenAPI- oder Swagger-Operation lesen

Nehmen Sie diese OpenAPI-3-Operation, die eine Sendung zu einem Auftrag anlegt:

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: Verbinden Sie Server-URL und Pfad. In Swagger 2.0 ist der Server auf schemes, host und basePath aufgeteilt.
2. Pfadparameter wie {orderId}: Ersetzen Sie jeden durch einen Ausdruck, zum Beispiel ${property.orderId}.
3. Query-Parameter (in: query): Übertragen Sie sie in das Feld Query.
4. Header-Parameter (in: header): Setzen Sie sie in einem Content Modifier als Message Header und tragen Sie ihre Namen unter Request Headers ein.
5. Request-Body: Bauen Sie das JSON in einem Content Modifier auf, nach dem Schema unter requestBody.
6. Security Schemes: Legen Sie die passenden Zugangsdaten im Tenant an und wählen Sie sie unter Authentication aus.

Das Ergebnis: ein Content Modifier und der Kanal

Für diese Operation sehen der Content Modifier vor dem Adapter und der HTTP-Receiver-Kanal so aus:

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

Der Content Modifier setzt den Header Content-Type auf application/json, den Header X-Request-Id und den JSON-Body, mit Werten aus Exchange Properties, die weiter vorne im Flow gesetzt wurden. Request Headers listet genau die zwei Header, die die API erhalten soll, sodass alle anderen Header im Tenant bleiben.

Aus einem Postman-Request

Ein Postman-Request enthält dieselben Informationen an anderen Stellen:

• Die URL beginnt oft mit einer Postman-Variablen wie {{baseUrl}}. In SAP CPI bezeichnet dieselbe {{…}}-Syntax einen externalisierten Parameter, der beim Deployment gesetzt wird – der natürliche Ort für die Basis-URL, die sich zwischen Test und Produktion ändert.
• Pfadvariablen (:orderId) und Query-Parameter gehören wie oben in die Felder Address und Query.
• Die Registerkarte Headers wird zu Content-Modifier-Headern plus deren Namen unter Request Headers.
• Ein Raw-JSON-Body wird zum Content-Modifier-Body, wobei jeder Testwert durch einen Ausdruck ersetzt wird.
• Die Registerkarte Authorization zeigt, welche Authentifizierung Sie konfigurieren müssen. Kopieren Sie kein Token aus Postman in den iFlow; hinterlegen Sie Zugangsdaten im Tenant.

Details, an denen der erste Aufruf scheitert

• Request Headers auf * sendet jeden Message Header an die API, auch interne. Listen Sie nur die Header auf, die die API erwartet.
• Ein fehlender oder falscher Header Content-Type: Viele APIs lehnen einen JSON-Body ohne application/json ab.
• Werte in der URL müssen URL-sicher sein: Eine ID mit Leerzeichen oder Schrägstrichen muss kodiert werden, bevor sie in die Adresse kommt.
• Fehlerantworten: Ist Throw Exception on Failure ausgeschaltet, läuft der Flow weiter und ${header.CamelHttpResponseCode} enthält den Statuscode, sodass ein Router Fehler behandeln kann.
• Feldnamen im JSON-Body unterscheiden bei den meisten APIs Groß- und Kleinschreibung; übernehmen Sie sie aus dem Schema, nicht aus dem Gedächtnis.

Sie rufen stattdessen einen OData-Service auf? Lesen Sie den Artikel zum OData Receiver. Zu den Ausdrücken in Adresse und Body siehe Camel Simple Expressions in SAP CPI.

Wie der Kitegra hilft

Die Browser-Erweiterung Kitegra übernimmt die API-Spezifikation für Sie. Geben Sie ihr eine OpenAPI- oder Swagger-Datei in JSON oder YAML oder eine Postman-Collection, und im Designer der SAP Integration Suite schlägt sie URLs, Pfade, Query-Parameter, Request-Header und JSON-Beispiel-Bodies aus dieser Spezifikation vor.

Die Spezifikation bleibt in Ihrem Browser: Kitegra speichert nie API-Spezifikationen. Die Erweiterung speichert, deployt oder bearbeitet nie den Inhalt eines iFlows, und Ihr Tenant ändert sich nur, wenn Sie auf eine von vier benannten Aktionen klicken, die sich abschalten lassen.

Wie Sie den HTTPS-Endpunkt Ihres eigenen iFlows auf dieselbe Weise aufrufen, zeigt einen HTTPS-iFlow mit einem Service Key testen.

Ohne Kitegra-Konto funktioniert sie für 5 iFlows je Modul. Der Tarif Free umfasst 50, Starter 100 und Pro 300. In den Team-Tarifen erhält jedes Mitglied Pro, mit 300 iFlows je Modul in Startup Team und ohne Limit in Growth Team und Scale Team. Während des Starts von Kitegra sind alle Werkzeuge für alle Angemeldeten offen, auch im Tarif Free. Tarife vergleichen.

Probieren Sie ihn im nächsten iFlow aus

Lesen Sie, was der Kitegra im Designer der SAP Integration Suite leistet, oder sehen Sie ihn neben den anderen Chrome-Erweiterungen von Kitegra.

Häufige Fragen