Do Postman ou OpenAPI para um receptor HTTP no SAP CPI

A maioria das APIs REST que você conecta a partir do SAP CPI chega com um arquivo OpenAPI ou Swagger, uma coleção do Postman ou os dois. Tudo de que o adaptador receptor HTTP precisa está neles: o servidor, o caminho, os parâmetros, os headers e o formato do corpo. O trabalho é levar cada parte para o campo certo sem perder um caractere.

Este artigo mapeia uma operação OpenAPI e uma requisição do Postman para o receptor HTTP, passo a passo, e lista os detalhes que mais costumam quebrar a primeira chamada.

Do que o receptor HTTP precisa

• Address: a URL completa da operação. Ela pode conter expressões Simple, como ${property.orderId} para um parâmetro de caminho.
• Query: a query string sem o ?, por exemplo notify=true.
• Method: GET, POST, PUT, PATCH ou DELETE.
• Authentication: nenhuma, Basic, Client Certificate, OAuth2 Client Credentials e outras, usando credenciais armazenadas no tenant, nunca digitadas no canal.
• Request Headers: os nomes dos headers da mensagem enviados à API, separados por |.
• O corpo: o corpo da mensagem do jeito que ele chega ao adaptador, geralmente montado em um Content Modifier ou em um mapeamento.

Lendo uma operação OpenAPI ou Swagger

Veja esta operação OpenAPI 3, que cria uma remessa para um 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: junte a URL do servidor e o caminho. No Swagger 2.0, o servidor vem dividido em schemes, host e basePath.
2. Parâmetros de caminho como {orderId}: substitua cada um por uma expressão, por exemplo ${property.orderId}.
3. Parâmetros de consulta (in: query): leve-os para o campo Query.
4. Parâmetros de header (in: header): defina-os como headers da mensagem em um Content Modifier e liste os nomes em Request Headers.
5. Corpo da requisição: monte o JSON em um Content Modifier, seguindo o schema de requestBody.
6. Esquemas de segurança: crie a credencial correspondente no tenant e selecione-a em Authentication.

O resultado: um Content Modifier e o canal

Para esta operação, o Content Modifier antes do adaptador e o canal receptor HTTP ficam assim:

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

O Content Modifier define o header Content-Type como application/json, o header X-Request-Id e o corpo JSON, com os valores vindos de exchange properties definidas antes no fluxo. Request Headers lista exatamente os dois headers que a API deve receber, então todos os outros headers ficam no tenant.

A partir de uma requisição do Postman

Uma requisição do Postman traz as mesmas informações em outros lugares:

• A URL muitas vezes começa com uma variável do Postman, como {{baseUrl}}. No SAP CPI, a mesma sintaxe {{…}} indica um parâmetro externalizado, definido na implantação: o lugar natural para a URL base, que muda entre teste e produção.
• Variáveis de caminho (:orderId) e parâmetros de consulta vão para os campos Address e Query, como acima.
• A aba Headers vira headers no Content Modifier, mais os nomes deles em Request Headers.
• Um corpo JSON raw vira o corpo do Content Modifier, com cada valor de teste substituído por uma expressão.
• A aba Authorization mostra qual autenticação configurar. Não copie um token do Postman para o iFlow; armazene as credenciais no tenant.

Detalhes que quebram a primeira chamada

• Request Headers com * envia todos os headers da mensagem para a API, inclusive os internos. Liste só os headers que a API espera.
• Um header Content-Type ausente ou errado: muitas APIs rejeitam um corpo JSON sem application/json.
• Valores na URL precisam ser seguros para URL: um ID com espaços ou barras precisa ser codificado antes de entrar no endereço.
• Respostas de erro: com Throw Exception on Failure desligado, o fluxo continua e ${header.CamelHttpResponseCode} guarda o código de status, para que um Router trate os erros.
• Na maioria das APIs, os nomes de campo do corpo JSON diferenciam maiúsculas de minúsculas; copie-os do schema, não de memória.

Vai chamar um serviço OData? Veja o artigo sobre o receptor OData. Para as expressões usadas no endereço e no corpo, veja Expressões Camel Simple no SAP CPI.

Como o Kitegra ajuda

A extensão de navegador Kitegra trabalha com a especificação da API por você. Forneça um arquivo OpenAPI ou Swagger, em JSON ou YAML, ou uma coleção do Postman, e no designer do SAP Integration Suite ela sugere as URLs, os caminhos, os parâmetros de consulta, os headers de requisição e os corpos JSON de exemplo dessa especificação.

A especificação fica no seu navegador: a Kitegra nunca armazena especificações de API. A extensão nunca salva, implanta nem edita o conteúdo de um iFlow, e o seu tenant só muda quando você clica em uma de quatro ações nomeadas, que podem ser desativadas.

Para chamar do mesmo jeito o endpoint HTTPS do seu próprio iFlow, veja como testar um iFlow HTTPS com uma service key.

Sem uma conta Kitegra, ela funciona em 5 iFlows por módulo. O plano Free cobre 50, o Starter 100 e o Pro 300. Nos planos de equipe, cada membro tem o Pro, com 300 iFlows por módulo no Startup Team e sem limite no Growth Team e no Scale Team. Enquanto o Kitegra é lançado, todas as ferramentas ficam liberadas para todos que entrarem, inclusive no plano Free. Compare os planos.

Experimente no seu próximo iFlow

Veja o que o Kitegra faz no designer do SAP Integration Suite, ou confira-o ao lado das outras extensões do Chrome da Kitegra.

Perguntas frequentes