Политика ExtensionCallout

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

Используйте политику 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 for Public Cloud, флаг features.allowExtensionsInPostClientFlow по умолчанию установлен в true .

• Если вы являетесь клиентом Apigee Edge for Private Cloud, используйте API обновления свойств организации , чтобы установить флаг 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-exposed-by-extension</Action>

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

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

элемент <Connector>

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

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

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

<Ввод> элемент

JSON-объект, содержащий тело запроса для отправки расширению.

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

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

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

Значение элемента <Input> представляет собой корректно сформированный JSON, свойства которого определяют значения, которые необходимо отправить в действие расширения для вызова. Например, действие log расширения Google Cloud Logging Extension принимает значения, указывающие, в какой журнал записывать данные ( 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> таким образом, чтобы для получения IP-адреса клиента, вызывающего API-прокси, использовалась переменная потока client.ip :

<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>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 .)

<Вывод> Атрибуты

Переменные потока

Никто.

коды ошибок

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

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

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

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

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

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