Como criar uma chamada de Java

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

Confira a documentação da Apigee Edge.

O que é uma frase de destaque do Java?

A Apigee fornece várias políticas que abordam requisitos comuns de gerenciamento de API, como segurança, transformação de dados, gerenciamento de tráfego e outros.

No entanto, em alguns casos, a API requer um comportamento personalizado que não seja implementado em uma política padrão. Nesses casos, a Apigee oferece várias opções que permitem criar scripts ou codificar comportamentos da API personalizada. Uma abordagem é implementar o comportamento desejado em Java.

As versões Java compatíveis incluem: Oracle JDK 11 e OpenJDK 11.

Como usar código Java em um proxy?

Uma política de chamada Java permite chamar código Java a partir de um fluxo de proxy em execução. O código Java precisa implementar determinadas interfaces Java específicas da Apigee que permitem que o código interaja com o proxy em execução. Por exemplo, os métodos Java existem para receber e definir cabeçalhos, parâmetros de consulta, variáveis de fluxo e outras entidades no contexto atual do fluxo do proxy.

Quando devo usar uma chamada Java?

Vejamos as situações em que as chamadas Java são úteis e as situações em que você deve considerar outras abordagens.

Primeiro, pense em abordagens alternativas

Antes de usar uma chamada de Java, pode haver abordagens alternativas que você pode usar. Exemplo:

Para operações leves, como chamadas de API HTTP para serviços remotos, considere usar a política ServiceCalling. Consulte a política de frase de destaque de serviço.
Para interações relativamente simples com conteúdo de mensagens, como modificar ou extrair cabeçalhos, parâmetros ou conteúdo de mensagens HTTP, você pode usar políticas JavaScript ou Python.

O que você pode fazer no código Java

Uma chamada Java é compatível com as seguintes operações básicas:

Examinar ou manipular mensagens de solicitação ou resposta
Receber e definir variáveis de fluxo. É possível usar métodos Java para acessar variáveis de fluxo da Apigee. Se você quiser acessar as informações do mapa de valor-chave (KVM), use uma política KVM, atribua valores de KVM às variáveis de fluxo e, em seguida, acesse as variáveis de fluxo dentro da chamada Java.
Como chamar serviços externos
Como informar falhas
Manipular mensagens de erro e códigos de status

O que não é possível fazer no código Java

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

Fazer leituras ou gravações no sistema de arquivos interno. Isso significa que não é possível usar nenhum dos pacotes Java para ler/gravar em sistemas de arquivos internos; No entanto, é possível fazer chamadas remotas externas.
Receba informações sobre o processo atual, a lista de processos ou o uso da CPU/memória na máquina.
Acesse o código-fonte em expressions-1.0.0.jar e message-flow-1.0.0.jar.

Embora algumas chamadas possam funcionar, elas não são compatíveis e ficam sujeitas à desativação ativa a qualquer momento. Evite fazer essas chamadas no seu código.

Não use ou dependa de bibliotecas Java incluídas na Apigee. 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. Se você usar essas bibliotecas, use-as apenas em demonstrações que não sejam de produção.

Chamada Hello Java

Acompanhe um exemplo básico de chamada Java. Neste exemplo, criamos um proxy simples com uma chamada Java que retorna uma resposta "hello world". O proxy pode retornar uma das duas respostas possíveis:

Se você transmitir o cabeçalho "username" com o valor "name", o proxy retornará:
```
Hello, <name>!
```
Se você omitir o cabeçalho, o proxy retornará apenas:
```
"Hello, Guest!"
```

Faça o download do projeto inicial

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

Faça o download ou clone api-platform-samples no seu sistema. Se você já tem api-platform-samples no sistema, faça uma pull para garantir que tenha a versão mais recente.
Em um terminal ou editor de código de sua escolha, acesse o projeto api-platform-samples/doc-samples/java-hello.

Escrever o código Java

Abra o arquivo de origem Java: java-hello/callout/src/main/java/HelloJava.java. Este arquivo é uma versão de esqueleto da principal classe Java que implementaremos. Os pacotes importados são necessários para o código de chamada Java da Apigee. Essas classes fornecem métodos que permitem que você acesse o contexto de execução de proxy. Explicaremos as etapas para compilar e implantar esse 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;
                }
        }

}

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!");
}
```
Observação: Observação: o objeto MessageContext permite acessar entidades dentro do fluxo em que a política de chamada Java é executada. Digamos que a política de chamada Java esteja anexada ao fluxo de resposta do endpoint do proxy. O código listado acima recebe o objeto de mensagem HTTP para esse contexto de fluxo. O objeto Message, por sua vez, fornece acesso a cabeçalhos, parâmetros de consulta, conteúdo do corpo e variáveis de fluxo.
Salve o arquivo.

Compile seu código com o Maven

Verifique se você tem o Maven instalado:
```
mvn -version
```

Instale as dependências JAR necessárias no seu repositório Maven local usando um dos seguintes métodos:

Adicione o seguinte snippet ao arquivo pom.xml para fazer o download das 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 fazer o download das 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 a java-hello/buildsetup.sh. Esse script faz o download das dependências JAR necessárias do repositório da Apigee no GitHub.

cd para o diretório java-hello/callout.
Execute o Maven:
```
mvn clean package
```
Observação: se aparecer um erro do Maven, verifique se você está no diretório java-hello/callout.
Se você quiser, verifique se o arquivo JAR edge-custom-policy-java-hello.jar foi copiado para java-hello/apiproxy/resources/java. Este é o local necessário para os arquivos JAR que você quer implantar com um proxy.

Implantar e chamar o proxy

Siga estas etapas para implantar e testar o proxy de API:

Altere para o diretório java-hello.

Compacte o pacote do proxy de API:

zip apiproxy-bundle.zip -r apiproxy -x \*.\*~

A maneira mais simples de implantar o proxy é agrupá-lo em um arquivo ZIP e fazer upload do pacote de proxy em um ambiente na sua organização da Apigee. Consulte Como criar um proxy de API. Use a opção Fazer upload de pacote de proxy. Veja também Dicas e truques para fazer upload de proxy de API em um pacote proxy na comunidade Apigee.
Quando o proxy estiver implantado, tente chamá-lo:
```
curl  https://$HOSTNAME/java-hello -H "username:Will"
```
Isso retorna "Hello, Will!

Sobre o proxy

Vamos examinar rapidamente as políticas usadas neste proxy. Preste atenção no local em que as políticas estão posicionadas no fluxo do proxy e por quê.

A política "Atribuir mensagem"

Uma política "Atribuir mensagem" é anexada ao fluxo de solicitações do ProxyEndpoint. Ele copia o cabeçalho do nome de usuário da solicitação e o atribui à resposta. Essa operação permite que a política de chamadas Java, que é anexada ao fluxo de resposta, para acessar o cabeçalho do nome de usuário e criar um corpo de resposta personalizado usando 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 de chamada Java

A política de chamada Java é anexada ao fluxo de resposta. Isso ocorre porque o código Java personalizado faz alterações nos cabeçalhos de resposta e na mensagem. O elemento ClassName da política especifica a classe principal que é executada pela política. O elemento ResourceURL é o nome do arquivo JAR que você 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 você precisa saber sobre a chamada Java

Observações importantes sobre a implementação de uma chamada Java são:

Importa classes dos pacotes com.apigee.flow.execution e com.apigee.flow.message. Esses pacotes precisam ser incluídos no arquivo JAR empacotado e implantado. 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.
Implementa a interface de execução. Qualquer código Java que é executado em um proxy de API precisa implementar a execução.
Uma política de chamada Java não contém código real. Em vez disso, uma política de chamada de Java se refere a um "recurso" Java, que você precisa empacotar em um JAR.
Nomes de pacote a serem evitados: não use io.apigee ou com.apigee como nomes de pacote no Java Callouts. Eles são reservados e usados por outros módulos da Apigee.
Se a chamada 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 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 mais informações sobre como fazer upload de JARs do Java, consulte Arquivos de recursos.