Integrações outbound

Declarando uma integração

spec:
  integrations:
    - id: pricing
      kind: http                       # http | grpc
      baseUrl: "${config:Pricing:Url}"
      auth: { scheme: oauth2-client-credentials, ref: corp-idp }
      resilience:
        timeout: { perAttempt: 2s, total: 8s }
        retry:   { attempts: 3, backoff: { initial: 200ms, jitter: true }, on: [502, 503, 504] }
        circuitBreaker: { failureRatio: 0.5, samplingDuration: 30s, minimumThroughput: 20, breakDuration: 15s }
        fallback: { expr: "{ 'price': 0, 'degraded': true }" }

kind: http ou kind: grpc decide qual protocolo. auth reusa os mesmos esquemas de autenticação das rotas de entrada, mas aplicados à direção contrária — veja IOutboundAuthProvider e Autenticação e autorização.

Chamando: http.call e grpc.call

- type: http.call
  id: price
  integration: pricing
  method: POST
  path: /quote
  body: "{ 'items': vars.order.items }"
  headers: { X-Correlation-Id: "input.headers.'x-correlation-id'" }
  resilience:                  # sobrescreve o default da integração para esta chamada específica
    timeout: { perAttempt: 1s }

grpc.call tem a mesma forma e o mesmo contrato de resiliência, para uma integração declarada com kind: grpc.

Resiliência

Toda integração pode declarar, sob resilience, o comportamento padrão para chamadas contra ela — e um step http.call/grpc.call individual pode sobrescrever qualquer parte disso para aquela chamada específica:

Bloco	O que controla
timeout.perAttempt / .total	Tempo máximo de uma tentativa individual, e da operação inteira (incluindo retries)
retry.attempts / .backoff / .on	Quantas tentativas, o backoff entre elas (initial, max, jitter), e em quais status HTTP retry se aplica
circuitBreaker.failureRatio / .samplingDuration / .minimumThroughput / .breakDuration	Quando o circuito abre (proporção de falhas numa janela de amostragem, com um mínimo de chamadas para o cálculo ser significativo) e por quanto tempo fica aberto
fallback.expr (ou .pipeline)	O que fazer quando a chamada falha mesmo depois de esgotar retry/circuit breaker — uma expressão JSONata que produz um valor substituto, ou um sub-pipeline inteiro
rateLimiter.permitLimit / .window / .queueLimit	Limite de chamadas concorrentes/por janela de tempo, com fila opcional para o excedente

Uma resposta de erro do servidor (status 5xx, ou uma falha de rede) que sobrevive a todo o pipeline de resiliência (retry, depois circuit breaker) executa o fallback declarado, se houver — em vez de simplesmente falhar o step. Um status 4xx, por outro lado, é sempre tratado como erro de negócio: a chamada foi rejeitada, não a integração está indisponível — nunca é repetida e nunca aciona fallback, a distinção é deliberada.

Para onde ir daqui

• Implantação
• Um exemplo real com integração HTTP outbound de ponta a ponta: samples/06-full-stack no repositório do Pipevine.