Política de destaque de Java

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

Confira a documentação da Apigee Edge.

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.

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.

Observação: Importante: se você estiver desenvolvendo políticas de frase de destaque Java, precisará saber quais políticas de permissão estão em vigor na Apigee JVM e como elas afetarão seu código. Consulte a referência de permissão do Java. Veja também Restrições.

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.

Observação: a Apigee recomenda o uso da política de JavaScript se você estiver inclinado a usar JavaScript. Se preferir, use a política de frases de destaque de serviço se precisar fazer chamadas HTTP para serviços remotos. No entanto, se quiser escrever código Java personalizado, você terá essa opção. Consulte também Quando devo usar uma frase de destaque Java.

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	Presence
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: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual Dica: Nos casos em que seu código Java gera uma exceção, o fluxo de proxy da Apigee muda para o status de falha, mesmo que o atributo continueOnError esteja definido como verdadeiro. Se você não quiser que uma exceção gerada resulte em um status de falha no proxy, crie a chamada do Java para que ela não gere erros. Em vez disso, capture exceções e defina uma variável de contexto para capturar as informações da exceção. Para mais informações, consulte esta postagem da comunidade da Apigee.	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.	true	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.
Presence	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	Presence
nome	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/A	O arquivo especificado no elemento <ResourceURL> não existe.
JavaCalloutInstantiationFailed	Failed to instantiate the JavaCallout Class [classname]	N/A	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/A	Consulte string de falha.
NoAppropriateConstructor	No appropriate constructor found in JavaCallout class [class_name]	N/A	Consulte string de falha.
NoResourceForURL	Could not locate a resource with URL [string]	N/A	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

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

.

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

Observação: por motivos de segurança, a Apigee aplica políticas de permissões Java ao código de frase de destaque Java. As políticas se aplicam ao código que você escreve, bem como ao código de pacotes importados. Qualquer código (código ou importado) falhará se violar uma política de permissão. Para detalhes, consulte Referência de permissão do 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.
• 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.