Substituição dinâmica de variáveis

A substituição dinâmica de variáveis permite que as configurações de serviço façam referência e resolvam valores provenientes de várias fontes de dados em tempo de execução, utilizando uma sintaxe consistente de marcadores de posição.

Em vez de definir valores diretamente na configuração, você pode obter valores dinamicamente das seguintes fontes:
  • Cargas úteis de solicitação (JSON)
  • Cargas úteis de solicitação (XML)
  • Cabeçalhos da solicitação
  • Parâmetros de consulta
  • Propriedades do OMS
  • JVM propriedades do sistema
Esse recurso ajuda você a criar integrações mais flexíveis, reutilizáveis e orientadas por configuração, ao mesmo tempo em que reduz a necessidade de código personalizado.
Atenção: A substituição dinâmica de variáveis é um recurso da plataforma projetado para uso mais amplo nos componentes do Service Definition Framework (SDF). Na versão do 10.0.2607.0, o suporte está disponível apenas na configuração do componente da API REST.

Benefícios

A substituição dinâmica de variáveis ajuda você a:

  • Criar configurações de serviço reutilizáveis
  • Evite valores fixos
  • Passar dados operacionais em tempo de execução para serviços posteriores
  • Reutilizar integrações em diferentes ambientes e cenários
  • Reduzir o desenvolvimento de extensões personalizadas

Suporte em 10.0.2607.0

Na versão 10.0.2607.0, a substituição dinâmica de variáveis pode ser configurada nos seguintes campos do componente da API REST:

  • URL de terminal
  • Cabeçalhos da solicitação
  • Parâmetros de consulta

Os futuros componentes do SDF poderão oferecer a mesma funcionalidade à medida que a disponibilidade for aumentando.

Expressões suportadas

São suportadas as seguintes expressões de espaço reservado:

Tabela 1. Sintaxe de expressão suportada por fonte
Origem Exemplo de sintaxe
Propriedade da OMS ${yfs.some.property}
Propriedade de sistema JVM ${sys:user.timezone}
Cabeçalho da solicitação ${header:X-Tenant-ID}
Parâmetro de consulta ${query:customerId}
Carga útil JSON ${json:$.order.customerId}
carga útil de XML ${xml://Order/@OrderNo}

Configurar um endpoint dinâmico URL

Na configuração da API REST, insira as expressões diretamente no campo REST_URL.

Exemplo

REST_URL :

https://api.example.com/customers/${json:$.order.customerId}/orders

JSON recebido:

{
  "order": {
    "customerId": "CUST1001"
  }
}

Resolução URL :

https://api.example.com/customers/CUST1001/orders

Configurar cabeçalhos dinâmicos de solicitação

Na seção “Cabeçalhos personalizados”, você pode usar expressões como todo o valor de um cabeçalho ou parte dele.

Exemplo 1: Propagação de cabeçalhos

Tabela 2. Exemplo de propagação de cabeçalho
Nome do Cabeçalho Valor do cabeçalho
Authorization Bearer ${header:X-Auth-Token}

Cabeçalho da mensagem recebida:

X-Auth-Token: abc123xyz

Cabeçalho enviado:

Authorization: Bearer abc123xyz

Exemplo 2: Construção do valor do cabeçalho

Tabela 3. Exemplo de construção do valor do cabeçalho
Nome do Cabeçalho Valor do cabeçalho
Referência de Pedido X ORD-${json:$.order.orderNo}

JSON recebido:

{
  "order": {
    "orderNo": "10001"
  }
}

Cabeçalho enviado:

X-Order-Reference: ORD-10001

Isso demonstra que as substituições podem ser incorporadas em sequências de caracteres maiores.

Configurar parâmetros dinâmicos de consulta

Exemplo

Tabela 4. Exemplo de parâmetro de consulta dinâmico
Parâmetro de consulta Valor
região ${query:region}
customerId ${json:$.order.customerId}

Solicitação recebida:

?region=us-east

JSON recebido:

{
  "order": {
    "customerId": "CUST1001"
  }
}

Solicitação enviada:

?region=us-east&customerId=CUST1001

Utilizar o OMS e as propriedades do sistema

Os valores podem ser obtidos a partir das propriedades do OMS ou das propriedades do sistem JVM.

REST_URL usando uma propriedade OMS:

${yfs.api.baseurl}/orders

Configuração do cabeçalho

Tabela 5. Nome e valor do cabeçalho
Nome do Cabeçalho Valor do cabeçalho
Fuso horário do servidor X ${sys:user.timezone}

Se o ` JVM ` for iniciado com -Duser.timezone=America/New_York, o cabeçalho será traduzido como:

X-Server-Timezone: America/New_York

Combinar várias fontes

Expressões provenientes de diferentes fontes podem ser combinadas em um único campo.

REST_URL :

https://api.example.com/customers/${json:$.customerId}/orders?region=${query:region}

Cabeçalho

Tabela 6. Exemplo de cabeçalho com várias fontes
Nome do Cabeçalho Valor do cabeçalho
ID de correlação X ${sys:tenant.id}-${json:$.order.orderNo}

Resultado

URL:    https://api.example.com/customers/CUST001/orders?region=us-east
Header: X-Correlation-ID: acme-10001

Melhores práticas

  • Utilize a substituição em tempo de execução para evitar valores específicos do cliente codificados de forma rígida.
  • Verifique se os valores referenciados estarão disponíveis no momento da execução.
  • Reutilize as configurações dos serviços, externalizando os valores de implantação em propriedades, quando for o caso.
  • Use nomes significativos para cabeçalhos e parâmetros a fim de melhorar a facilidade de manutenção.