Política FlowCallout

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Use a política FlowCallout para chamar um fluxo compartilhado de um proxy de API ou 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 de API e 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 de vários proxies de API.
• É possível chamar um fluxo compartilhado de outro por meio da implementação de uma política FlowCallout de dentro de um fluxo compartilhado.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Observação: para saber mais sobre fluxos compartilhados, consulte Fluxos compartilhados reutilizáveis. Também é possível chamar um fluxo compartilhado usando um código externo de proxy de API para aplicar o pré-processamento de solicitações ou o pós-processamento de respostas de todos os proxies de API implantados em um ambiente. Para mais informações, consulte Como anexar um fluxo compartilhado usando um hook de fluxo.

Amostras

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 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 maneira que um pacote de proxy de API 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 FlowCallout para um fluxo compartilhado. Aqui, uma política 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 e a saída de strings e também o que fazer com a entrada.

1. A política String-Handler FlowCallout chama o fluxo compartilhado, transmitindo parâmetros que especificam 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 pode ser também uma variável de fluxo). Os elementos Parameter especificam os nomes e os 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 elementosParameter da política 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 JavaScript para o fluxo compartilhado e, em seguida, para a política FlowCallout no proxy de 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	Presence
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. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual	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.	true	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.
Presence	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 este 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
Presence	Obrigatório
Tipo	N/A

Atributos

Nenhuma.

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. Como acontece com um parâmetro de função, o valor de um parâmetro FlowCallout pode variar com base no contexto da chamada de fluxo compartilhado.

Os parâmetros 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 String-Handler FlowCallout 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
Presence	Obrigatório
Tipo	N/A

Atributos

Atributo	Descrição	Padrão	Presence	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
value	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
Presence	Opcional
Tipo	N/A

Atributos

Nenhuma.

Esquemas

Amostra: veja nossas amostras de repositório do GitHub para os esquemas mais recentes.

Variáveis de fluxo

As variáveis de fluxo permitem o comportamento dinâmico de políticas e fluxos no ambiente de execução, com base em cabeçalhos HTTP, conteúdo de mensagens ou contexto de fluxo. Para mais informações sobre as 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 retornadas e as variáveis com falha definidas pela Apigee quando essa 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.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Corrigir" para informações detalhadas sobre a solução de problemas.

Use o Monitoramento de APIs para investigar códigos de falha e diagnosticar problemas mais rapidamente.

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

Erros na implantação

N/D

Temas relacionados

• Como criar fluxos compartilhados: Fluxos compartilhados reutilizáveis
• Como executar fluxos compartilhados em vários proxies: Como anexar um fluxo compartilhado usando um hook de fluxo