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

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

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые устанавливаются 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 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.

Похожие темы