Правило ExtensionCallout

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

Используйте правило ExtensionCallout, чтобы включить расширение в прокси-сервер API.

Расширение предоставляет доступ к определенному ресурсу, внешнему по отношению к Apigee Edge. Ресурсом могут быть сервисы Google Cloud Platform, например Cloud Storage или Cloud Speech-to-Text. Но ресурс может быть любым внешним ресурсом, доступным по протоколу HTTP или HTTPS.

Общую информацию о расширениях можно найти в статье Что такое расширение. Ознакомьтесь с руководством по добавлению и использованию расширений.

Прежде чем получить доступ к расширению из правила ExtensionCallout, необходимо добавить, настроить и развернуть расширение из пакета расширений, который уже установлен в организации Apigee Edge.

Примеры

Ниже приведен пример правил для использования с расширением Cloud Logging:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

Полное руководство по использованию расширения Cloud Logging приведено в разделе Учебник: использование расширений.

Примеры всех доступных расширений можно найти в обзоре справочной информации о расширениях.

Правило ExtensionCallout

Используйте правило ExtensionCallout, если вы хотите использовать настроенное расширение для доступа к внешнему ресурсу из прокси-сервера API.

Чтобы использовать это правило, вам потребуется:

• Несколько деталей о внешнем ресурсе, к которому вы хотите получить доступ из этого правила. Эти сведения относятся к определенному ресурсу. Например, если правило будет обращаться к базе данных Cloud Firestore, вам нужно будет знать название коллекции и документа, которые вы хотите создать или к которым хотите получить доступ. Как правило, при настройке обработки запросов и ответов для этого правила используется информация, относящаяся к определенному ресурсу.
• Расширение, добавленное, настроенное и развернутое в среде, в которой будет развернут прокси-сервер API. Другими словами, если вы собираетесь использовать это правило для доступа к определенному сервису Google Cloud, в вашей среде должно быть развернуто расширение для этого сервиса. Обычно в сведениях о конфигурации указывается информация, необходимая для ограничения доступа к ресурсу, например идентификатор проекта или название аккаунта.

Использование правила ExtensionCallout в PostClientFlow

Вы можете вызвать правило ExtensionCallout из PostClientFlow прокси-сервера API. Функция PostClientFlow выполняется после того, как ответ отправлен клиенту, запросившему его. Это гарантирует, что все показатели будут доступны для регистрации. Подробнее об использовании PostClientFlow можно узнать в справочнике по конфигурации прокси-сервера API.

Если вы хотите использовать правило ExtensionCallout, чтобы вызвать расширение Google Cloud Logging из PostClientFlow, убедитесь, что флаг features.allowExtensionsInPostClientFlow имеет значение true в вашей организации.

• Если вы используете Apigee Edge для общедоступного облака, флаг features.allowExtensionsInPostClientFlow по умолчанию имеет значение true.

• Если вы используете Apigee Edge для частного облака, воспользуйтесь API Update organization properties (Обновление свойств организации), чтобы задать для флага features.allowExtensionsInPostClientFlow значение true.

Все ограничения на вызов правил MessageLogging из PostClientFlow также применяются к правилам ExtensionCallout. Подробнее о примечаниях к использованию…

Сведения об элементах

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

Атрибуты <ConnectorCallout>

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

В следующей таблице описаны атрибуты, общие для всех родительских элементов политики:

Элемент <DisplayName>

Используйте в дополнение к атрибуту name , чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

<DisplayName>Policy Display Name</DisplayName>

Элемент <Action>

Действие, которое должно выполняться при срабатывании правила.

<Action>action-exposed-by-extension</Action>

Каждое расширение предоставляет свой набор действий, которые обеспечивают доступ к функциям ресурса, представленного расширением. Действие можно рассматривать как функцию, вызываемую с помощью этого правила. Содержимое элемента <Input> используется для указания аргументов функции. Ответ на действие сохраняется в переменной, указанной в элементе <Output>.

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

Элемент <Connector>

Название настроенного расширения, которое нужно использовать. Это название, присвоенное расширению при настройке развертывания в среде.

<Connector>name-of-configured-extension</Connector>

У расширения есть значения конфигурации, которые могут отличаться от значений другого развернутого расширения, созданного на основе того же пакета расширения. Эти значения конфигурации могут представлять важные различия в функциональности во время выполнения между расширениями, настроенными из одного и того же пакета, поэтому обязательно укажите правильное расширение для вызова.

Элемент <Input>

JSON, содержащий тело запроса, которое нужно отправить расширению.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

Это аргумент для действия, указанного в элементе <Action>. Значение элемента <Input> зависит от расширения и действия, которое вы вызываете. Подробную информацию о свойствах каждого действия можно найти в документации по пакету расширения.

Обратите внимание, что многие значения элемента <Input> будут работать правильно, даже если не заключены в раздел <![CDATA[]]>, но правила JSON допускают значения, которые не будут анализироваться как XML. Чтобы избежать ошибок при синтаксическом анализе во время выполнения, рекомендуется заключить JSON в раздел CDATA.

Значение элемента <Input> – это корректный код JSON, свойства которого задают значения, которые нужно отправить действию расширения для вызова. Например, действие log расширения для ведения журналов Google Cloud принимает значения, указывающие журнал, в который нужно записать данные (logName), метаданные, которые нужно включить в запись (metadata), и сообщение журнала (data). Вот пример:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

Как использовать переменные потока в JSON <Input>

Содержимое файла <Input> рассматривается как шаблон письма. Это означает, что название переменной, заключенное в фигурные скобки, во время выполнения будет заменено значением этой переменной.

Например, вы можете переписать приведенный выше блок <Input>, чтобы использовать переменную потока client.ip для получения IP-адреса клиента, вызывающего прокси-сервер API:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

Если вы хотите, чтобы значение ресурса в JSON было заключено в кавычки во время выполнения, обязательно используйте кавычки в коде JSON. Это верно, даже если вы укажете переменную потока в качестве значения свойства JSON, которое будет разрешено во время выполнения.

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

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

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

• Значение свойства logName – строковый литерал example-log.
• Значение свойства metadata – значение переменной потока my.log.entry.metadata без кавычек. Это может быть полезно, если значение переменной представляет собой объект JSON.
• Значение свойства message – значение переменной потока client.ip в кавычках.

Элемент <Output>

Название переменной, в которой хранится ответ действия расширения.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

или

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

Когда ответ получен, его значение помещается в указанную здесь переменную, к которой можно получить доступ из другого кода прокси API.

Объекты ответов расширения имеют формат JSON. Правило может обрабатывать JSON двумя способами:

• Проанализированный (по умолчанию). Политика анализирует объект JSON и автоматически создает переменные с данными JSON. Например, если в JSON есть "messageId" : 12345;, а выходная переменная называется extensionOutput, то в других правилах можно получить доступ к этому идентификатору сообщения, используя переменную {extensionOutput.messageId}.
• Необработанный. Выходная переменная содержит необработанный ответ JSON от расширения. (При желании вы можете проанализировать значение ответа на отдельном шаге, используя правило JavaScript.)

Атрибуты элемента <Output>

Переменные процесса

Нет.

Коды ошибок

Ошибки, возвращаемые правилами Apigee Edge, имеют единый формат, описанный в справочнике по ошибкам правил.

В этом разделе описываются сообщения об ошибках и переменные потока, которые устанавливаются, когда эта политика вызывает ошибку. Эту информацию важно знать, если вы разрабатываете правила отказа для прокси. Дополнительные сведения см. в разделах Что нужно знать об ошибках политик и Обработка ошибок .

Ошибки выполнения

Эти ошибки могут возникать при выполнении политики.

Ошибки развертывания

Эти ошибки могут возникать при развертывании прокси-сервера, содержащего эту политику.