Политика JavaCallout

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

Что

Позволяет использовать 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>
По умолчанию: Н/Д
Присутствие: Необходимый
Тип: Нить

Элемент <Свойства>

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

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

Атрибуты

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

Указывает имя свойства.

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

Элемент <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>
По умолчанию: Никто
Присутствие: Необходимый
Тип: Нить

Ссылка на ошибку

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.javacallout.ExecutionError 500 Occurs when Java code throws an exception or returns null during the execution of a JavaCallout policy.

Deployment errors

These errors can occur when the proxy containing the policy is deployed.

Error name Fault string HTTP status Occurs when
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A The file specified in the <ResourceURL> element does not exist.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A The class file specified in the <ClassName> element is not in the jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A See fault string. See also Supported software and supported versions.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A See fault string.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A See fault string.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A See fault string.
NoResourceForURL Could not locate a resource with URL [string] N/A See fault string.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javacallout.JC-GetUserData.failed = true

Example error response

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

Example fault rule

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

Схемы

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

Подробную информацию о том, как скомпилировать пользовательский код Java и развернуть его с помощью прокси-сервера, см. в разделе Создание выноски Java .

Ограничения

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

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

Упаковка

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

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

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

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

Javadoc

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

Заметки об использовании

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

Похожие темы