Правило JavaCallout

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

Что

Позволяет использовать Java для реализации специального поведения, которое не предусмотрено правилами Apigee. В коде Java можно получить доступ к свойствам сообщения (заголовкам, параметрам запроса, контенту) и переменным потока в прокси-потоке. Если вы только начинаете работать с этим правилом, ознакомьтесь с информацией о том, как создать вызов Java.

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

Когда

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

Обзор

Правило Java Callout позволяет получать и задавать переменные потока, выполнять пользовательскую логику и обработку ошибок, извлекать данные из запросов или ответов и т. д. Это правило позволяет реализовать специальное поведение, не предусмотренное другими стандартными правилами Edge.

Вы можете упаковать приложение Java с любыми нужными JAR-файлами. Обратите внимание, что при использовании Java Callout действуют некоторые ограничения. Они перечислены ниже в разделе Ограничения.

Примеры

Простой пример

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

Как получить свойства в коде Java

Элемент <Property> позволяет указать пару "название-значение", которую можно получить во время выполнения в коде Java. Пример использования свойств можно найти в статье Как использовать свойства в выноске Java.

Используйте атрибут name элемента <Property>, чтобы указать имя, с помощью которого можно будет получить доступ к свойству из кода Java. Значение элемента <Property> (значение между открывающим и закрывающим тегами) – это значение, которое получит код Java. Значение должно быть строкой. Ссылаться на переменную потока, чтобы получить значение, нельзя.

  • Настройте ресурс. В этом случае значением свойства будет название переменной response.status.code. 
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
    <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
    <Properties>
        <Property name="source">response.status.code</Property>
    </Properties>
</Javascript>
  • В коде Java реализуйте следующий конструктор в классе Execution:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

            // Extract property values from map.
    }
    ...
}

Как задать переменные потока в коде Java

Подробное описание того, как задавать переменные в контексте сообщения (переменные потока) в коде Java, приведено в сообщении сообщества Apigee.

Сведения об элементах

В справочнике по элементам описаны элементы и атрибуты правила JavaCallout.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

Атрибуты <JavaCallout>

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

В следующей таблице описаны атрибуты, общие для всех родительских элементов политики:

Атрибут Описание По умолчанию Присутствие
name

Внутреннее имя политики. Значение атрибута name может содержать буквы, цифры, пробелы, дефисы, подчеркивания и точки. Это значение не может превышать 255 символов.

При необходимости используйте элемент <DisplayName> , чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

 Н/Д Необходимый
continueOnError

Установите значение false , чтобы возвращать ошибку в случае сбоя политики. Это ожидаемое поведение для большинства политик.

Установите значение true , чтобы выполнение потока продолжалось даже после сбоя политики.

 ЛОЖЬ Необязательный
enabled

Установите значение true , чтобы обеспечить соблюдение политики.

Установите значение false , чтобы отключить политику. Политика не будет применена, даже если она останется привязанной к потоку.

 истинный Необязательный
async

Этот атрибут устарел.

 ЛОЖЬ Устарело

Элемент <DisplayName>

Используйте в дополнение к атрибуту name , чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

<DisplayName>Policy Display Name</DisplayName>
По умолчанию

Н/Д

Если вы опустите этот элемент, будет использовано значение атрибута name политики.

Присутствие Необязательный
Тип Нить

Элемент <ClassName>

Указывает название класса Java, который выполняется при запуске правила Java Callout. Класс должен быть включен в JAR-файл, указанный в <ResourceURL>. Также ознакомьтесь со статьей Как создать вызов Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
По умолчанию: Н/Д
Присутствие Обязательно
Тип: Строка

Элемент <Property>

Указывает свойство, к которому можно получить доступ из кода Java во время выполнения. Для каждого свойства необходимо указать строковое значение. Ссылаться на переменные потока в этом элементе нельзя. Рабочий пример использования свойств можно найти в статье Как использовать свойства в выноске Java.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
По умолчанию: Нет
Присутствие Необязательно
Тип: Строка

Атрибуты

Атрибут Описание По умолчанию Тип поля
name

Указывает название ресурса.

 Н/Д Обязательно.

Элемент<ResourceURL>

Этот элемент указывает на JAR-файл Java, который будет выполняться при запуске правила вызова Java.

Вы можете сохранить этот файл в области действия прокси-сервера API (в разделе /apiproxy/resources/java в пакете прокси-сервера API или в разделе "Скрипты" на панели навигации редактора прокси-сервера API) или в области действия организации или среды для повторного использования в нескольких прокси-серверах API, как описано в разделе Файлы ресурсов.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
По умолчанию: Нет
Присутствие Обязательно
Тип: Строка

Справочник по ошибкам

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые устанавливаются Edge, когда эта политика вызывает ошибку. Эту информацию важно знать, если вы разрабатываете правила обработки ошибок. Дополнительные сведения см. в разделах Что нужно знать об ошибках политики и Обработка ошибок .

Ошибки выполнения

Эти ошибки могут возникнуть при выполнении политики.

Код неисправности Статус HTTP Причина Исправить
steps.javacallout.ExecutionError 500 Происходит, когда код Java генерирует исключение или возвращает значение NULL во время выполнения политики JavaCallout.

Ошибки развертывания

Эти ошибки могут возникнуть при развертывании прокси-сервера, содержащего политику.

Название ошибки Строка неисправности Статус HTTP Происходит, когда
ResourceDoesNotExistResource with name [name] and type [type] does not exist Н/Д Файл, указанный в элементе <ResourceURL> , не существует.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] Н/Д Файл класса, указанный в элементе <ClassName> отсутствует в банке.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] Н/Д См. строку ошибки. См. также Поддерживаемое программное обеспечение и поддерживаемые версии .
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] Н/Д См. строку ошибки.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] Н/Д См. строку ошибки.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] Н/Д См. строку ошибки.
NoResourceForURL Could not locate a resource with URL [string] Н/Д См. строку ошибки.

Переменные неисправности

Эти переменные устанавливаются, когда эта политика вызывает ошибку. Дополнительные сведения см. в разделе Что нужно знать об ошибках политики .

Переменные Где Пример
fault.name=" fault_name " fault_name — это имя ошибки, как указано в таблице ошибок времени выполнения выше. Имя неисправности — это последняя часть кода неисправности. fault.name Matches "ExecutionError"
javacallout. policy_name .failed policy_name — указанное пользователем имя политики, вызвавшей ошибку. javacallout.JC-GetUserData.failed = true

Пример ответа об ошибке 

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

Пример правила неисправности 

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

Схемы

Компиляция и развертывание

Подробнее о том, как создать вызов Java…

Ограничения

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

  • Большинство системных вызовов запрещено. Например, вы не можете читать или записывать данные во внутреннюю файловую систему.
  • Доступ к сети через сокеты. Apigee ограничивает доступ к адресам sitelocal, anylocal, loopback и linklocal.
  • Выноска не может получить информацию о текущем процессе, списке процессов или использовании ЦП/памяти на компьютере. Хотя некоторые из таких звонков могут работать, они не поддерживаются и могут быть отключены в любой момент. Чтобы обеспечить совместимость с будущими версиями, не используйте такие вызовы в коде.
  • Использование библиотек Java, включенных в Apigee Edge, не поддерживается. Эти библиотеки предназначены только для функций продукта Edge, и нет гарантии, что они будут доступны в каждом выпуске.
  • Не используйте io.apigee или com.apigee в качестве названий пакетов в выносках Java. Эти названия зарезервированы и используются другими модулями Apigee.

Упаковка

Поместите JAR-файл в прокси-сервер API в папку /resources/java. Если ваш вызов Java зависит от дополнительных сторонних библиотек, упакованных в отдельные JAR-файлы, поместите эти JAR-файлы в каталог /resources/java, чтобы они правильно загружались во время выполнения.

Если вы создаете или изменяете прокси-сервер с помощью интерфейса управления, добавьте новый ресурс и укажите дополнительный зависимый JAR-файл. Если файлов JAR несколько, просто добавьте их как дополнительные ресурсы. Вам не нужно изменять конфигурацию правил, чтобы ссылаться на дополнительные JAR-файлы. Достаточно указать их в /resources/java.

Информацию о загрузке JAR-файлов Java можно найти в разделе Файлы ресурсов.

Подробный пример того, как упаковать и развернуть объект уточнения Java с помощью Maven или javac, приведен в статье Как создать объект уточнения Java.

Javadoc

Документация Javadoc по написанию кода Java Callout приведена на GitHub. Вам нужно будет клонировать или скачать HTML-код на устройство, а затем открыть файл index.html в браузере.

Примечания

  • Правило Java Callout не содержит кода. Вместо этого правило Java Callout ссылается на ресурс Java и определяет шаг в потоке API, на котором выполняется код Java. Вы можете загрузить JAR-файл Java через редактор прокси-сервера в интерфейсе управления или добавить его в каталог /resources/java в прокси-серверах API, которые вы разрабатываете локально.
  • Для простых операций, таких как вызовы API к удаленным сервисам, мы рекомендуем использовать правило ServiceCallout. Ознакомьтесь с правилами в отношении описаний услуг.
  • Для относительно простых взаимодействий с контентом сообщений, например для изменения или извлечения HTTP-заголовков, параметров или контента сообщений, Apigee рекомендует использовать правила JavaScript.

Статьи по теме