Da Postman o OpenAPI a un receiver HTTP in SAP CPI

La maggior parte delle API REST che colleghi da SAP CPI arriva con un file OpenAPI o Swagger, una collection di Postman o entrambi. Tutto ciò che serve all'adapter receiver HTTP è lì: il server, il path, i parametri, gli header e la forma del body. Il lavoro consiste nel portare ogni pezzo nel campo giusto senza perdere un carattere.

Questo articolo mappa un'operazione OpenAPI e una richiesta Postman sul receiver HTTP, passo dopo passo, ed elenca i dettagli che più spesso fanno fallire la prima chiamata.

Cosa serve al receiver HTTP

• Address: l'URL completo dell'operazione. Può contenere espressioni Simple, come ${property.orderId} per un parametro di path.
• Query: la query string senza il ?, per esempio notify=true.
• Method: GET, POST, PUT, PATCH o DELETE.
• Authentication: nessuna, Basic, Client Certificate, OAuth2 Client Credentials e altre, con credenziali salvate nel tenant e mai digitate nel canale.
• Request Headers: i nomi degli header del messaggio inviati all'API, separati da |.
• Il body: il body del messaggio così come arriva all'adapter, di solito costruito in un Content Modifier o in un mapping.

Leggere un'operazione OpenAPI o Swagger

Prendi questa operazione OpenAPI 3, che crea una spedizione per un ordine:

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: unisci l'URL del server e il path. In Swagger 2.0 il server è diviso in schemes, host e basePath.
2. Parametri di path come {orderId}: sostituisci ciascuno con un'espressione, per esempio ${property.orderId}.
3. Parametri di query (in: query): spostali nel campo Query.
4. Parametri di header (in: header): impostali come header del messaggio in un Content Modifier ed elenca i loro nomi in Request Headers.
5. Body della richiesta: costruisci il JSON in un Content Modifier seguendo lo schema sotto requestBody.
6. Security scheme: crea la credenziale corrispondente nel tenant e selezionala in Authentication.

Il risultato: un Content Modifier e il canale

Per questa operazione, il Content Modifier prima dell'adapter e il canale receiver HTTP appaiono così:

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

Il Content Modifier imposta l'header Content-Type su application/json, l'header X-Request-Id e il body JSON, con i valori presi da exchange property impostate prima nel flusso. Request Headers elenca esattamente i due header che l'API deve ricevere, così tutti gli altri header restano nel tenant.

Da una richiesta Postman

Una richiesta Postman contiene le stesse informazioni in posti diversi:

• L'URL inizia spesso con una variabile Postman come {{baseUrl}}. In SAP CPI la stessa sintassi {{…}} indica un parametro esternalizzato, impostato al deploy: il posto naturale per l'URL di base, che cambia tra test e produzione.
• Le variabili di path (:orderId) e i parametri di query vanno nei campi Address e Query, come sopra.
• La scheda Headers diventa header del Content Modifier più i loro nomi in Request Headers.
• Un body JSON raw diventa il body del Content Modifier, con ogni valore di test sostituito da un'espressione.
• La scheda Authorization ti dice quale autenticazione configurare. Non copiare un token da Postman nell'iFlow; salva le credenziali nel tenant.

Dettagli che fanno fallire la prima chiamata

• Request Headers impostato su * invia all'API tutti gli header del messaggio, compresi quelli interni. Elenca solo gli header che l'API si aspetta.
• Un header Content-Type mancante o sbagliato: molte API rifiutano un body JSON senza application/json.
• I valori nell'URL devono essere sicuri per un URL: un ID con spazi o barre va codificato prima di entrare nell'indirizzo.
• Risposte di errore: con Throw Exception on Failure disattivato, il flusso prosegue e ${header.CamelHttpResponseCode} contiene il codice di stato, così un Router può gestire gli errori.
• Per la maggior parte delle API, i nomi dei campi nel body JSON distinguono tra maiuscole e minuscole; copiali dallo schema, non a memoria.

Devi chiamare un servizio OData? Vedi l'articolo sul receiver OData. Per le espressioni usate nell'indirizzo e nel body, vedi Espressioni Camel Simple in SAP CPI.

Come aiuta Kitegra

L'estensione del browser Kitegra si occupa della specifica API al posto tuo. Forniscile un file OpenAPI o Swagger, in JSON o YAML, o una collection di Postman, e nel designer di SAP Integration Suite ti suggerisce URL, path, parametri di query, header della richiesta e body JSON di esempio tratti da quella specifica.

La specifica resta nel tuo browser: Kitegra non salva mai le specifiche API. L'estensione non salva, non esegue il deploy e non modifica mai il contenuto di un iFlow, e il tuo tenant cambia solo quando fai clic su una di quattro azioni ben precise, che si possono disattivare.

Per chiamare allo stesso modo l'endpoint HTTPS del tuo iFlow, vedi testare un iFlow HTTPS con una service key.

Senza un account Kitegra funziona su 5 iFlow per modulo. Il piano Free ne copre 50, Starter 100 e Pro 300. Con i piani per team ogni membro ha Pro, con 300 iFlow per modulo su Startup Team e nessun limite su Growth Team e Scale Team. Durante il lancio di Kitegra, tutti gli strumenti sono aperti a chiunque abbia effettuato l'accesso, anche con il piano Free. Confronta i piani.

Provalo nel tuo prossimo iFlow

Scopri cosa fa Kitegra nel designer di SAP Integration Suite, oppure guardalo accanto alle altre estensioni Chrome di Kitegra.

Domande frequenti