Política de FlowCallout

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

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

Num fluxo partilhado, cria uma sequência de passos que pode reutilizar no momento da execução a partir de vários locais. Estes passos são implementados como políticas, tal como num proxy de API. A política FlowCallout dá-lhe uma forma de invocar o fluxo partilhado a partir de proxies de API e outros fluxos partilhados. Funciona como uma chamada de função numa linguagem de programação tradicional.

• Por exemplo, imagine que criou um fluxo partilhado com funcionalidades de segurança, como a validação da chave da API, a validação do token OAuth e a proteção de expressões regulares. Este fluxo partilhado representa a sua convenção para verificar os pedidos recebidos. Com as políticas FlowCallout, pode invocar esse fluxo partilhado a partir de vários proxies de API.
• Pode chamar um fluxo partilhado a partir de outro implementando uma política FlowCallout a partir de um fluxo partilhado.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Nota: para mais informações sobre fluxos partilhados, consulte o artigo Fluxos partilhados reutilizáveis. Também pode chamar um fluxo partilhado a partir de código de proxy de API externo para aplicar o pré-processamento de pedidos ou o pós-processamento de respostas para todos os proxies de API implementados num ambiente. Para mais informações, consulte o artigo Anexar um fluxo partilhado através de um ponto de ligação do fluxo.

Amostras

Valide a chave da API no fluxo partilhado

Neste exemplo, é usado um fluxo partilhado para realizar tarefas comuns relacionadas com a segurança. Aqui, o fluxo partilhado valida uma chave da API. Os proxies de API e outros fluxos partilhados podem usar a política FlowCallout para fazer chamadas para este fluxo partilhado.

A definição do fluxo partilhado seguinte inclui uma política Verify-API-Key que é executada quando o fluxo partilhado é chamado a partir de uma política FlowCallout num 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 partilhado anterior obtém o valor da chave e valida-o.

<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 num proxy de API, chama o fluxo partilhado anterior para validar a chave da API. O pacote de fluxo partilhado verify-apikey-shared (não apresentado aqui) configura o fluxo partilhado da mesma forma 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>

Transmita parâmetros para um fluxo partilhado

Este exemplo ilustra como transmitir parâmetros de uma política FlowCallout para um fluxo partilhado. Aqui, uma política FlowCallout chama um fluxo partilhado concebido para executar funções de processamento de strings comuns. O fluxo partilhado inclui JavaScript que concatena a respetiva entrada, converte a respetiva entrada em minúsculas ou ambas. A política FlowCallout define parâmetros que especificam a entrada de string, a saída e o que fazer com a entrada.

1. A política String-Handler FlowCallout chama o fluxo partilhado, transmitindo parâmetros que especificam a variável para armazenar o resultado do fluxo partilhado, que operação do fluxo partilhado usar e que entrada usar (aqui, um literal de string, mas também pode ser uma variável de fluxo). Os elementos Parameter especificam os nomes e os valores das variáveis a criar no tempo de execução. O fluxo partilhado pode obter estas variáveis para utilização no respetivo 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 seguinte fluxo partilhado default inclui uma política de JavaScript que é executada quando o fluxo partilhado é chamado a partir de uma política FlowCallout.SharedStringFunctions

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

3. No fluxo partilhado, a seguinte SharedStringFunctionspolítica de JavaScript especifica o SharedStringFunctions.jsficheiro JavaScript com o código a executar.

   <?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 de JavaScript SharedStringFunctions. Este script obtém valores de variáveis criadas a partir de elementos da política FlowCallout Parameter.

   // 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 flui de volta da política de JavaScript para o fluxo partilhado e, em seguida, para a política FlowCallout no proxy de API de origem.

Referência do elemento

Seguem-se os elementos e os atributos que pode configurar nesta 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 <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 partilhado a chamar. O valor deste elemento deve ser igual ao valor do atributo name do elemento <SharedFlowBundle> de destino.

<SharedFlowBundle/>

No exemplo mais simples, atribui o nome do fluxo partilhado que está a ser chamado como um valor para este elemento. Ou seja, o valor deste elemento tem de ser igual ao valor do atributo name do fluxo partilhado.

<SharedFlowBundle>Shared-Flow-Name</SharedFlowBundle>

Predefinição	N/A
Presença	Obrigatória
Tipo	N/A

Atributos

Nenhum.

Elemento <Parameter>

Especifica um parâmetro e um valor (ou uma origem de valor) a transmitir como uma variável para o fluxo partilhado chamado por esta política.

Ao usar um parâmetro, pode especificar um valor (ou uma variável que contém um valor) que deve ser transmitido ao fluxo partilhado chamado pela política. Isto é conceptualmente semelhante a especificar um parâmetro numa chamada de função. Tal como acontece com um parâmetro de função, o valor de um parâmetro FlowCallout pode variar com base no contexto da chamada do fluxo partilhado.

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

Sintaxe

Pode usar este elemento com qualquer uma das seguintes formas de sintaxe. Tenha em atenção que, quando usa um valor literal, o formato do valor que especifica 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

Esta política String-Handler FlowCallout transmite parâmetros que especificam onde armazenar o resultado do fluxo partilhado e que entrada usar. Os elementos Parameter especificam os nomes e os valores das variáveis a criar no tempo de execução. O fluxo partilhado pode obter estas variáveis para utilização no respetivo 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>

Predefinição	N/A
Presença	Obrigatória
Tipo	N/A

Atributos

Atributo	Descrição	Predefinição	Presença	Tipo
name	O nome da variável de tempo de execução a criar com este parâmetro.	Nenhum	Obrigatória	String
ref	A variável que contém o valor a usar no tempo de execução. Omita este atributo se estiver a especificar um valor literal a usar.	Nenhum	Opcional	String
value	O valor a usar na variável de tempo de execução criada com este parâmetro. Omita este atributo se estiver a especificar o nome de uma variável que deve ser a origem do valor.	Nenhum	Opcional	String

Elemento <Parameters>

Especifica o conjunto de elementos <Parameter> a transmitir como variáveis no fluxo partilhado chamado por esta política.

Sintaxe

<Parameters>
  <Parameter name="parameter-name" value='parameter-value' />
</Parameters>

Predefinição	N/A
Presença	Opcional
Tipo	N/A

Atributos

Nenhum.

Esquemas

Exemplo: consulte os exemplos do nosso repositório do GitHub para ver os esquemas mais recentes.

Variáveis de fluxo

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

Variável	Descrição
apigee.edge.sharedflow.name	Âmbito: durante a execução do fluxo partilhado Tipo: string Autorização: leitura O valor do atributo de nome do fluxo partilhado.
apigee.edge.flowhook.name	Âmbito: durante a execução do fluxo partilhado anexado ao gancho do fluxo. Tipo: String Autorização: Leitura O nome do gancho do fluxo.

Referência de erro

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

Tópicos relacionados

• Criar fluxos partilhados: Fluxos partilhados reutilizáveis
• Executar fluxos partilhados em vários proxies: Anexar um fluxo partilhado através de um gancho de fluxo