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

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

Что такое вызов функции Java?

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

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

Список поддерживаемых версий Java см. в разделах «Поддерживаемое программное обеспечение» и «Поддерживаемые версии» .

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

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

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

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

Во-первых, рассмотрите альтернативные подходы.

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

  • Для несложных операций, таких как вызовы HTTP API к удаленным сервисам, рекомендуется использовать политику ServiceCallout. См. Политику Service Callout .
  • Для относительно простых взаимодействий с содержимым сообщений, таких как изменение или извлечение 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. В этом примере мы создадим простой прокси-объект с вызовом функции на 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 (необязательно)

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

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

    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.
  3. Сохраните файл setenv.sh .
  4. Выполните скрипт развертывания: 

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

    ./invoke.sh

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

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

    В результате возвращается сообщение "Привет, Уилл!".

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

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

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

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

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

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