Política de destaque de Java

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

O que

Permite usar o Java para implementar comportamento personalizado que não está pronto para uso pelas políticas da Apigee. No código Java, é possível acessar as propriedades da mensagem (cabeçalhos, parâmetros de consulta, conteúdo) e variáveis de fluxo no fluxo de proxy. Se você estiver começando a usar essa política, consulte Como criar uma chamada de Java.

Para conferir as versões com suporte do Java, consulte Softwares e versões compatíveis.

Quando

Para orientações, consulte "Quando devo usar uma chamada Java?" em Como criar uma chamada Java.

Sobre

A política de frase de destaque Java permite conseguir e definir variáveis de fluxo, executar lógica personalizada e executar tratamento de erros, extrair dados de solicitações ou respostas e muito mais. Essa política permite que você implemente um comportamento personalizado que não é coberto por outras políticas padrão do Edge.

Você pode empacotar seu aplicativo Java com qualquer arquivo JAR de pacote necessário. Há algumas restrições sobre o que você pode fazer com uma frase de destaque Java. Eles estão listados abaixo em Restrições.

Exemplos

Exemplo simples

Como criar uma frase de destaque Java

Recuperar propriedades no código Java

O elemento <Property> da política permite especificar um par de nome/valor que pode ser recuperado no ambiente de execução no código Java. Para um exemplo funcional que usa propriedades, consulte Como usar propriedades em uma frase de destaque Java.

Use o atributo name do elemento <Property> para especificar o nome com que acessar a propriedade a partir do código Java. O valor do elemento <Property> (o valor entre as tags de abertura e fechamento) é o valor que será recebido pelo código Java. O valor precisa ser uma string. não é possível referenciar uma variável de fluxo para conseguir 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 código Java, implemente o seguinte construtor na implementação da classe Execution da seguinte maneira:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

Definir variáveis de fluxo no 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, veja esta postagem da Apigee.

Referência de elemento

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

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

Atributos de <JavaFrase de destaque>

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

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 <ClassName>

Especifica o nome da classe Java que é executada quando a política de chamada de Java é executada. A classe precisa ser incluída no arquivo JAR especificado por <ResourceURL>. Consulte também Como criar uma frase de destaque Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Padrão: N/A
Presença: Obrigatório
Tipo: String

Elemento de {Property}

Especifica uma propriedade que você pode acessar a partir do código Java no tempo de execução. Você precisa especificar um valor de string literal para cada propriedade. não é possível referenciar variáveis de fluxo neste elemento. Para um exemplo prático que usa propriedades, consulte Como usar propriedades em uma frase de destaque Java.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Padrão: Nenhum
Presença: Opcional
Tipo: String

Atributos

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

Especifica o nome da propriedade.

 N/A Obrigatório.

<ResourceURL> element

Esse elemento especifica o arquivo Java JAR que será executado quando a política de chamadas Java for executada.

Você pode armazenar esse arquivo no escopo do proxy da API (em /apiproxy/resources/java no pacote de proxy da API ou na seção "Scripts" do painel de navegação do editor de proxy de API) ou nos escopos da organização ou do ambiente para reutilização em vários proxies de API, conforme descrito em Arquivos de recurso.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Padrão: Nenhum
Presença: Obrigatório
Tipo: String

Referência de erros

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

Fault code HTTP status Cause Fix
steps.javacallout.ExecutionError 500 Occurs when Java code throws an exception or returns null during the execution of a JavaCallout policy.

Deployment errors

These errors can occur when the proxy containing the policy is deployed.

Error name Fault string HTTP status Occurs when
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A The file specified in the <ResourceURL> element does not exist.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A The class file specified in the <ClassName> element is not in the jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A See fault string. See also Supported software and supported versions.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A See fault string.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A See fault string.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A See fault string.
NoResourceForURL Could not locate a resource with URL [string] N/A See fault string.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javacallout.JC-GetUserData.failed = true

Example error response

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

Example fault rule

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

Esquemas

Como compilar e implantar

Para detalhes sobre como compilar seu código Java personalizado e implantá-lo com um proxy, consulte Como criar uma chamada Java.

Veja abaixo as restrições que você precisa considerar ao escrever frases de destaque Java:

  • A maioria das chamadas do sistema não é permitida. Por exemplo, não é possível fazer leituras ou gravações internas do sistema de arquivos.
  • Acesso à rede via soquetes. A Apigee restringe o acesso a endereços sitelocal, anylocal, loopback e linklocal.
  • A frase de destaque não pode receber informações sobre o processo atual, a lista de processos ou a utilização da CPU/memória na máquina. Embora algumas chamadas possam ser funcionais, elas não são compatíveis e são responsáveis por serem desativadas ativamente a qualquer momento. Para compatibilidade com versões futuras, evite fazer essas chamadas no seu código.
  • Não há suporte para as bibliotecas Java incluídas no Apigee Edge. Essas bibliotecas são apenas para funcionalidades de produtos Edge, e não há garantia de que uma biblioteca estará disponível de uma versão para a outra.
  • Não use io.apigee ou com.apigee como nomes de pacotes em chamadas do Java. Esses nomes são reservados e usados por outros módulos da Apigee.

Empacotamento

Coloque o JAR em um proxy de API em /resources/java. Se a frase de destaque Java depender de outras bibliotecas de terceiros empacotadas como arquivos JAR independentes, coloque esses arquivos JAR no diretório /resources/java para garantir que eles sejam carregados corretamente no ambiente de execução.

Se você estiver usando a interface de gerenciamento para criar ou modificar o proxy, adicione um novo recurso e especifique um arquivo JAR dependente adicional. Se houver vários JARs, basta adicioná-los como recursos adicionais. Não é necessário modificar a configuração da política para se referir a outros arquivos JAR. Colocar os dados em /resources/java é suficiente.

Para informações sobre como fazer upload de JARs do Java, consulte Arquivos de recursos.

Para ver um exemplo detalhado que demonstra como empacotar e implantar uma frase de destaque Java usando o Maven ou o javac, consulte Como criar uma chamada Java.

Javadoc

O Javadoc para escrever código Java Callout está incluído aqui no GitHub. Você precisará clonar ou fazer o download do HTML para seu sistema e simplesmente abrir o arquivo index.html em um navegador.

Observações sobre uso

  • Uma política de frase de destaque Java não contém código real. Em vez disso, uma política de frase de chamada Java faz referência a um "recurso" Java e define a etapa no fluxo da API onde o código Java é executado. Você pode fazer upload do JAR Java usando o Editor de proxy da IU de gerenciamento ou incluí-lo no diretório /resources/java nos proxies de API desenvolvidos localmente.
  • Para operações leves, como chamadas de API para serviços remotos, recomendamos usar a política ServiceCallout. Consulte a política de frase de destaque de serviço.
  • Para interações relativamente simples com conteúdo de mensagens, como modificação ou extração de cabeçalhos HTTP, parâmetros ou conteúdo da mensagem, a Apigee recomenda o uso de uma política JavaScript.

Temas relacionados