Política de destaque de Java

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

Confira a documentação da Apigee Edge.

Ícone da política

Conteúdo

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.

As versões Java compatíveis incluem: Oracle JDK 11 e OpenJDK 11

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.

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 nenhuma outra política padrão da Apigee.

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.

Amostras

Exemplo simples

Como criar uma chamada de 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 <JavaCallout>

<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, hífens, 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:

 falso 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.

 falso Obsoleto

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

Adiciona novas propriedades que podem ser acessadas no código Java durante a execução.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Padrão: Nenhum
Presença: Opcional
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

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de 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.

Código de falha Status HTTP Causa Correção
steps.javacallout.ExecutionError 500 Ocorre quando o código Java gera uma exceção ou retorna nulo durante a execução de um JavaCallout policy.

Erros na implantação

Esses erros podem ocorrer quando o proxy que contém a política é implantado.

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

Variáveis de falha

Essas variáveis são definidas quando esta política aciona um erro. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis Onde Exemplo
fault.name="fault_name" fault_name é o nome da falha, conforme listado na tabela Erros de ambiente 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 usuário da política que causou 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

.

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.

Restrições

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.
  • A dependência de bibliotecas Java incluídas no Apigee não é compatível. Essas bibliotecas são apenas para a funcionalidade do produto Apigee, e não há garantia de que uma biblioteca estará disponível de uma versão para 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.

Notas de uso e práticas recomendadas

  • Ao trabalhar com várias chamadas Java, considere fazer upload de JARs comuns como recursos com escopo de ambiente. Essa prática é mais eficiente do que empacotar os mesmos JARs com vários pacotes de proxy ao fazer a implantação no mesmo ambiente.
  • Evite empacotar e implantar várias cópias ou versões do mesmo arquivo JAR em um ambiente. Por exemplo, a Apigee recomenda que você evite:
    • Implantar o mesmo JAR como parte de um pacote de proxy e como um recurso de ambiente.
    • Implantar uma versão de um arquivo JAR como um recurso de ambiente e outra como parte de um pacote de proxy.

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

  • 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.