Как создать вызов Java

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

Что такое вызов Java?

Apigee Edge предоставляет ряд правил, которые отвечают распространенным требованиям к управлению API, таким как безопасность, преобразование данных, управление трафиком и т. д.

Однако в некоторых случаях API требует особого поведения, которое не реализовано в стандартных правилах. В таких случаях Apigee предлагает несколько вариантов, позволяющих создавать скрипты или код для настройки поведения API. Один из способов – реализовать нужное поведение на Java.

Список поддерживаемых версий Java приведен в статье Поддерживаемое программное обеспечение и его версии.

Как использовать код Java в прокси-сервере?

Правило вызова Java позволяет вызывать код Java из выполняемого потока прокси. В коде Java должны быть реализованы определенные интерфейсы Java, которые позволяют коду взаимодействовать с выполняемым прокси. Например, в Java есть методы для получения и установки заголовков, параметров запроса, переменных потока и других объектов в текущем контексте потока прокси.

Когда следует использовать вызов Java?

Давайте рассмотрим ситуации, в которых полезны вызовы Java, и ситуации, в которых следует рассмотреть другие подходы.

Сначала рассмотрите альтернативные подходы

Прежде чем использовать вызов Java, обратите внимание, что существуют альтернативные подходы, которые можно использовать вместо него. Пример:

  • Для простых операций, таких как вызовы HTTP API к удаленным сервисам, можно использовать правило ServiceCallout. Ознакомьтесь с правилами в отношении описаний услуг.
  • Для относительно простых взаимодействий с контентом сообщений, например для изменения или извлечения HTTP-заголовков, параметров или контента сообщений, можно использовать языки JavaScript или Python.

Что можно делать с помощью кода Java

Вызов Java поддерживает следующие основные операции:

  • Проверка или изменение сообщений запросов или ответов
  • Получение и настройка переменных потока. Для доступа к переменным потока Edge можно использовать методы Java. Если вам нужна информация из карты "ключ-значение" (KVM), используйте правило KVM, назначьте значения KVM переменным потока, а затем получите доступ к этим переменным из вызова Java.
  • Вызовы внешних сервисов
  • Сообщения о неисправностях
  • Как изменять сообщения об ошибках и коды статуса

Что нельзя делать в коде Java

Большинство системных вызовов запрещено. Вы не можете:

  • выполнять внутренние операции чтения и записи в файловой системе; Это означает, что вы не можете использовать ни один из пакетов Java для чтения и записи во внутренние файловые системы, но можете выполнять внешние удаленные вызовы.
  • Получать информацию о текущем процессе, списке процессов или использовании ЦП/памяти на устройстве.
  • Исходный код можно найти в файлах `expressions-1.0.0.jar` и `message-flow-1.0.0.jar`.

Хотя некоторые из таких звонков могут работать, они не поддерживаются и могут быть отключены в любое время. Не используйте такие вызовы в коде.

Не используйте библиотеки Java, которые входят в состав Apigee Edge. Эти библиотеки предназначены только для функций продукта Edge, и нет гарантии, что они будут доступны в каждом выпуске. Если вы используете такие библиотеки, делайте это только в демонстрационных целях, а не в рабочих нагрузках.

Уточнение "Здравствуйте"

Рассмотрим простой пример вызова Java-кода "Hello, world!". В этом примере мы создадим простой прокси-сервер с вызовом Java, который возвращает ответ "hello world". Прокси-сервер может вернуть один из двух возможных ответов:

  • Если вы передадите заголовок username со значением name, прокси-сервер вернет:

    Hello, <name>!
  • Если вы не укажете заголовок, прокси-сервер вернет только:

    "Hello, Guest!"

Скачайте стартовый проект

Чтобы упростить задачу, мы подготовили для вас базовый проект на GitHub в репозитории Apigee api-platform-samples.

  1. Скачайте или клонируйте api-platform-samples в свою систему.
  2. В терминале или редакторе кода перейдите в проект api-platform-samples/doc-samples/java-hello.

Напишите код Java

  1. Откройте исходный файл Java: java-hello/callout/src/main/java/HelloJava.java. Этот файл представляет собой скелет основного класса Java, который мы реализуем. Импортированные пакеты необходимы для кода Edge Java Callout. Эти классы предоставляют методы, которые позволяют получить доступ к контексту выполнения прокси. Ниже мы расскажем, как скомпилировать и развернуть этот код.
    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. Замените закомментированную строку // Your code here следующим кодом:

    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. Сохраните файл.


Компиляция кода с помощью Maven

Проект настроен так, что его можно скомпилировать с помощью Maven. Если вы хотите использовать javac, мы приведем пример после примера с Maven.

  1. Убедитесь, что у вас установлен Maven:

    mvn -version
  2. Выполните скрипт java-hello/buildsetup.sh. Этот скрипт устанавливает необходимые зависимости JAR в локальном репозитории Maven.
  3. Перейдите в каталог java-hello/callout.
  4. Выполнить Maven:

    mvn clean package
  5. При необходимости убедитесь, что JAR-файл edge-custom-policy-java-hello.jar был скопирован в папку java-hello/apiproxy/resources/java. Это обязательное местоположение для JAR-файлов, которые вы хотите развернуть с помощью прокси-сервера.

Компиляция с помощью javac (необязательно)

В предыдущем разделе вы автоматически создали необходимый JAR-файл Java с помощью команды Maven. Если вы хотите использовать javac для компиляции кода, вы можете сделать что-то похожее на следующее (из каталога java-hello). Необходимые JAR-файлы находятся в каталоге java-hello/lib.

  1. Перейдите в каталог api-platform-samples/doc-samples/java-hello.
  2. Убедитесь, что в пути есть javac.

    javac -version
  3. Выполните следующую команду javac:

    javac -d . -classpath ./lib/expressions-1.0.0.jar:./lib/message-flow-1.0.0.jar:. callout/src/main/java/HelloJava.java
     Это создаст com/apigeesample/HelloJava.class.
  4. Создайте JAR-файл, содержащий скомпилированный класс, в каталоге apiproxy/resources/java. Это обязательное местоположение для JAR-файлов, которые вы хотите развернуть с помощью прокси-сервера. Для этого выполните следующую команду в каталоге java-hello (не забудьте точку в конце).

    jar cvf apiproxy/resources/java/edge-custom-policy-java-hello.jar -C com .

Как развернуть и вызвать прокси-сервер

Скрипт развертывания находится в каталоге ./java-hello. Но перед этим нужно выполнить быструю настройку.

  1. cd api-platform-samples/doc-samples/java-hello
  2. Если вы ещё этого не сделали, откройте файл ../../setup/setenv.sh и измените его, указав информацию о своем аккаунте Apigee: имя пользователя (адрес электронной почты, связанный с аккаунтом), название организации и домен, который вы используете для вызовов API управления. Например, для облака Edge домен будет выглядеть так: https://api.enterprise.apigee.com. Однако если вы используете частное облако Edge, домен может быть другим.
  3. Сохраните файл setenv.sh.
  4. Выполните скрипт развертывания:

    ./deploy.sh
  5. Если развертывание прошло успешно, выполните скрипт вызова:

    ./invoke.sh

    Скрипт invoke вызывает команду cURL, которая выглядит следующим образом:

    curl  http://$org-$env.$api_domain/java-hello -H "username:Will"

    В результате будет возвращено значение "Hello, Will!

    Вы можете изменить invoke.sh, чтобы изменить имя, или удалить заголовок из вызова cURL, чтобы команда возвращала "Здравствуйте, гость!"

О прокси-сервере

Давайте быстро рассмотрим правила, используемые в этом прокси-сервере. Обратите внимание на то, где в потоке прокси-сервера размещены правила и почему.

Правила назначения сообщений

Правило Assign Message прикреплено к потоку запросов ProxyEndpoint. Он копирует заголовок имени пользователя из запроса и назначает его ответу. Эта операция позволяет правилу Java Callout, прикрепленному к потоку ответов, получить доступ к заголовку имени пользователя и создать собственный текст ответа, используя значение этого заголовка.

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

Правила в отношении уточнений Java

Правила вызова Java прикреплены к потоку ответов. Это связано с тем, что пользовательский код Java вносит изменения в заголовки ответа и сообщение. Элемент ClassName правила указывает на основной класс, который выполняется правилом. Элемент ResourceURL – это название JAR-файла, который вы создали и добавили в каталог resources/java прокси-сервера.

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

Что нужно знать о вызове Java

При реализации вызова Java следует учитывать следующие важные моменты:

  • Импортирует классы из пакетов com.apigee.flow.execution и com.apigee.flow.message. Эти пакеты должны быть включены в JAR-файл, который упаковывается и развертывается. Вы можете загрузить JAR-файл Java через редактор прокси-сервера в интерфейсе управления или включить его в каталог /resources/java в прокси-серверах API, которые вы разрабатываете локально.
  • Реализует интерфейс Execution. Любой код Java, выполняемый в прокси-сервере API, должен реализовывать интерфейс Execution.
  • Правило Java Callout не содержит кода. Вместо этого в правиле Java Callout указывается ссылка на ресурс Java, который необходимо упаковать в JAR-файл.
  • Названия пакетов, которых следует избегать. Не используйте io.apigee или com.apigee в качестве названий пакетов в вызовах Java. Они зарезервированы и используются другими модулями Apigee.
  • Если ваш вызов Java зависит от дополнительных сторонних библиотек, упакованных в виде отдельных JAR-файлов, поместите эти JAR-файлы в каталог /resources/java, чтобы они правильно загружались во время выполнения.
  • Если файлов JAR несколько, добавьте их как дополнительные ресурсы. Вам не нужно изменять конфигурацию правил, чтобы ссылаться на дополнительные JAR-файлы. Достаточно указать их в разделе /resources/java.
  • Дополнительную информацию о загрузке JAR-файлов Java можно найти в разделе Файлы ресурсов.