Política de ExtensionExtensions

Estás viendo la documentación de Apigee Edge.
Ve a la Documentación de Apigee X. información

Usa la política ExtensionLlamadas 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 servicios de Google Cloud Platform, como Cloud Storage o Cloud Speech-to-Text. Sin embargo, el recurso puede ser cualquier recurso externo accesible a través de HTTP o HTTPS.

Para obtener una descripción general de las extensiones, consulta ¿Qué son las extensiones? Para 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 ExtensionLlamadas, debes agregar, configurar e implementar 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 una política de ejemplo 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: Cómo usar extensiones para un instructivo completo con la extensión de Cloud Logging.

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

Acerca de la política Extension desafíos

Use la política ExtensionAviso para utilizar una extensión configurada para acceder a un recurso externo desde un proxy de API.

Antes de utilizar esta política, deberá contar con lo siguiente:

• 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 saber la colección y el nombre del documento que quieres crear o al que quieres acceder. Por lo general, usarás información específica del recurso en la configuración del manejo de solicitudes y respuestas de esta política.
• Una extensión se agregó, configuró e implementó. al entorno en el que se implementará el proxy de la API. En otras palabras, Si la usa para acceder a un servicio específico de Google Cloud entonces, debe existir en tu entorno una extensión implementada para ese servicio. Por lo general, los detalles de la configuración incluyen la información necesaria para delimitar al recurso, como un ID de proyecto o nombre de cuenta.

Cómo usar la política ExtensionCallout en un objeto PostClientFlow

Puedes invocar la política ExtensionReference desde el PostClientFlow de un proxy de API. 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 ExtensionReference para llamar a la extensión de Google Cloud Logging desde un PostClientFlow, asegúrate de que la marca features.allowExtensionsInPostClientFlow se estableció como 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 el Actualizar la API de propiedades de la organización para establecer la marca features.allowExtensionsInPostClientFlow en true.

Todas las restricciones para llamar a la política de MessageLogging desde PostClientFlow también se aplican a la política ExtensionAviso. 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>

<ConnectorCallout> atributos

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

&lt;Action&gt; elemento

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

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

Cada extensión expone su propio conjunto de acciones que proporcionan acceso a la funcionalidad del recurso que representa. Puedes pensar en una acción como una función a la que llamas con esta política. Usa 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 especifiques 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.

<Conector> elemento

Es el nombre de la extensión configurada que se usará. Este es el nombre con alcance de entorno que se asignó a la extensión cuando se configuró para su 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 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 extensiones configuradas desde el mismo paquete, así que asegúrate de especificar la extensión correcta que debes invocar.

&lt;Input&gt; elemento

JSON que contiene el cuerpo de la solicitud para enviar a la extensión.

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

En esencia, 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 los elementos <Input> funcionarán correctamente sin estar encerrados como una sección <![CDATA[]]>, las reglas de JSON permiten valores que no se analizarán como XML. Como práctica recomendada, delimita 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 con el formato correcto cuyas propiedades especifican valores. para enviar a la acción de extensión que se invocará. Por ejemplo, el Extensión de Google Cloud Logging la acción log de la extensión toma valores que especifican el registro en el que se escribirá (logName) metadatos para incluir con la entrada (metadata) y el mensaje de registro (data). A continuación, te mostramos un ejemplo:

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

Cómo usar variables de flujo en el JSON <Input>

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

Por ejemplo, puedes volver a escribir 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 un valor de propiedad en el JSON se encierre entre comillas durante 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 para resolver en el entorno de ejecución.

En el siguiente ejemplo de <Input>, se incluyen dos referencias de variables de flujo:

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

En el entorno de ejecución, los valores de propiedad JSON se resolverán de la siguiente manera:

• Valor de propiedad logName: el literal de string example-log.
• Valor de propiedad metadata: el valor de la variable de flujo my.log.entry.metadata sin comillas Esto puede ser útil si el valor de la variable es JSON y representa un objeto.
• Valor de propiedad message: el valor de la variable de flujo client.ip con comillas.

&lt;Output&gt; elemento

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 especifiques aquí, donde puedes acceder a ella desde otro código de proxy de API.

Los objetos de respuesta de extensión están en formato JSON. Existen dos opciones sobre cómo la política controla el JSON:

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

&lt;Output&gt; Atributos

Variables de flujo

Ninguno

Códigos de error

Los errores que muestran las políticas de Apigee Edge tienen un formato coherente, como se describe en la referencia de errores de política.

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.