Política de ExtensionExtensions

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

Usa la política de ExtensionCallout para incorporar una extensión en un proxy de API.

Una extensión proporciona acceso a un recurso específico externo a Apigee Edge. El recurso podría ser un servicio de Google Cloud Platform, como Cloud Storage o Cloud Speech-to-Text. Sin embargo, el recurso podría ser cualquier recurso externo al que se pueda acceder a través de HTTP o HTTPS.

Para obtener una descripción general de las extensiones, consulta ¿Qué son las extensiones? Si deseas ver un instructivo introductorio, consulta Instructivo: Cómo agregar y usar una extensión.

Antes de acceder a una extensión desde la política ExtensionCallout, debes agregar, configurar y, luego, realizar la implementación de la extensión desde un paquete de extensión que ya esté instalado en tu organización de Apigee Edge.

Ejemplos

A continuación, se muestra un ejemplo de política para usar con la extensión de 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>

Consulta el instructivo sobre el uso de extensiones para ver un instructivo completo sobre el uso de la extensión de Cloud Logging.

Para ver ejemplos de todas las extensiones disponibles, consulta la Descripción general de la referencia de extensiones.

Acerca de la política ExtensionCallout

Usa la política ExtensionCallout cuando quieras usar una extensión configurada para acceder a un recurso externo desde un proxy de API.

Antes de usar esta política, necesitarás lo siguiente:

• Son algunos detalles sobre el recurso externo al que deseas acceder desde esta política. Estos detalles serán específicos del recurso. Por ejemplo, si la política accederá a tu base de datos de Cloud Firestore, deberás conocer el nombre de la colección y el documento que deseas crear o a los que deseas acceder. Por lo general, usarás información específica del recurso para configurar el control de solicitudes y respuestas de esta política.
• Una extensión agregada, configurada y, luego, implementada en el entorno en el que se implementará tu proxy de API En otras palabras, si vas a usar esta política para acceder a un servicio específico de Google Cloud, debe existir en tu entorno una extensión implementada para ese servicio. Por lo general, los detalles de configuración incluyen la información necesaria para restringir el acceso al recurso, como un ID de proyecto o un nombre de cuenta.

Usa la política ExtensionCallout en un PostClientFlow

Puedes invocar la política ExtensionCallout desde el PostClientFlow de un proxy de API. El PostClientFlow se ejecuta después de que se envía la respuesta al cliente solicitante, lo que garantiza que todas las métricas estén disponibles para el registro. Para obtener detalles sobre el uso de PostClientFlow, consulta la Referencia de configuración del proxy de API.

Si deseas usar la política ExtensionCallout para llamar a la extensión de Google Cloud Logging desde un PostClientFlow, asegúrate de que la marca features.allowExtensionsInPostClientFlow esté establecida en true en tu organización.

• Si eres cliente de Apigee Edge para la nube pública, la marca features.allowExtensionsInPostClientFlow se establece en true de forma predeterminada.

• Si eres cliente de Apigee Edge para la nube privada, usa la API de Update organization properties para establecer la marca features.allowExtensionsInPostClientFlow en true.

Todas las restricciones para llamar a la política MessageLogging desde PostClientFlow también se aplican a la política ExtensionCallout. Consulta las notas de uso para obtener más información.

Referencia del elemento

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

Atributos de <ConnectorCallout>

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

En la siguiente tabla, se describen los atributos que son comunes a todos los elementos principales de las políticas:

Elemento <DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

<DisplayName>Policy Display Name</DisplayName>

Elemento <Action>

Es la acción expuesta por la extensión que debe invocar la política.

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

Cada extensión expone su propio conjunto de acciones que brindan acceso a la funcionalidad del recurso que representa la extensión. Puedes considerar una acción como una función a la que llamas con esta política, usando el contenido del elemento <Input> para especificar los argumentos de la función. La respuesta de la acción se almacena en la variable que especificas con el elemento <Output>.

Para obtener una lista de las funciones de la extensión, consulta la referencia de la extensión a la que llamas desde esta política.

Elemento <Connector>

Nombre de la extensión configurada que se usará. Es el nombre con alcance para el entorno que se le asignó a la extensión cuando se configuró para la implementación en un entorno.

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

Una extensión tiene valores de configuración que pueden diferir de otra extensión implementada basada en el mismo paquete de extensión. Estos valores de configuración pueden representar diferencias importantes en la funcionalidad del tiempo de ejecución entre las extensiones configuradas desde el mismo paquete, por lo que debes asegurarte de especificar la extensión correcta para invocar.

Elemento <Input>

Es un objeto JSON que contiene el cuerpo de la solicitud que se enviará a la extensión.

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

Básicamente, es un argumento para la acción que especificas con el elemento <Action>. El valor del elemento <Input> variará según la extensión y la acción que invoques. Consulta la documentación del paquete de extensión para obtener detalles sobre las propiedades de cada acción.

Ten en cuenta que, si bien muchos valores de elementos <Input> funcionarán correctamente sin estar incluidos como una sección <![CDATA[]]>, las reglas de JSON permiten valores que no se analizarán como XML. Como práctica recomendada, incluye el JSON como una sección CDATA para evitar errores de análisis en el tiempo de ejecución.

El valor del elemento <Input> es un JSON bien formado cuyas propiedades especifican los valores que se enviarán a la acción de extensión para invocarla. Por ejemplo, la acción log de la extensión Google Cloud Logging Extension toma valores que especifican el registro en el que se escribirá (logName), los metadatos que se incluirán con la entrada (metadata) y el mensaje de registro (data). A continuación, se muestra un ejemplo:

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

Usa variables de flujo en el JSON de <Input>

El contenido de <Input> se trata como una plantilla de mensaje. Esto significa que un nombre de variable entre llaves se reemplazará en el tiempo de ejecución por el valor de la variable a la que se hace referencia.

Por ejemplo, podrías reescribir el bloque <Input> anterior para usar la variable de flujo client.ip y obtener la dirección IP del cliente que llama al proxy de API:

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

Si deseas que el valor de una propiedad en el JSON se incluya entre comillas en el tiempo de ejecución, asegúrate de usar comillas en tu código JSON. Esto es así incluso cuando especificas una variable de flujo como un valor de propiedad JSON que se resolverá en el tiempo de ejecución.

El siguiente ejemplo de <Input> incluye dos referencias de variables de flujo:

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

En el tiempo de ejecución, los valores de las propiedades JSON se resolverán de la siguiente manera:

• Valor de la propiedad logName: El literal de cadena example-log.
• Valor de la propiedad metadata: Es el valor de la variable de flujo my.log.entry.metadata sin comillas de cierre. Esto puede ser útil si el valor de la variable es en sí mismo un JSON que representa un objeto.
• Valor de la propiedad message: El valor de la variable de flujo client.ip con comillas de cierre.

Elemento <Output>

Nombre de una variable que almacena la respuesta de la acción de extensión.

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

o

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

Cuando se recibe la respuesta, el valor de la respuesta se coloca en la variable que especificas aquí, desde donde puedes acceder a ella desde otro código del proxy de API.

Los objetos de respuesta de la extensión están en formato JSON. Existen dos opciones para controlar el JSON de la política:

• Analizado (predeterminado): La política analiza el objeto JSON y genera automáticamente variables con los datos JSON. Por ejemplo, si el JSON contiene "messageId" : 12345; y nombras tu variable de salida extensionOutput, puedes acceder a ese ID de mensaje en otras políticas con la variable {extensionOutput.messageId}.
• Sin analizar: La variable de salida contiene la respuesta JSON sin procesar y sin analizar de la extensión. (Si quisieras, podrías analizar el valor de la respuesta en un paso separado con la política de JavaScript).

Atributos <Output>

Variables de flujo

Ninguno

Códigos de error

Los errores que devuelven las políticas de Apigee Edge siguen un formato coherente, como se describe en la Referencia de errores de políticas.

En esta sección, se describen los mensajes de error y las variables de flujo que se establecen cuando esta política activa un error. Esta información es importante para saber si desarrolla reglas de fallas para un proxy. Para obtener más información, consulta Qué debes saber sobre los errores de las políticas y Cómo solucionar errores.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.