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:

 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

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

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e o artigo Processamento de falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada.

Código de falha Estado de HTTP Causa Corrigir
steps.javacallout.ExecutionError 500 Ocorre quando o código Java aciona uma exceção ou devolve nulo durante a execução de um JavaCallout policy.

Erros de implementação

Estes erros podem ocorrer quando o proxy que contém a política é implementado.

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

Variáveis de falha

Estas variáveis são definidas quando esta política aciona um erro. Para mais informações, consulte o artigo O que precisa de saber acerca dos erros de políticas.

Variáveis Onde Exemplo
fault.name="fault_name" fault_name é o nome da falha, conforme indicado na tabela Erros de tempo 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 utilizador da política que gerou 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

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.