Политика 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 Community .

Ссылка на элемент

В справочнике элементов описаны элементы и атрибуты политики 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. Класс должен быть включен в 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> элемент

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

Этот файл можно сохранить в области действия API-прокси (в каталоге /apiproxy/resources/java в пакете API-прокси или в разделе Scripts панели Navigator редактора 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» .

Ограничения

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

  • Большинство системных вызовов запрещены. Например, вы не можете выполнять чтение или запись во внутреннюю файловую систему.
  • Доступ к сети осуществляется через сокеты. 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 не содержит фактического кода. Вместо этого политика вызова Java ссылается на «ресурс» Java и определяет шаг в потоке API, на котором выполняется код Java. Вы можете загрузить свой JAR-файл Java через редактор прокси-серверов в пользовательском интерфейсе управления или включить его в каталог /resources/java в прокси-серверы API, которые вы разрабатываете локально.
  • Для несложных операций, таких как вызовы API к удаленным сервисам, мы рекомендуем использовать политику ServiceCallout. См. Политику Service Callout .
  • Для относительно простых взаимодействий с содержимым сообщений, таких как изменение или извлечение HTTP-заголовков, параметров или содержимого сообщений, Apigee рекомендует использовать политику JavaScript.

Связанные темы