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 seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo	Descrição	Predefinição	Presença
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual	falso	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional
async	Este atributo foi descontinuado.	falso	Descontinuado

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Predefinição	N/A Se omitir este elemento, é 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 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
Presença	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>
<!-- A 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
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
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
Presença	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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Use API Monitoring to investigate fault codes and diagnose issues faster.

Fault code	HTTP status	Cause	Fix
flow.SharedFlowNotFound	500	Either the shared flow does not exist, or the shared flow exists but is not deployed.

Deployment errors

N/A

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