Como criar um texto destacado Java

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

Veja a documentação do Apigee Edge.

O que é um Java Callout?

O Apigee oferece uma variedade de políticas que abordam os requisitos comuns de gestão de APIs, como segurança, transformação de dados, gestão de tráfego e outros.

No entanto, existem alguns casos em que a sua API requer um comportamento personalizado que não está implementado numa política padrão. Nestes casos, o Apigee oferece várias opções que lhe permitem criar scripts ou programar o comportamento personalizado da API. Uma abordagem consiste em implementar o comportamento desejado em Java.

As versões Java suportadas incluem: Oracle JDK 11 e OpenJDK 11.

Como posso usar código Java num proxy?

A política JavaCallout permite-lhe chamar código Java a partir de um fluxo de proxy em execução. O seu código Java tem de implementar determinadas interfaces Java específicas do Apigee que permitem ao código interagir com o proxy em execução. Por exemplo, existem métodos Java para obter e definir cabeçalhos, parâmetros de consulta, variáveis de fluxo e outras entidades no contexto de fluxo atual do proxy.

Quando devo usar a política JavaCallout?

Vejamos situações em que a política JavaCallout é útil e situações em que deve considerar outras abordagens.

Primeiro, considere abordagens alternativas

Antes de usar a política JavaCallout, tenha em atenção que podem existir abordagens alternativas que pode usar em alternativa. Por exemplo:

  • Para operações simples, como chamadas da API HTTP para serviços remotos, considere usar a 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, pode usar políticas de JavaScript ou PythonScript.

O que pode fazer no código Java

A política JavaCallout suporta estas operações básicas:

  • Examinar ou manipular mensagens de pedidos ou respostas
  • Obter e definir variáveis de fluxo. Pode usar métodos Java para aceder às variáveis de fluxo do Apigee. Se quiser aceder a informações do mapa de chave-valor (KVM), use uma política de KVM, atribua valores de KVM a variáveis de fluxo e, em seguida, pode aceder às variáveis de fluxo a partir da política JavaCallout.
  • Chamar serviços externos
  • A apresentar falhas
  • Manipular mensagens de erro e códigos de estado

O que não pode fazer no código Java

A maioria das chamadas do sistema não é permitida. Não pode:

  • Fazer leituras ou escritas internas do sistema de ficheiros. Isto significa que não pode usar nenhum dos pacotes Java para ler/escrever em sistemas de ficheiros internos. No entanto, pode fazer chamadas remotas externas.
  • Obter informações sobre o processo atual, a lista de processos ou a utilização da CPU/memória na máquina.
  • Aceda ao código-fonte no expressions-1.0.0.jar e no message-flow-1.0.0.jar.

Embora algumas destas chamadas possam funcionar, não são suportadas e podem ser ativamente desativadas em qualquer altura. Evite fazer essas chamadas no seu código.

Não use nem confie em bibliotecas Java incluídas no Apigee. 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. Se usar essas bibliotecas, use-as apenas em demonstrações de não produção.

Olá JavaCallout

Vamos analisar um exemplo básico de uma política JavaCallout "Olá mundo". Neste exemplo, criamos um proxy simples com JavaCallout que devolve uma resposta "hello world". O proxy pode devolver uma de duas respostas possíveis:

  • Se transmitir um cabeçalho "username" com um valor "name", o proxy devolve:

    Hello, <name>!
  • Se omitir o cabeçalho, o proxy devolve apenas:

    "Hello, Guest!"

Transfira o projeto inicial

Para simplificar, temos um projeto básico preparado para si no GitHub no repositório api-platform-samples do Apigee.

  1. Transfira ou clone api-platform-samples para o seu sistema. Se já tiver o api-platform-samples no seu sistema, faça um pull para se certificar de que tem a versão mais recente.
  2. Num terminal ou num editor de código à sua escolha, aceda ao projeto api-platform-samples/doc-samples/java-hello.

Escreva o código Java

  1. Abra o ficheiro de origem Java: java-hello/callout/src/main/java/HelloJava.java. Este ficheiro é uma versão esqueleto da classe Java principal que vamos implementar. Os pacotes importados são necessários para o código JavaCallout do Apigee. Estas classes fornecem métodos que lhe permitem aceder ao contexto de execução do proxy. Vamos explicar os passos para compilar e implementar este código em breve.
    package com.apigeesample;

import com.apigee.flow.execution.ExecutionContext;
import com.apigee.flow.execution.ExecutionResult;
import com.apigee.flow.execution.spi.Execution;
import com.apigee.flow.message.MessageContext;


public class HelloJava implements Execution {

        public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {

                try {

                        // Your code here.

            return ExecutionResult.SUCCESS;

                } catch (Exception e) {
                        return ExecutionResult.ABORT;
                }
        }

}
  2. Substitua a linha comentada // Your code here pelo seguinte código:

    String name = messageContext.getMessage().getHeader("username");

if (name != null && name.length()>0) {
        messageContext.getMessage().setContent("Hello, " + name + "!");
        messageContext.getMessage().removeHeader("username");
} else {
        messageContext.getMessage().setContent("Hello, Guest!");
}
  3. Guarde o ficheiro.


Compile o código com o Maven

  1. Certifique-se de que tem o Maven instalado:

    mvn -version
  2. Instale as dependências JAR necessárias no seu repositório Maven local através de um dos seguintes métodos:
    • Adicione o seguinte fragmento ao ficheiro pom.xml para transferir as dependências JAR necessárias do Artifact Registry: 
      <repositories>
  <repository>
    <id>artifact-registry</id>
    <url>https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.apigee.gateway.libraries</groupId>
    <artifactId>message-flow</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
  <dependency>
    <groupId>com.apigee.infra.libraries</groupId>
    <artifactId>expressions</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
</dependencies>
    • Use as seguintes chamadas curl para transferir as dependências JAR necessárias do Artifact Registry: 
      curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/gateway/libraries/message-flow/1.0.0/message-flow-1.0.0.jar" -v -L -o message-flow-1.0-0.jar
        
      curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/infra/libraries/expressions/1.0.0/expressions-1.0.0.jar" -v -L -o expressions-1.0.0.jar
    • Execute o script java-hello/buildsetup.sh. Este script transfere as dependências JAR necessárias do repositório do GitHub do Apigee.
  3. cd para o diretório java-hello/callout.
  4. Executar Maven:

    mvn clean package
  5. Se quiser, verifique se o ficheiro JAR edge-custom-policy-java-hello.jar foi copiado para java-hello/apiproxy/resources/java. Esta é a localização necessária para os ficheiros JAR que quer implementar com um proxy.

Implemente e chame o proxy

Siga estes passos para implementar e testar o proxy de API:

  1. Mude para o diretório java-hello.
  2. Comprima o pacote do proxy de API: 
    zip apiproxy-bundle.zip -r apiproxy -x \*.\*~
  3. A forma mais simples de implementar o proxy é incluí-lo num ficheiro ZIP e carregar o pacote do proxy para um ambiente na sua organização do Apigee. Consulte o artigo Criar um proxy de API. Certifique-se de que usa a opção Carregar pacote de proxy. Veja também Sugestões e truques para carregar um proxy de API num pacote de proxies na comunidade do Apigee.
  4. Quando o proxy for implementado, experimente chamá-lo:
    curl  https://$HOSTNAME/java-hello -H "username:Will"

    Que devolve "Hello, Will!

Acerca do proxy

Vamos analisar rapidamente as políticas usadas neste proxy. Preste atenção à posição das políticas no fluxo do proxy e porquê.

A política de atribuição de mensagens

Uma política de atribuição de mensagens está anexada ao fluxo de pedidos do ProxyEndpoint. Copia o cabeçalho do nome de utilizador do pedido e atribui-o à resposta. Esta operação permite que a política JavaCallout, que está anexada ao fluxo de resposta, aceda ao cabeçalho do nome de utilizador e crie um corpo de resposta personalizado com o valor desse cabeçalho.

<AssignMessage async="false" continueOnError="false" enabled="true" name="CopyHeader">
    <DisplayName>CopyHeader</DisplayName>
    <Copy source="request">
        <Headers>
          <Header name="username"/>
        </Headers>
    </Copy>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

A política JavaCallout

A política JavaCallout está anexada ao fluxo de resposta. Isto deve-se ao facto de o código Java personalizado fazer alterações aos cabeçalhos de resposta e à mensagem. O elemento ClassName da política especifica a classe principal que é executada pela política. O elemento ResourceURL é o nome do ficheiro JAR que criou e adicionou ao diretório resources/java do proxy.

<JavaCallout name="hello-java">
    <ClassName>com.apigeesample.HelloJava</ClassName>
    <ResourceURL>java://edge-custom-policy-java-hello.jar</ResourceURL>
</JavaCallout>

O que precisa de saber sobre a política JavaCallout

Aspetos importantes a ter em conta acerca da implementação da política JavaCallout:

  • Importa turmas dos pacotes com.apigee.flow.execution e com.apigee.flow.message. Estes pacotes têm de ser incluídos no ficheiro JAR que é incluído e implementado. Pode carregar o seu JAR Java através do editor do proxy da IU de gestão ou pode incluí-lo no diretório /resources/java em proxies de API que desenvolve localmente.
  • Implementa a interface Execution. Qualquer código Java executado num proxy de API tem de implementar a execução.
  • A política JavaCallout não contém código real. Em vez disso, a política faz referência a um "recurso" Java, que tem de agrupar num JAR.
  • Nomes de pacotes a evitar: não use io.apigee nem com.apigee como nomes de pacotes nas políticas JavaCallout. Estes estão reservados e são usados por outros módulos do Apigee.
  • Se a sua política JavaCallout depender de bibliotecas de terceiros adicionais incluídas como ficheiros JAR independentes, coloque também esses ficheiros JAR no diretório /resources/java para garantir que são carregados corretamente no tempo de execução.
  • 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 mais informações sobre o carregamento de ficheiros JARs Java, consulte o artigo Ficheiros de recursos.