Политика 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 обновления свойств организации, чтобы установить для флага 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">

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

Атрибут Описание По умолчанию Присутствие
name

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

При необходимости используйте элемент <DisplayName> , чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

Н/Д Необходимый
continueOnError

Установите значение false , чтобы возвращать ошибку в случае сбоя политики. Это ожидаемое поведение для большинства политик.

Установите значение true , чтобы выполнение потока продолжалось даже после сбоя политики.

ЛОЖЬ Необязательный
enabled

Установите значение true , чтобы обеспечить соблюдение политики.

Установите значение false , чтобы отключить политику. Политика не будет применена, даже если она останется привязанной к потоку.

истинный Необязательный
async

Этот атрибут устарел.

ЛОЖЬ Устарело

Элемент <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
По умолчанию

Н/Д

Если вы опустите этот элемент, будет использовано значение атрибута name политики.

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

Элемент <Действие>

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

<Action>action-exposed-by-extension</Action>
По умолчанию Никто
Присутствие Необходимый
Тип Нить

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

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

Элемент <Соединитель>

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

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

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

Содержимое <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>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 -->

По умолчанию Никто
Присутствие Необязательно или обязательно, в зависимости от расширения.
Тип Анализируемый объект или строка, в зависимости от настройки parsed атрибута.

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

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

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

<Выходные> Атрибуты

Атрибут Описание По умолчанию Присутствие
разобранный Анализирует объект JSON, возвращенный из расширения, что позволяет другим политикам получать доступ к данным в объекте JSON как к переменным. истинный Необязательный

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

Никто.

Коды ошибок

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

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

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

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

Название ошибки HTTP-статус Причина
Ошибка выполнения 500 Расширение отвечает ошибкой.

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

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

Название ошибки Происходит, когда Исправить
InvalidConnectorInstance Элемент <Connector> пуст.
ConnectorInstanceDoesNotExists Расширение, указанное в элементе <Connector> , не существует в среде.
InvalidAction Элемент <Action> в политике ExtensionCallout отсутствует или имеет пустое значение.
AllowExtensionsInPostClientFlow Запрещено иметь политику ExtensionCallout в PostClient Flow.