De Postman u OpenAPI a un receptor HTTP en SAP CPI

La mayoría de las API REST que conectas desde SAP CPI llegan con un archivo OpenAPI o Swagger, una colección de Postman o ambos. Ahí está todo lo que necesita el adaptador receptor HTTP: el servidor, la ruta, los parámetros, los headers y la forma del cuerpo. El trabajo consiste en llevar cada pieza al campo correcto sin perder un carácter.

Este artículo asigna una operación OpenAPI y una solicitud de Postman al receptor HTTP, paso a paso, y enumera los detalles que más a menudo hacen fallar la primera llamada.

Qué necesita el receptor HTTP

• Address: la URL completa de la operación. Puede contener expresiones Simple, como ${property.orderId} para un parámetro de ruta.
• Query: la cadena de consulta sin el ?, por ejemplo notify=true.
• Method: GET, POST, PUT, PATCH o DELETE.
• Authentication: ninguna, Basic, Client Certificate, OAuth2 Client Credentials y otras, con credenciales guardadas en el tenant, nunca escritas en el canal.
• Request Headers: los nombres de los headers del mensaje que se envían a la API, separados por |.
• El cuerpo: el cuerpo del mensaje tal como llega al adaptador, normalmente armado en un Content Modifier o en un mapeo.

Cómo leer una operación OpenAPI o Swagger

Toma esta operación de OpenAPI 3, que crea un envío para un pedido:

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: une la URL del servidor y la ruta. En Swagger 2.0, el servidor está dividido en schemes, host y basePath.
2. Parámetros de ruta como {orderId}: reemplaza cada uno por una expresión, por ejemplo ${property.orderId}.
3. Parámetros de consulta (in: query): pásalos al campo Query.
4. Parámetros de header (in: header): defínelos como headers del mensaje en un Content Modifier y lista sus nombres en Request Headers.
5. Cuerpo de la solicitud: arma el JSON en un Content Modifier siguiendo el esquema de requestBody.
6. Esquemas de seguridad: crea la credencial correspondiente en el tenant y selecciónala en Authentication.

El resultado: un Content Modifier y el canal

Para esta operación, el Content Modifier previo al adaptador y el canal receptor HTTP quedan así:

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

El Content Modifier define el header Content-Type como application/json, el header X-Request-Id y el cuerpo JSON, con valores tomados de exchange properties definidas antes en el flujo. Request Headers lista exactamente los dos headers que debe recibir la API, así que todos los demás headers se quedan en el tenant.

Desde una solicitud de Postman

Una solicitud de Postman contiene la misma información en otros lugares:

• La URL suele empezar con una variable de Postman como {{baseUrl}}. En SAP CPI, la misma sintaxis {{…}} indica un parámetro externalizado, que se define al desplegar: el lugar natural para la URL base, que cambia entre pruebas y producción.
• Las variables de ruta (:orderId) y los parámetros de consulta van a los campos Address y Query, como antes.
• La pestaña Headers se convierte en headers del Content Modifier más sus nombres en Request Headers.
• Un cuerpo JSON raw se convierte en el cuerpo del Content Modifier, con cada valor de prueba reemplazado por una expresión.
• La pestaña Authorization te indica qué autenticación configurar. No copies un token de Postman al iFlow; guarda las credenciales en el tenant.

Detalles que hacen fallar la primera llamada

• Request Headers con * envía todos los headers del mensaje a la API, incluidos los internos. Lista solo los headers que espera la API.
• Un header Content-Type ausente o incorrecto: muchas API rechazan un cuerpo JSON sin application/json.
• Los valores de la URL deben ser seguros para URL: un ID con espacios o barras necesita codificarse antes de entrar en la dirección.
• Respuestas de error: con Throw Exception on Failure desactivado, el flujo continúa y ${header.CamelHttpResponseCode} contiene el código de estado, así que un Router puede manejar los errores.
• En la mayoría de las API, los nombres de campo del cuerpo JSON distinguen mayúsculas de minúsculas; cópialos del esquema, no de memoria.

¿Llamas a un servicio OData? Consulta el artículo sobre el receptor OData. Para las expresiones de la dirección y del cuerpo, consulta Expresiones Camel Simple en SAP CPI.

Cómo ayuda Kitegra

La extensión de navegador Kitegra se encarga de la especificación de la API por ti. Dale un archivo OpenAPI o Swagger, en JSON o YAML, o una colección de Postman, y en el diseñador de SAP Integration Suite te sugiere las URLs, rutas, parámetros de consulta, headers de solicitud y cuerpos JSON de ejemplo de esa especificación.

La especificación se queda en tu navegador: Kitegra nunca guarda especificaciones de API. La extensión nunca guarda, despliega ni edita el contenido de un iFlow, y tu tenant solo cambia cuando haces clic en una de cuatro acciones con nombre, que se pueden desactivar.

Para llamar del mismo modo al endpoint HTTPS de tu propio iFlow, consulta cómo probar un iFlow HTTPS con una service key.

Sin una cuenta de Kitegra funciona en 5 iFlows por módulo. El plan Free cubre 50, Starter 100 y Pro 300. En los planes de equipo, cada miembro tiene Pro, con 300 iFlows por módulo en Startup Team y sin límite en Growth Team y Scale Team. Mientras Kitegra se lanza, todas las herramientas están abiertas para cualquiera que haya iniciado sesión, también en el plan Free. Compara los planes.

Pruébalo en tu próximo iFlow

Descubre lo que hace Kitegra en el diseñador de SAP Integration Suite, o míralo junto a las demás extensiones de Chrome de Kitegra.

Preguntas frecuentes