Política JavaCallout

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

Veja a documentação do Apigee Edge.

A política JavaCallout 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), obter e definir variáveis de fluxo, executar lógica personalizada e realizar o processamento de erros, extrair dados de pedidos ou respostas e muito mais. Se está a começar a usar esta política, consulte o artigo Como criar um texto explicativo em Java.

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 em Restrições.

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.

Amostras

Exemplos gerais

Para ver um exemplo simples que usa um texto destacado Java, consulte o artigo Como criar um texto destacado Java.

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

Recupere propriedades no seu código Java

Este exemplo mostra como usar 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.

A configuração requer dois elementos:

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 seu 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 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`	Defina 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 falha 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 captar 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

Predefinição	N/A Se omitir este elemento, é usado o valor do atributo `name` da política.
Presença	Opcional
Tipo	String

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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. Supported Java versions include: Oracle JDK 7/8 and OpenJDK 7/8
`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

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

Restrições

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 explicativo 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 utilização de 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 Java Textos destacados. 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 com o Maven ou o javac, consulte o artigo Como criar um Java callout.

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 de ambiente. Esta prática é mais eficiente em comparação com o agrupamento dos mesmos 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.