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

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

Элемент <ИмяКласса>

Указывает имя класса 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:

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

Упаковка

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

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