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

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

Что такое выноска Java?

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

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

Информацию о поддерживаемых версиях Java см. в разделе Поддерживаемое программное обеспечение и поддерживаемые версии .

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

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

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

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

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

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

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

Что вы можете сделать в Java-коде

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

  • Проверка или манипулирование сообщениями запроса или ответа
  • Получение и установка переменных потока. Вы можете использовать методы Java для доступа к переменным потока Edge. Если вы хотите получить доступ к информации о карте ключевых значений (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. В этом примере мы создаем простой прокси-сервер с вызовом Java, который возвращает ответ «привет, мир». Прокси-сервер может вернуть один из двух возможных ответов:

  • Если вы передадите заголовок «имя пользователя» со значением «имя», прокси вернет:

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

    "Hello, Guest!"

Загрузите стартовый проект

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

  1. Загрузите или клонируйте образцы API-платформы в свою систему.
  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. перейдите api-platform-samples/doc-samples/java-hello
  2. Если вы еще этого не сделали, откройте файл ../../setup/setenv.sh и отредактируйте его, как указано, указав информацию вашей учетной записи Apigee: ваше имя пользователя (адрес электронной почты, связанный с вашей учетной записью), название вашей организации, и домен, который вы используете для вызовов управления API. Например, для облака Edge домен — https://api.enterprise.apigee.com ; однако ваш домен может быть другим, если вы используете Edge Private Cloud.
  3. Сохраните файл setenv.sh .
  4. Выполните сценарий развертывания:

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

    ./invoke.sh

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

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

    Что возвращает «Привет, Уилл!

    Вы можете отредактировать сценарий invoke.sh чтобы изменить имя, или если вы измените вызов cURL, чтобы удалить заголовок, команда вернет «Привет, Гость!»

О прокси

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

Политика назначения сообщений

Политика сообщений Assign прикрепляется к потоку запросов 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, который упаковывается и развертывается. Вы можете загрузить свой Java JAR через редактор прокси-сервера пользовательского интерфейса управления или включить его в каталог /resources/java в прокси API, которые вы разрабатываете локально.
  • Реализует интерфейс выполнения. Любой код Java, который выполняется внутри прокси-сервера API, должен реализовывать выполнение.
  • Политика Java Callout не содержит реального кода. Вместо этого политика Java Callout ссылается на «ресурс» Java, который необходимо упаковать в JAR.
  • Имена пакетов, которых следует избегать: не используйте io.apigee или com.apigee в качестве имен пакетов в выносках Java. Они зарезервированы и используются другими модулями Apigee.
  • Если ваша Java Callout использует дополнительные сторонние библиотеки, упакованные в виде независимых файлов JAR, поместите эти файлы JAR в каталог /resources/java , чтобы гарантировать их правильную загрузку во время выполнения.
  • Если имеется несколько файлов JAR, просто добавьте их в качестве дополнительных ресурсов. Вам не нужно изменять конфигурацию политики для обращения к дополнительным файлам JAR. Достаточно поместить их в /resources/java .
  • Дополнительную информацию о загрузке файлов JAR Java см. в разделе Файлы ресурсов .