Política JavaCallout

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

Veja a documentação do Apigee Edge.

O quê

Permite-lhe usar Java para implementar um comportamento personalizado que não está incluído de imediato nas políticas do Apigee. No seu código Java, pode aceder às propriedades das mensagens (cabeçalhos, parâmetros de consulta, conteúdo) e às variáveis de fluxo no fluxo do proxy. Se está a começar a usar esta política, consulte o artigo Como criar um texto de chamada Java.

As versões Java suportadas incluem: Oracle JDK 11 e OpenJDK 11

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: Importante: se estiver a desenvolver políticas JavaCallout, tem de saber que políticas de autorização estão em vigor na JVM do Apigee e como vão afetar o seu código. Consulte a referência de autorizações Java. Consulte também a secção Restrições.

Quando

Para ver diretrizes, consulte "Quando devo usar JavaCallout?" no artigo Como criar um texto destacado Java.

Acerca de

A política JavaCallout permite obter e definir variáveis de fluxo, executar lógica personalizada e realizar processamento de erros, extrair dados de pedidos ou respostas e muito mais. Esta política permite-lhe implementar um comportamento personalizado que não é abrangido por outras políticas padrão do Apigee.

Nota: a Apigee recomenda que considere usar a política JavaScript se tiver inclinação para usar JavaScript. Em alternativa, considere usar a política de indicação de serviços se precisar de fazer chamadas HTTP para serviços remotos. No entanto, se quiser escrever código Java personalizado, tem essa opção. Consulte também Quando devo usar um JavaCallout?

Pode criar um pacote da sua aplicação Java com os ficheiros JAR de pacotes de que precisa. Tenha em atenção que existem algumas restrições quanto ao que pode fazer com JavaCallout. Estas estão listadas abaixo em Restrições.

Amostras

Exemplo simples

Como criar um texto destacado Java

Recupere propriedades no seu código Java

O elemento <Property> da política permite-lhe especificar um par nome/valor que pode obter no tempo de execução no seu código Java. Para ver um exemplo funcional que usa propriedades, consulte o artigo Como usar propriedades em políticas de JavaCallout.

Use o atributo name do elemento <Property> para especificar o nome com o qual aceder à propriedade a partir do código Java. O valor do elemento <Property> (o valor entre as etiquetas de abertura e fecho) é o valor que o código Java vai receber. O valor tem de ser uma string. Não pode fazer referência a uma variável de fluxo para obter o valor.

• Configure a propriedade. Aqui, o valor da propriedade é o nome da variável response.status.code.

  <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
      <DisplayName>JavaCallout</DisplayName>
      <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
      <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
      <Properties>
          <Property name="source">response.status.code</Property>
      </Properties>
  </Javascript>

• No seu código Java, implemente o seguinte construtor na implementação da classe Execution da seguinte forma:
  

  public class MyJavaCallout implements Execution{
      public MyJavaCallout(Map<string, string> props){
          
              // Extract property values from map.
      }
      ...
  }

Defina variáveis de fluxo no seu código Java

Para uma descrição clara de como definir variáveis no contexto da mensagem (variáveis de fluxo) no seu código Java, consulte esta publicação da comunidade do Apigee.

---

Referência do elemento

A referência de elementos descreve os elementos e os atributos da política JavaCallout.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

Atributos <JavaCallout>

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

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 Sugestão: nos casos em que o seu código Java gera uma exceção, o fluxo do proxy do Apigee muda para o estado de falha, mesmo que o atributo continueOnError esteja definido como verdadeiro. Se não quiser que uma exceção lançada resulte num estado de falha no proxy, crie o código de chamada Java de forma que não lance erros. Em alternativa, intercete exceções e defina uma variável de contexto para capturar as informações de exceção. Para mais informações, consulte esta publicação da comunidade do Apigee.	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 <ClassName>

Especifica o nome da classe Java que é executada quando a política JavaCallout é executada. A classe tem de ser incluída no ficheiro JAR especificado por <ResourceURL>. Veja também como criar um texto de chamada Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>

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

Elemento <Properties>

Adiciona novas propriedades às quais pode aceder a partir do código Java no tempo de execução.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

Predefinição:	Nenhum
Presença:	Opcional
Tipo:	String

Elemento <Property>

Especifica uma propriedade à qual pode aceder a partir do código Java no tempo de execução. Tem de especificar um valor de string literal para cada propriedade. Não pode fazer referência a variáveis de fluxo neste elemento. Para ver um exemplo funcional que usa propriedades, consulte o artigo Como usar propriedades numa política JavaCallout.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

Predefinição:	Nenhum
Presença:	Opcional
Tipo:	String

Atributos

Atributo	Descrição	Predefinição	Presença
nome	Especifica o nome da propriedade.	N/A	Obrigatório.

Elemento <ResourceURL>

Este elemento especifica o ficheiro JAR Java que é executado quando a política JavaCallout é executada.

Pode armazenar este ficheiro no âmbito do proxy de API (em /apiproxy/resources/java no pacote do proxy de API ou na secção Scripts do painel Navigator do editor do proxy de API) ou nos âmbitos da organização ou do ambiente para reutilização em vários proxies de API, conforme descrito em Ficheiros de recursos.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>

Predefinição:	Nenhum
Presença:	Obrigatória
Tipo:	String

Referência de erro

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e o artigo Processamento de falhas.

Erros de tempo de execução

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

Código de falha	Estado de HTTP	Causa	Corrigir
steps.javacallout.ExecutionError	500	Ocorre quando o código Java aciona uma exceção ou devolve nulo durante a execução de um JavaCallout policy.

Erros de implementação

Estes erros podem ocorrer quando o proxy que contém a política é implementado.

Nome do erro	String de falha	Estado de HTTP	Ocorre quando
ResourceDoesNotExist	Resource with name [name] and type [type] does not exist	N/A	O ficheiro especificado no elemento <ResourceURL> não existe.
JavaCalloutInstantiationFailed	Failed to instantiate the JavaCallout Class [classname]	N/A	O ficheiro de classe especificado no elemento <ClassName> não está no JAR.
IncompatibleJavaVersion	Failed to load java class [classname] definition due to - [reason]	N/A	Veja a string de falha. As versões do Java suportadas incluem: Oracle JDK 7/8 e OpenJDK 7/8
JavaClassNotFoundInJavaResource	Failed to find the ClassName in java resource [jar_name] - [class_name]	N/A	Veja a string de falha.
JavaClassDefinitionNotFound	Failed to load java class [class_name] definition due to - [reason]	N/A	Veja a string de falha.
NoAppropriateConstructor	No appropriate constructor found in JavaCallout class [class_name]	N/A	Veja a string de falha.
NoResourceForURL	Could not locate a resource with URL [string]	N/A	Veja a string de falha.

Variáveis de falha

Estas variáveis são definidas quando esta política aciona um erro. Para mais informações, consulte o artigo O que precisa de saber acerca dos erros de políticas.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme indicado na tabela Erros de tempo de execução acima. O nome da falha é a última parte do código de falha.	fault.name Matches "ExecutionError"
javacallout.policy_name.failed	policy_name é o nome especificado pelo utilizador da política que gerou a falha.	javacallout.JC-GetUserData.failed = true

Exemplo de resposta de erro

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

Exemplo de regra de falha

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

Esquemas

Exemplo: cada tipo de política é definido por um esquema XML (.xsd). Para referência, os esquemas de políticas estão disponíveis no GitHub.

Compilar e implementar

Para ver detalhes sobre como compilar o seu código Java personalizado e implementá-lo com um proxy, consulte o artigo Como criar um pedido de lance Java.

Restrições

Nota: por motivos de segurança, o Apigee aplica políticas de autorizações Java ao código de chamadas Java. As políticas aplicam-se ao código que escreve, bem como ao código de pacotes importados. Qualquer código (seja o seu código ou um código importado) falha se violar uma política de autorizações. Para ver detalhes, consulte a referência de autorizações Java.

Seguem-se as restrições que tem de considerar ao escrever código de texto destacado Java:

• A maioria das chamadas do sistema não é permitida. Por exemplo, não pode fazer leituras nem gravações no sistema de ficheiros interno.
• Acesso à rede através de tomadas. O Apigee restringe o acesso a endereços sitelocal, anylocal, loopback e linklocal.
• O texto de chamada não consegue obter informações sobre o processo atual, a lista de processos nem a utilização de CPU/memória na máquina. Embora algumas destas chamadas possam ser funcionais, não são suportadas e podem ser ativamente desativadas em qualquer altura. Para compatibilidade futura, deve evitar fazer essas chamadas no seu código.
• A confiança em bibliotecas Java incluídas no Apigee não é suportada. Essas bibliotecas destinam-se apenas à funcionalidade do produto Apigee e não existe garantia de que uma biblioteca esteja disponível de lançamento para lançamento.
• Não use io.apigee nem com.apigee como nomes de pacotes em chamadas Java. Esses nomes estão reservados e são usados por outros módulos do Apigee.

Embalagem

Coloque o JAR num proxy de API em /resources/java. Se o seu código JavaCallout depender de bibliotecas de terceiros adicionais incluídas como ficheiros JAR independentes, coloque esses ficheiros JAR também no diretório /resources/java para garantir que são carregados corretamente no tempo de execução.

Se estiver a usar a IU de gestão para criar ou modificar o proxy, adicione um novo recurso e especifique um ficheiro JAR dependente adicional. Se existirem vários JARs, basta adicioná-los como recursos adicionais. Não precisa de modificar a configuração da política para fazer referência a ficheiros JAR adicionais. Colocá-los em /resources/java é suficiente.

Para informações sobre o carregamento de ficheiros JARs Java, consulte o artigo Ficheiros de recursos.

Para ver um exemplo detalhado que demonstra como criar pacotes e implementar políticas JavaCallout através do Maven ou do javac, consulte o artigo Como criar um texto destacado Java.

Javadoc

A Javadoc para escrever código de chamadas Java está incluída aqui no GitHub. Tem de clonar ou transferir o HTML para o seu sistema e, em seguida, basta abrir o ficheiro index.html num navegador.

Notas de utilização e práticas recomendadas

• Quando trabalhar com várias políticas JavaCallout, considere carregar JARs comuns como recursos com âmbito do ambiente. Esta prática é mais eficiente em comparação com o agrupamento dos mesmos ficheiros JARs com vários pacotes de proxy quando implementados no mesmo ambiente.
• Evite criar pacotes e implementar várias cópias ou versões do mesmo ficheiro JAR num ambiente. Por exemplo, a Apigee recomenda que evite:
  • Implementar o mesmo JAR como parte de um pacote de proxy e como um recurso de ambiente.
  • Implementar uma versão de um ficheiro JAR como um recurso de ambiente e outra como parte de um pacote de proxy.

  A implementação de várias cópias do mesmo JAR pode causar um comportamento não determinístico no tempo de execução devido a potenciais conflitos do ClassLoader.

• Uma política JavaCallout não contém código real. Em alternativa, a política faz referência a um "recurso" Java e define o passo no fluxo da API em que o código Java é executado. Pode carregar o seu JAR Java através do editor de proxy da IU de gestão ou incluí-lo no diretório /resources/java em proxies de API que desenvolve localmente.
• Para operações simples, como chamadas API para serviços remotos, recomendamos a utilização da política ServiceCallout. Consulte a Política de Texto Destacado de Serviços.
• Para interações relativamente simples com o conteúdo das mensagens, como modificar ou extrair cabeçalhos HTTP, parâmetros ou conteúdo das mensagens, a Apigee recomenda a utilização de uma política JavaScript.