从 Postman 或 OpenAPI 到 SAP CPI HTTP 接收方

你从 SAP CPI 连接的大多数 REST API 都附带 OpenAPI 或 Swagger 文件、Postman 集合，或两者都有。HTTP 接收方适配器需要的一切都在其中：服务器、路径、参数、header 和请求体结构。你要做的是把每一部分放进正确的字段，一个字符都不丢。

本文一步步把 OpenAPI 操作和 Postman 请求映射到 HTTP 接收方，并列出最常导致第一次调用失败的细节。

HTTP 接收方需要什么

• Address：操作的完整 URL。可以包含 Simple 表达式，例如用 ${property.orderId} 作为路径参数。
• Query：不带 ? 的查询字符串，例如 notify=true。
• Method：GET、POST、PUT、PATCH 或 DELETE。
• Authentication：无、Basic、Client Certificate、OAuth2 Client Credentials 等，凭据保存在 tenant 中，绝不写在通道里。
• Request Headers：要发送给 API 的消息 header 名称，以 | 分隔。
• 请求体：消息到达适配器时的消息体，通常在 Content Modifier 或映射中构建。

如何解读 OpenAPI 或 Swagger 操作

以下面这个 OpenAPI 3 操作为例，它为订单创建一个发货记录：

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：把服务器 URL 和路径拼接起来。在 Swagger 2.0 中，服务器被拆分为 schemes、host 和 basePath。
2. 像 {orderId} 这样的路径参数：把每一个替换为表达式，例如 ${property.orderId}。
3. 查询参数（in: query）：放进 Query 字段。
4. header 参数（in: header）：在 Content Modifier 中设置为消息 header，并在 Request Headers 中列出它们的名称。
5. 请求体：按照 requestBody 的 schema 在 Content Modifier 中构建 JSON。
6. 安全方案：在 tenant 中创建相应的凭据，并在 Authentication 中选择它。

结果：一个 Content Modifier 加上通道

对于这个操作，适配器之前的 Content Modifier 和 HTTP 接收方通道如下：

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

Content Modifier 把 header Content-Type 设为 application/json，设置 header X-Request-Id 和 JSON 请求体，其中的值取自流程中先前设置的 exchange property。Request Headers 恰好列出 API 需要接收的两个 header，因此其他所有 header 都留在 tenant 中。

从 Postman 请求出发

Postman 请求包含同样的信息，只是位置不同：

• URL 通常以 {{baseUrl}} 这样的 Postman 变量开头。在 SAP CPI 中，同样的 {{…}} 语法表示外部化参数，在部署时设置：这正是放置基础 URL 的合适位置，因为它在测试和生产之间会变化。
• 路径变量（:orderId）和查询参数和前面一样，分别放进 Address 和 Query 字段。
• Headers 选项卡对应 Content Modifier 中的 header，再加上它们在 Request Headers 中的名称。
• raw JSON 请求体对应 Content Modifier 的消息体，并把每个测试值替换为表达式。
• Authorization 选项卡告诉你要配置哪种认证方式。不要把 Postman 中的令牌复制到 iFlow；请把凭据保存在 tenant 中。

导致第一次调用失败的细节

• 在 Request Headers 中写 * 会把所有消息 header（包括内部 header）都发送给 API。请只列出 API 期望的 header。
• Content-Type header 缺失或错误：许多 API 会拒绝不带 application/json 的 JSON 请求体。
• URL 中的值必须是 URL 安全的：含空格或斜杠的 ID 在放进地址之前需要编码。
• 错误响应：关闭 Throw Exception on Failure 后，流程会继续执行，${header.CamelHttpResponseCode} 中保存着状态码，因此可以用 Router 处理错误。
• 在大多数 API 中，JSON 请求体的字段名区分大小写；请从 schema 中复制，而不要凭记忆输入。

要调用的是 OData 服务？请参阅 OData 接收方文章。关于地址和请求体中使用的表达式，请参阅 SAP CPI 中的 Camel Simple 表达式。

Kitegra 如何帮你

浏览器扩展 Kitegra 会替你处理 API 规范。向它提供 JSON 或 YAML 格式的 OpenAPI 或 Swagger 文件，或者 Postman 集合，它就会在 SAP Integration Suite 设计器中提示该规范里的 URL、路径、查询参数、请求 header 和 JSON 请求体示例。

规范只保留在你的浏览器中：Kitegra 从不保存 API 规范。它从不保存、部署或编辑 iFlow 的内容；只有在你点击四个指定操作之一时，tenant 才会发生变化，而且这些操作可以关闭。

想用同样的方式调用你自己 iFlow 的 HTTPS 端点？请参阅用服务密钥测试 HTTPS iFlow。

没有 Kitegra 账户时，每个模块可用于 5 个 iFlow。Free 套餐涵盖 50 个，Starter 100 个，Pro 300 个。在团队套餐中，每位成员都享有 Pro：Startup Team 每个模块 300 个 iFlow，Growth Team 和 Scale Team 不限。Kitegra 上线期间，所有工具向所有已登录用户开放，Free 套餐也不例外。比较各套餐。

在下一个 iFlow 中试试

了解 Kitegra 在 SAP Integration Suite 设计器中能做什么，或在 Kitegra 的其他 Chrome 扩展旁查看它。

常见问题