Política de ExtensionExtensions

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Utiliza la política ExtensionExtensions 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. Pero el recurso puede 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? Para obtener un instructivo introductorio, consulta Instructivo: Cómo agregar y usar una extensión.

Antes de acceder a una extensión desde la política ExtensionExtension, debes agregar, configurar y, luego, implementar la extensión desde un paquete de extensiones 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 Instructivo: Usa extensiones para obtener 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 las extensiones.

Acerca de la política ExtensionExtension

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

Antes de utilizar esta política, necesitarás 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 la base de datos de Cloud Firestore, deberás conocer el nombre de la colección y el documento al que quieres crear o acceder. Por lo general, usarás información específica del recurso para configurar la administración de respuestas y solicitudes de esta política.
  • Una extensión que se agregó, se configuró y se implementó en el entorno en el que se implementará el proxy de API. En otras palabras, si vas a usar esta política para acceder a un servicio de Google Cloud en particular, debes existir una extensión implementada para ese servicio en tu entorno. Por lo general, los detalles de configuración incluyen la información necesaria para limitar el acceso al recurso, como el ID del proyecto o el nombre de la cuenta.

Cómo usar la política ExtensionExtension en un PostClientFlow

Puedes invocar la política ExtensionExtensions 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 ExtensionExtension para llamar a la extensión de Google Cloud Logging desde un PostClientFlow, asegúrate de que la marca features.allowExtensionsInPostClientFlow esté configurada como true en tu organización.

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

  • Si eres cliente de Apigee Edge para nube privada, usa la API de Actualizar 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 el PostClientFlow también se aplican a la política de ExtensionExtension. Consulta 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 <ConnectorFeatured>

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

Atributo Descripción Predeterminada Presencia
name

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

No disponible Obligatorias
continueOnError

Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas.

Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle.

false Opcional
enabled

Configúralo como true para aplicar la política.

Configúralo como false para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.

true Opcional
async

Este atributo dejó de estar disponible.

false Funciones obsoletas

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

No disponible

Si omites este elemento, se usa el valor del atributo name de la política.

Presencia Opcional
Tipo Cadena

Elemento <Action>

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

<Action>action-exposed-by-extension</Action>
Predeterminada Ninguna
Presencia Obligatorias
Tipo Cadena

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

Elemento <Connector>

El nombre de la extensión configurada que se usará. Este es el nombre específico del entorno que se asignó a la extensión cuando se configuró para la implementación en un entorno.

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

Predeterminada Ninguna
Presencia Obligatorias
Tipo Cadena

Una extensión tiene valores de configuración que pueden diferir de otra extensión implementada según el mismo paquete de extensión. Estos valores de configuración pueden representar diferencias importantes en la funcionalidad del entorno de ejecución entre extensiones configuradas desde el mismo paquete, así que asegúrate de especificar la extensión correcta que se invocará.

Elemento <Input>

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

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

Predeterminada Ninguna
Presencia Opcional u obligatorio, según la extensión.
Tipo Cadena

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 estés invocando. Consulta la documentación del paquete de extensiones 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 delimitarse 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 del entorno 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, la acción log de la extensión de Google Cloud Logging toma valores que especifican el registro en el que se escribirá (logName), los metadatos que se incluirán en la entrada (metadata) y el mensaje de registro (data). Aquí 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 JSON <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, puedes volver a escribir el bloque <Input> anterior para usar la variable de flujo client.ip a fin de 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 quieres que un valor de propiedad en 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 que se resuelve en el tiempo 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 tiempo de ejecución, los valores de las propiedades JSON se resolverán de la siguiente manera:

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

Elemento <Output>

Es el nombre de una variable que almacena la respuesta de la acción de la 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 -->

Predeterminada Ninguna
Presencia Opcional u obligatorio, según la extensión.
Tipo Objeto o cadena analizado, según la configuración del atributo parsed.

Cuando se recibe la respuesta, el valor de respuesta se coloca en la variable que especificas aquí, en la que puedes acceder a ella desde otro código 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:

  • Analizado (predeterminado): La política analiza el objeto JSON y genera variables automáticamente con los datos de JSON. Por ejemplo, si JSON contiene "messageId" : 12345; y le asignas el nombre extensionOutput a la variable de salida, puedes acceder a ese ID del 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 lo deseas, puedes analizar el valor de respuesta en un paso separado mediante la política de JavaScript).

Atributos de <Output>

Atributo Descripción Predeterminada Presencia
analizado Analiza el objeto JSON que muestra la extensión, lo que permite que otras políticas accedan a los datos del objeto JSON como variables. true Opcional

Variables de flujo

Ningún contenido de este tipo

Códigos de error

Los errores que muestran 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.

Nombre del error Estado de HTTP Causa
ExecutionFailed 500 La extensión responde con un error.

Errores en la implementación

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

Nombre del error Ocurre cuando Corregir
InvalidConnectorInstance El elemento <Connector> está vacío.
ConnectorInstanceDoesNotExists La extensión especificada en el elemento <Connector> no existe en el entorno.
InvalidAction Falta el elemento <Action> en la política ExtensionExtension o se estableció en un valor vacío.
AllowExtensionsInPostClientFlow Se prohíbe tener la política ExtensionExtension en un flujo de PostClient.