O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Política de destaque de Java

Política extensível

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

Confira a documentação da Apigee Edge.

A política JavaCallout permite usar o Java para implementar um comportamento personalizado que não está incluído pronto para uso pelas políticas da Apigee. No código Java, é possível acessar propriedades de mensagens (cabeçalhos, parâmetros de consulta, conteúdo), receber e definir variáveis de fluxo, executar lógica personalizada e tratamento de erros, extrair dados de solicitações ou respostas e muito mais. Se você estiver começando a usar essa política, consulte Como criar uma chamada de 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 JavaCallout. Elas estão listadas em Restrições.

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.

Amostras

Exemplos gerais

Para um exemplo simples usando uma chamada de Java, consulte Como criar uma chamada de Java.

Para saber como definir variáveis de fluxo no seu código Java, consulte esta postagem da comunidade da Apigee sobre depuração de frases de destaque do Java.

Recuperar propriedades no código Java

Este exemplo mostra como usar o atributo name do elemento <Property> para especificar o nome com que acessar a propriedade 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.

A configuração requer duas partes:

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>
</JavaCallout>

No código Java, implemente o seguinte construtor na classe Execution:

public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

            // Extract property values from map.
    }
    ...
}

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: 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 o código da chamada de Java para que ele 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.	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	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

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo `name` da política.
Presença	Opcional
Tipo	String

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 JavaCallout é 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 política JavaCallout.

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

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

Atributos

Atributo	Descrição	Padrão	Presença
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 JavaCallout 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

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码	HTTP 状态	原因	修复
`steps.javacallout.ExecutionError`	`500`	当 Java 代码执行 `JavaCallout policy` 时抛出异常或返回 null 时发生。

部署错误

部署包含政策的代理时，可能会出现此类错误。

错误名称	故障字符串	HTTP 状态	发生的条件
`ResourceDoesNotExist`	`Resource with name [name] and type [type] does not exist`	不适用	`<ResourceURL>` 元素中指定的文件不存在。
`JavaCalloutInstantiationFailed`	`Failed to instantiate the JavaCallout Class [classname]`	不适用	在 `<ClassName>` 元素中指定的类文件不在 jar 中。
`IncompatibleJavaVersion`	`Failed to load java class [classname] definition due to - [reason]`	不适用	请参阅故障字符串。支持的 Java 版本包括：Oracle JDK 7/8 和 OpenJDK 7/8
`JavaClassNotFoundInJavaResource`	`Failed to find the ClassName in java resource [jar_name] - [class_name]`	不适用	请参阅故障字符串。
`JavaClassDefinitionNotFound`	`Failed to load java class [class_name] definition due to - [reason]`	不适用	请参阅故障字符串。
`NoAppropriateConstructor`	`No appropriate constructor found in JavaCallout class [class_name]`	不适用	请参阅故障字符串。
`NoResourceForURL`	`Could not locate a resource with URL [string]`	不适用	请参阅故障字符串。

故障变量

此政策触发错误时设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量	位置	示例
`fault.name="fault_name"`	`fault_name` 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。	`fault.name Matches "ExecutionError"`
`javacallout.policy_name.failed`	`policy_name` 是抛出故障的政策的用户指定名称。	`javacallout.JC-GetUserData.failed = true`

错误响应示例

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

故障规则示例

<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

Confira abaixo as restrições que você precisa considerar ao escrever o código de chamada de 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 o código JavaCallout 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 políticas JavaCallout usando o Maven ou o javac, consulte Como criar uma chamada Java.

Javadoc

O Javadoc para escrever código de chamada de Java 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 políticas JavaCallout, 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 JavaCallout não contém código real. Em vez disso, a política faz referência a um "recurso" Java e define a etapa no fluxo da API em que 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.