Política de destaque de Java

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

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.

Para ver as versões compatíveis do Java, consulte Software compatível e versões compatíveis.

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ê implementar um comportamento personalizado que não seja coberto por nenhuma outra política padrão do Edge.

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 frase de destaque 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 classe de execução da seguinte forma:
    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 <JavaFrase de destaque>

<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, hifens, 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.

 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.

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

Nesta seção, descrevemos os códigos e as mensagens de erro retornados e as variáveis de falha definidas pelo Edge quando a 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 uma política JavaCallout.

Erros de 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. Consulte também Software e versões compatíveis.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/D 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.
  • Não é possível depender de bibliotecas Java incluídas no Apigee Edge. Aqueles são apenas para funcionalidades do produto Edge, e não há garantia de que uma biblioteca 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.

Observações sobre uso

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

Temas relacionados