Política FlowCallout

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Use a política FlowCallout para chamar um fluxo compartilhado de um proxy de API ou de outro fluxo compartilhado.

Em um fluxo compartilhado, você cria uma sequência de etapas que podem ser reutilizadas no momento da execução de vários lugares. Essas etapas são implementadas como políticas, por exemplo, em um proxy de API. Com a política FlowCallout, é possível invocar o fluxo compartilhado dos proxies da API e de outros fluxos compartilhados. Ele funciona como uma chamada de função em uma linguagem de programação tradicional.

  • Por exemplo, imagine que você criou um fluxo compartilhado com recursos de segurança, como verificação de chaves de API, validação de token OAuth e proteção de expressão regular. Esse fluxo compartilhado representa sua convenção para verificar as solicitações de entrada. Com as políticas FlowCallout, é possível invocar esse fluxo compartilhado a partir de vários proxies de API.
  • Você pode chamar um fluxo compartilhado a partir de outro implementando uma política Flow callout dentro de um fluxo compartilhado.

Exemplos

Verificar a chave de API no fluxo compartilhado

Neste exemplo, um fluxo compartilhado é usado para executar tarefas comuns relacionadas à segurança. Aqui, o fluxo compartilhado valida uma chave de API. Os proxies da API e outros fluxos compartilhados podem usar a política FlowCallout para fazer chamadas para esse fluxo compartilhado.

A definição do fluxo compartilhado a seguir inclui uma política Verify-API-Key que é executada quando o fluxo compartilhado é chamado a partir de uma política FlowCallout em um proxy de API.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
    <Step>
        <Name>Verify-API-Key</Name>
    </Step>
</SharedFlow>

A política VerifyAPIKey no fluxo compartilhado anterior recupera o valor da chave e o verifica.

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

A seguinte política de FlowCallout, usada em um proxy de API, chama o fluxo compartilhado anterior para verificar a chave de API. O pacote de fluxo compartilhado verify-apikey-shared (não mostrado aqui) configura o fluxo compartilhado da mesma maneira que um pacote APIProxy configura um proxy.

<FlowCallout async="false" continueOnError="false" enabled="true" name="Auth-Flow-Callout">
    <DisplayName>Auth Flow Callout</DisplayName>
    <SharedFlowBundle>verify-apikey-shared</SharedFlowBundle>
</FlowCallout>

Transmitir parâmetros para um fluxo compartilhado

Neste exemplo, ilustramos como transmitir parâmetros de uma política de FlowCallout para um fluxo compartilhado. Aqui, uma política de FlowCallout chama um fluxo compartilhado projetado para executar funções comuns de manipulação de strings. O fluxo compartilhado inclui JavaScript que concatena a entrada, reduz a entrada, ou ambos. A política FlowCallout define parâmetros que especificam a entrada, a saída de string e o que fazer com a entrada.

  1. A política FlowCallout String-Handler chama o fluxo compartilhado, passando parâmetros especificando a variável para armazenar a saída do fluxo compartilhado, qual operação de fluxo compartilhado usar e qual entrada usar. Aqui, um literal de string, mas também pode ser uma variável de fluxo. Os elementos Parameter especificam os nomes e valores das variáveis para criar o ambiente de execução. O fluxo compartilhado pode recuperar essas variáveis para uso no próprio código.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
      <DisplayName>String Handler</DisplayName>
      <Parameters>
        <Parameter name="input">Gladys Kravitz</Parameter>
        <Parameter name="operations">concatenate tolowercase</Parameter>
        <Parameter name="outputVariable">string.handler.output</Parameter>
      </Parameters>
      <SharedFlowBundle>StringHandler</SharedFlowBundle>
    </FlowCallout>
    
  2. O fluxo compartilhado default a seguir inclui uma política JavaScript SharedStringFunctions que é executada quando o fluxo compartilhado é chamado a partir de uma política FlowCallout.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <SharedFlow name="default">
      <Step>
        <Name>SharedStringFunctions</Name>
      </Step>
    </SharedFlow>
  3. No fluxo compartilhado, a seguinte política JavaScript SharedStringFunctions especifica o arquivo JavaScript SharedStringFunctions.js com o código a ser executado.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="SharedStringFunctions">
      <DisplayName>SharedStringFunctions</DisplayName> <Properties/>
      <ResourceURL>jsc://SharedStringFunctions.js</ResourceURL>
    </Javascript>
  4. O seguinte JavaScript, SharedStringFunctions.js, é executado a partir da política JavaScript SharedStringFunctions. Esse script recupera valores de variáveis criadas a partir de elementos Parameter da política do FlowCallout.

    // Input value from the calling API proxy.
    var handledString = context.getVariable("input");
    // Variable to use for output from this script.
    var outputVariable = context.getVariable("outputVariable");
    // A space-separated list of things to do to the input string.
    // Convert to lower case to handle unintentional capitals in configuration.
    var operation = context.getVariable("operations").toLowerCase();
    
    // If "lowercase" was given as an operation, convert the input to lowercase.
    if (operation.includes("tolowercase")) {
        handledString = handledString.toLowerCase();
    }
    
    // If "concatenate" was given as an operation, concatenate the input.
    if (operation.includes("concatenate")) {
        handledString = handledString.replace(/\s+/g, '');
    }
    // Assign the resulting string to the output variable specified by
    // the calling API proxy.
    context.setVariable(outputVariable, handledString);
  5. A execução volta da política do JavaScript para o fluxo compartilhado e depois para a política FlowCallout no proxy da API de origem.

Referência de elemento

Veja a seguir elementos e atributos que podem ser configurados com esta política:

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <SharedFlowBundle>thereferencedsharedflowbundle</SharedFlowBundle>
</FlowCallout>

Atributos de <FlowCallout>

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Atributo Descrição Padrão Presença
name

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres.

Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

N/A Obrigatório
continueOnError

Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas.

Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar.

false Opcional
enabled

Defina como true para aplicar a política.

Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.

verdadeiro Opcional
async

Esse atributo está obsoleto.

false Descontinuado

Elemento <DisplayName>

Use em conjunto com o atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

<DisplayName>Policy Display Name</DisplayName>
Padrão

N/A

Se você omitir esse elemento, será usado o valor do atributo name da política.

Presença Opcional
Tipo String

Elemento <SharedFlowBundle>

Especifica o nome do fluxo compartilhado a ser chamado. O valor desse elemento precisa ser igual ao valor do atributo de nome do elemento SharedFlowBundle de destino.

<SharedFlowBundle/>

No exemplo mais simples, você atribui o nome do fluxo compartilhado chamado como um valor para esse elemento. Ou seja, o valor desse elemento precisa ser igual ao valor do atributo name do fluxo compartilhado.

<SharedFlowBundle>Shared-Flow-Name</SharedFlowBundle>
 
Padrão N/A
Presença

Obrigatório.

Tipo N/A

Atributos

Nenhum.

Elemento <Parameter>

Especifica um parâmetro e um valor (ou fonte de valor) para passar como uma variável no fluxo compartilhado chamado por essa política.

Ao usar um parâmetro, é possível especificar um valor, ou uma variável que contenha um valor, que precisa ser transmitido para o fluxo compartilhado chamado pela política. Esse conceito é conceitualmente semelhante à especificação de um parâmetro em uma chamada de função. Assim como em um parâmetro de função, o valor de um parâmetro FlowCallout pode variar de acordo com o contexto da chamada de fluxo compartilhada.

Os parâmetros do FlowCallout são visíveis apenas durante a execução do fluxo compartilhado.

Sintaxe

É possível usar esse elemento com qualquer um dos seguintes formulários de sintaxe. Observe que, quando você usa um valor literal, o formato do valor especificado depende do código que o consome.

<!- A literal value in an attribute. --/>
<Parameter name="parameter-name" value='parameter-value' />
<!- A reference to a variable in an attribute. --/>
<Parameter name="parameter-name" ref='source-variable-name' />
<!- A literal value in the element content. --/>
<Parameter name="parameter-name">parameter-value</Parameter>
<!- An reference to an attribute in the element content. --/>
<Parameter name="parameter-name">{source-variable-name}</Parameter>

Exemplo

Essa política de FlowCallout String-Handler transmite parâmetros que especificam onde armazenar a saída do fluxo compartilhado e qual entrada usar. Os elementos Parameter especificam os nomes e valores das variáveis para criar o ambiente de execução. O fluxo compartilhado pode recuperar essas variáveis para uso em seu próprio código.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
  <DisplayName>String Handler</DisplayName>
  <Parameters>
    <Parameter name="input">Gladys Kravitz</Parameter>
    <Parameter name="outputVariable">string.handler.output</Parameter>
  </Parameters>
  <SharedFlowBundle>StringHandler</SharedFlowBundle>
</FlowCallout>
Padrão N/A
Presença

Obrigatório.

Tipo N/A

Atributos

Atributo Descrição Padrão Presença Tipo
name O nome da variável de ambiente de execução para criar com este parâmetro. Nenhum. Obrigatório. String
ref

A variável que contém o valor a ser usado no ambiente de execução. Omita esse atributo se estiver especificando um valor literal a ser usado.

Nenhum. Opcional. String
valor O valor a ser usado na variável de ambiente de execução criada com esse parâmetro. Omita esse atributo se você estiver especificando o nome de uma variável que precisa ser a origem do valor. Nenhum. Opcional. String

Elemento <Parameters>

Especifica o conjunto de elementos <Parameter> a serem transmitidos como variáveis para o fluxo compartilhado chamado por essa política.

Sintaxe

<Parameters>
  <Parameter name="parameter-name" value='parameter-value' />
</Parameters>
Padrão N/A
Presença

Opcional.

Tipo N/A

Atributos

Nenhum.

Esquemas

Variáveis de fluxo

As variáveis de fluxo permitem o comportamento dinâmico das políticas e dos fluxos no ambiente de execução, com base em cabeçalhos HTTP, conteúdo da mensagem ou contexto do fluxo. Para mais informações sobre variáveis de fluxo, consulte Referência de variáveis.

Variável Descrição

apigee.edge.sharedflow.name

Escopo: durante a execução do fluxo compartilhado
Tipo: string
Permissão: leitura

O valor do atributo de nome do fluxo compartilhado.

apigee.edge.flowhook.name

Escopo: durante a execução do fluxo compartilhado anexado ao gancho de fluxo.
Tipo: string
Permissão: leitura

O nome do gancho de fluxo.

Referência de erros

Nesta seção, descrevemos os códigos de falha e as mensagens de erro retornados, além das variáveis de falha definidas pelo Edge quando esta política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Código de falha Status HTTP Causa Corrigir
flow.SharedFlowNotFound 500 O fluxo compartilhado não existe ou ele existe, mas não está implantado.

Erros na implantação

N/A

Temas relacionados