Программирование API-прокси с помощью JavaScript

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

В этом разделе вы узнаете, как использовать JavaScript для динамического добавления HTTP-заголовков в ответное сообщение, а также как анализировать ответ JSON и возвращать подмножество его свойств запрашивающему приложению.

Загрузите и опробуйте пример кода

Об этом примере кулинарной книги

Этот пример кулинарной книги иллюстрирует шаблон API-прокси, в котором вы реализуете поведение API в JavaScript. Примеры JavaScript предназначены для того, чтобы показать вам, как работать с простыми переменными и содержимым сообщений. В одном примере показано, как получать и устанавливать переменные. Во втором примере показано, как анализировать JSON и на основе результата создавать сообщение.

В прокси-сервере API находятся два примера JavaScript:

  • setHeaders.js : этот JavaScript получает значения нескольких переменных, которые устанавливаются при вызове прокси-сервера API. JavaScript добавляет эти переменные в ответное сообщение, чтобы вы могли видеть их значения для каждого вашего запроса.
  • minimize.js : этот JavaScript показывает, как работать с содержимым сообщения. Идея этого примера заключается в том, что служба часто возвращает больше данных, чем необходимо. Итак, JavaScript анализирует ответное сообщение, извлекает несколько интересных свойств, а затем использует их для построения содержимого ответного сообщения.

Код для setHeader.js :

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

Код для minimize.js :

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

Вы можете получить доступ к переменным потока в JavaScript через объект контекста. Этот объект является частью объектной модели Edge JavaScript. Подробные сведения об объектной модели см. в разделе Объектная модель JavaScript .

Прежде чем начать

Прежде чем приступить к изучению примера кулинарной книги, вы также должны быть знакомы со следующими фундаментальными понятиями:

  • Что такое политики и как их привязать к прокси. Хорошее введение в политики см. в разделе Что такое политика? .
  • Структура потока прокси, как описано в разделе «Настройка потоков» . Потоки позволяют указать последовательность выполнения политик прокси-сервером API. В этом примере создается несколько политик и добавляется в поток прокси-сервера API.
  • Как проект прокси-сервера API организован в вашей файловой системе, как описано в справочнике по настройке прокси-сервера API .
  • Практические знания XML, JSON и JavaScript. В этом примере вы создаете прокси-сервер API и его политики с помощью XML-файлов, находящихся в файловой системе.

Если вы загрузили пример кода, вы можете найти все файлы, обсуждаемые в этом разделе, в папке примеров javascript-cookbook . В следующих разделах подробно обсуждается пример кода.

Понимание потока прокси

Чтобы заставить JavaScript выполняться в прокси-сервере API, вам необходимо присоединить его к потоку с помощью вложения политики, называемого «Шаг». Политика типа Javascript (с заглавными буквами) просто содержит ссылку на имя файла JavaScript. Вы указываете политику на файл JavaScript с помощью элемента ResourceURL.

Например, следующая политика ссылается на файл JavaScript с именем setHeader.js .

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

Вы можете прикрепить эту политику к потоку прокси-сервера API, как и любой другой тип политики. Прикрепляя политику к потоку прокси-сервера API, вы указываете, где должен выполняться JavaScript. Это позволяет вам выполнять JavaScript, который взаимодействует с сообщениями запроса или ответным сообщением, когда эти сообщения «проходят» через прокси-сервер API. В этом примере оба сценария JavaScript выполняются в потоке ответа, поскольку политики выполняют две задачи: устанавливают заголовки HTTP в ответном сообщении и «минимизируют» ответное сообщение, которое Apigee Edge возвращает запрашивающему приложению.

Если вы откроете эту конфигурацию потока в пользовательском интерфейсе управления, вы увидите конфигурацию потока ниже.

Выберите Конечные точки прокси-сервера > по умолчанию > PostFlow на панели Навигатор .

Соответствующая конфигурация XML для ProxyEndpoint с именем «default» показана ниже.

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Вот краткое изложение элементов потока.

  • <Request> — элемент <Request> состоит из нескольких элементов <Step>. Каждый шаг вызывает одну из политик, которые вы создадите в оставшейся части этого раздела. Эти политики прикрепляют JavaScript к потоку прокси-сервера API, а расположение вложения политики определяет, когда будет выполняться JavaScript.
  • <Response> — элемент <Response> также включает <Steps>. Эти шаги также вызывают политики, которые отвечают за обработку окончательного ответа от цели (которой в этом примере является цель ложной службы Apigee — обратите внимание на настройку HTTPTargetConnection в /apiproxy/targets/default.xml ).
  • <HTTPProxyConnection> — указывает хост и путь URI, определяющие сетевой адрес, который приложения вызывают для использования этого API.
  • <RouteRule> — этот элемент указывает, какая конфигурация TargetEndpoint вызывается ProxyEndpoint.

Добавление кода JavaScript в прокси

JavaScript (например, сценарии Python, файлы Java JAR, файлы XSLT и т. д.) хранятся как ресурсы . Когда вы только начинаете работать с JavaScript, проще всего хранить файлы JavaScript в прокси-сервере API. По мере продвижения JavaScript должен быть максимально универсальным и пригодным для повторного использования, а затем храниться на уровне среды или организации . Это избавляет вас от необходимости хранить одни и те же файлы JavaScript в нескольких прокси-серверах API, что может быстро стать неуправляемым.

Дополнительные сведения о хранении ресурсов на уровне организации и среды см. в разделе Файлы ресурсов .

Попробуйте это

Инструкции по развертыванию и вызову прокси см. в кулинарной книге JavaScript README .

Импорт и развертывание прокси API

После внесения изменений вы можете сохранить прокси-сервер API в инструменте создания прокси-серверов API в пользовательском интерфейсе управления .

Или вы можете запустить следующую команду в каталоге /api-platform-samples/doc-samples/javascript-cookbook . 

$ sh deploy.sh

Тестирование JavaScript

Выполните следующую команду в каталоге /api-platform-samples/doc-samples/javascript-cookbook .

$ sh invoke.sh

Флаг Curl -v используется в сценарии оболочки для просмотра заголовков HTTP в ответном сообщении, измененном JavaScript.

Вы можете напрямую отправить запрос следующим образом:

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook

Если JavaScript выполняется правильно, вы увидите ответ, подобный следующему:

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

Теперь вы можете изменить JavaScript, чтобы попробовать что-то новое, повторно развернуть прокси-сервер API и проверить результаты, отправив тот же запрос. Всегда убедитесь, что вы развернули прокси-сервер API, содержащий ваш JavaScript, чтобы ваши изменения вступили в силу.

Ошибки скрипта

Вы неизбежно увидите ошибки при написании JavaScript. Формат ошибок JavaScript, которые вы увидите, выдаваемых прокси-сервером API, показан ниже. 

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

Когда использовать JavaScript

В Apigee Edge обычно существует несколько способов реализации определенных функций. По возможности используйте готовые политики и избегайте соблазна закодировать всю логику прокси-сервера API на JavaScript. Несмотря на то, что Apigee Edge использует скомпилированный JavaScript для повышения производительности, маловероятно, что JavaScript будет работать так же хорошо, как политики. JavaScript может быть сложнее поддерживать и отлаживать. Зарезервируйте JavaScript для функций, которые соответствуют вашим требованиям.

Если производительность является проблемой для пользовательских функций, используйте Java, где это возможно.

Краткое содержание

В этом разделе кулинарной книги вы узнали, как JavaScript можно включить в конфигурацию прокси-сервера API для реализации пользовательского поведения. Пользовательское поведение, реализованное в примерах, демонстрирует, как получать переменные, а также анализировать JSON и создавать собственные ответные сообщения.