Вы просматриваете документацию 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 | Внутреннее имя политики. Значение атрибута При необходимости используйте элемент | Н/Д | Необходимый |
continueOnError | Установите значение Установите значение | ЛОЖЬ | Необязательный |
enabled | Установите значение Установите значение | истинный | Необязательный |
async | Этот атрибут устарел. | ЛОЖЬ | Устарело |
Элемент <DisplayName>
Используйте в дополнение к атрибуту name
, чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.
<DisplayName>Policy Display Name</DisplayName>
По умолчанию | Н/Д Если вы опустите этот элемент, будет использовано значение атрибута |
---|---|
Присутствие | Необязательный |
Тип | Нить |
Элемент <Действие>
Действие, предоставляемое расширением, которое должна вызывать политика.
<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> пуст. | build |
ConnectorInstanceDoesNotExists | Расширение, указанное в элементе <Connector> , не существует в среде. | build |
InvalidAction | Элемент <Action> в политике ExtensionCallout отсутствует или имеет пустое значение. | build |
AllowExtensionsInPostClientFlow | Запрещено иметь политику ExtensionCallout в PostClient Flow. | build |