Política RaiseFault

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

ícono de política

Qué

Genera un mensaje personalizado en respuesta a una condición de error. Usa RaiseFault para definir una respuesta ante errores que se muestra en la app solicitante cuando surge una condición específica.

Esta es una política estándar y se puede implementar en cualquier tipo de entorno. No todos los usuarios necesitan conocer los tipos de políticas y el entorno. Para obtener información sobre los tipos de políticas y la disponibilidad con cada tipo de entorno, consulta Tipos de políticas.

Para obtener información general sobre cómo manejar las fallas, consulta Controla errores.

Ejemplos

Muestra FaultResponse

RaiseFault se usa más comúnmente para mostrar una respuesta de falla personalizada a la app solicitante. Por ejemplo, esta política mostrará un código de estado 404 sin carga útil:

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
   </Set>
 </FaultResponse>
</RaiseFault>

Muestra la carga útil de FaultResponse

Un ejemplo más complejo implica mostrar una carga útil de respuesta personalizada ante errores, junto con encabezados HTTP y un código de estado HTTP. En el siguiente ejemplo, la respuesta de falla se propaga mediante un mensaje XML con el código de estado HTTP que recibió Apigee del servicio de backend y un encabezado que contiene el tipo de falla que se produjo:

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact support@company.com</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

A fin de obtener una lista de todas las variables disponibles para propagar mensajes de FaultResponse, consulta la referencia de variables.

Maneja errores de texto destacado de servicios


Acerca de la política de RaiseFault

Apigee te permite realizar un manejo de excepciones personalizado con una política de tipo RaiseFault. La política RaiseFault, que es similar a la política AssignMessage, te permite generar una respuesta de falla personalizada en respuesta a una condición de error.

Usa la política de RaiseFault para definir una respuesta con errores que se muestra en la app solicitante cuando surge una condición de error específica. La respuesta a errores puede consistir en encabezados HTTP, parámetros de consulta y una carga útil de mensaje. Una respuesta a errores personalizada puede ser más útil para los desarrolladores y usuarios finales de la app que los mensajes de error genéricos o los códigos de respuesta HTTP.

Cuando se ejecuta la política RaiseFault, esta transfiere el control desde el flujo actual hasta el flujo de error, el cual muestra la respuesta designada a la app cliente solicitante. Cuando el flujo de mensajes cambia al flujo de errores, no se produce ningún procesamiento de política adicional. Se omiten todos los pasos de procesamiento restantes y la respuesta de error se muestra directamente a la app solicitante.

Puedes usar RaiseFault en un ProxyEndpoint o un TargetEndpoint. Por lo general, debes adjuntar una condición a la política RaiseFault. Después de que se ejecuta RaiseFault, Apigee realizará el procesamiento de fallas normal, evaluará las FaultRules o, si no hay reglas de falla definidas, finalizará el procesamiento de la solicitud.

Referencia de elementos

En la referencia del elemento, se describen los elementos y atributos de la política RaiseFault.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
    <DisplayName>RaiseFault 1</DisplayName>
    <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

Atributos <RaiseFault>

<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">

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

Atributo Descripción Predeterminado 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.

N/A Obligatorio
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. También consulta lo siguiente:

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

falso Obsoleta

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

N/A

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

Presencia Opcional
Tipo String

Elemento <IgnoreUnresolvedVariables>

(Opcional) Ignora cualquier error de variable no resuelto en el flujo. Valores válidos: verdadero/falso true predeterminado.

Elemento <FaultResponse>

(Opcional) Define el mensaje de respuesta que se muestra al cliente solicitante. FaultResponse usa la misma configuración que la política de AssignMessage.

Elemento <FaultResponse><AssignVariable>

Asigna un valor a una variable de flujo de destino. Si la variable de flujo no existe, AssignVariable la crea.

Por ejemplo, usa el siguiente código para configurar la variable llamada myFaultVar en la política RaiseFault:

<FaultResponse>
  <AssignVariable>
    <Name>myFaultVar</Name>
    <Value>42</Value>
  </AssignVariable>
  ...
</FaultResponse>

Luego, puedes hacer referencia a esa variable en las plantillas de mensajes de la política RaiseFault. Además, una política adjunta a una FaultRule puede acceder a la variable. Por ejemplo, en la siguiente política AssignMessage, se usa la variable configurada en RaiseFault para configurar un encabezado en la respuesta ante fallas:

<AssignMessage enabled="true" name="Assign-Message-1">
  <Add>
    <Headers>
      <Header name="newvar">{myFaultVar}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

<AssignVariable> en la política RaiseFault usa la misma sintaxis que el elemento <AssignVariable> en la política AssignMessage.

Elemento <FaultResponse><Add>/<Headers>

Agrega encabezados HTTP al mensaje de error. Ten en cuenta que el encabezado vacío <Add><Headers/></Add> no agrega ningún encabezado. En este ejemplo, se copia el valor de la variable de flujo request.user.agent en el encabezado.

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

Predeterminado:

N/A

Presencia:

Opcional

Tipo:

String

Elemento <FaultResponse><AssignVariable>

Copia de la información desde el mensaje especificado por el atributo source en el mensaje de error.

    <Copy source="request">
        <Headers/>
        <StatusCode/>
    </Copy>

Predeterminado:

N/A

Presencia:

Opcional

Tipo:

String

Atributos

 <Copy source="response">
Atributo Descripción Presencia Tipo
origen

Especifica el objeto de origen de la copia.

  • Si source no se especifica, se lo trata como un mensaje simple. Por ejemplo, si la política está en el flujo de solicitud, la fuente predeterminada tiene como configuración el objeto request. Si la política está en el flujo de respuesta, su valor predeterminado es el objeto response. Si omites source, puedes usar una referencia absoluta a una variable de flujo como la fuente de la copia. Por ejemplo, especifica el valor como {request.header.user-agent}.
  • Si la variable de origen no se puede resolver o se resuelve en un tipo que no es de mensaje, <Copy> no responde.
Opcional String

Elemento <FaultResponse><Copy>/<ReasonPhrase>

Copia el encabezado HTTP especificado del origen al mensaje de error. Para copiar todos los encabezados, especifica <Copy><Headers/></Copy>..

<Copy source='request'>
    <Headers>
        <Header name="headerName"/>
    </Headers>
</Copy>

Si hay varios encabezados con el mismo nombre, usa la siguiente sintaxis:

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

En este ejemplo, se copia “h1”, “h2” y el segundo valor de “h3”. Si “h3” tiene solo un valor, no se copia.

Predeterminado:

N/A

Presencia:

Opcional

Tipo:

String

Elemento <FaultResponse><Copy>/<StatusCode>

El código de estado HTTP que se debe copiar desde el objeto que especifica el atributo fuente en el mensaje de error.

<Copy source='response'>
    <StatusCode>404</StatusCode>
</Copy>

Predeterminado:

falso

Presencia:

Opcional

Tipo:

String

Elemento <FaultResponse><Remove>/<Headers>

Quita los encabezados HTTP especificados del mensaje de error. Para quitar todos los encabezados, especifica <Remove><Headers/></Remove>. En este ejemplo, se quita el encabezado user-agent del mensaje.

<Remove>
    <Headers>
        <Header name="user-agent"/>
    </Headers>
</Remove>

Si hay varios encabezados con el mismo nombre, usa la siguiente sintaxis:

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

En este ejemplo, se quita “h1”, “h2” y el segundo valor de “h3”. Si “h3” tiene solo un valor, no se quita.

Predeterminado:

N/A

Presencia:

Opcional

Tipo:

String

Elemento <FaultResponse><AssignVariable>

Establece la información en el mensaje de error.

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
    </Set>

Predeterminado:

N/A

Presencia:

Opcional

Tipo:

N/A

Elemento <FaultResponse>/<Set>/<ReasonPhrase>

Establece o reemplaza encabezados de HTTP en el mensaje de error. Ten en cuenta que el encabezado vacío <Set><Headers/></Set> no establece ningún encabezado. En este ejemplo, se establece el encabezado user-agent en la variable de mensaje especificada con el elemento <AssignTo>.

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
</Set>

Predeterminado:

N/A

Presencia:

Opcional

Tipo:

String

Elemento <FaultResponse>/<Set>/<Payload>

Configura la carga útil del mensaje de error.

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

Configura una carga útil de JSON:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

En una carga útil JSON, puedes insertar variables mediante los atributos variablePrefix y variableSuffix con caracteres delimitadores, como se muestra en el siguiente ejemplo.

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

o, a partir de la versión 16.08.17 de la nube, también puedes utilizar las llaves para insertar variables:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

Configura una carga útil mixta en XML:

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

Predeterminado:

Presencia:

Opcional

Tipo:

String

Atributos

 <Payload contentType="content_type" variablePrefix="char" variableSuffix="char">
Atributo Descripción Presencia Tipo
contentType

Si se especifica contentType, su valor se asigna al encabezado Content-Type.

Opcional String
variablePrefix De forma opcional, se especifica el delimitador inicial en una variable de flujo, ya que las cargas útiles de JSON no pueden usar el carácter predeterminado “{”. Opcional Caracteres
variableSuffix De forma opcional, se especifica el delimitador final en una variable de flujo, ya que las cargas útiles de JSON no pueden usar el carácter predeterminado “}”. Opcional Caracteres

Elemento <FaultResponse>/<Set>/<ReasonPhrase>

Establece el código de estado de la respuesta.

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

Predeterminado:

falso

Presencia:

Opcional

Tipo:

Booleano

Elemento <ShortFaultReason>

Especifica para mostrar un motivo corto sobre falla en la respuesta:

<ShortFaultReason>true|false</ShortFaultReason>

De forma predeterminada, la razón de la falla en la respuesta de la política es la siguiente:

"fault":{"faultstring":"Raising fault. Fault name : Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

A fin de hacer que el mensaje sea más legible, puedes configurar el elemento <ShortFaultReason> como verdadero para acortar el faultstring a solo el nombre de la política:

"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

Valores válidos: true/false (predeterminado).

Predeterminado:

falso

Presencia:

Opcional

Tipo:

Booleano

Variables de flujo

Las variables de flujo habilitan el comportamiento dinámico de las políticas y los flujos en el entorno de ejecución, en función de los encabezados HTTP, el contenido de los mensajes o el contexto del flujo. Las siguientes variables predefinidas de flujo están disponibles después de que se ejecuta una RaiseFault. Para obtener más información sobre las variables de flujo, consulta Referencia de las variables.

Variable Tipo Permiso Descripción
fault.name String Solo lectura Cuando se ejecuta la política RaiseFault, esta variable siempre se establece en la string RaiseFault.
fault.type String Solo lectura Muestra el tipo de falla en el error y, si no está disponible, una string vacía.
fault.category String Solo lectura Muestra la categoría de falla en el error y, si no está disponible, una string vacía.

Ejemplo de uso de RaiseFault

En el siguiente ejemplo, se usa una condición para aplicar la presencia de un queryparam con el nombre zipcode en la solicitud entrante. Si queryparam no está presente, el flujo generará una falla a través de RaiseFault:

<Flow name="flow-1">
  <Request>
    <Step>
        <Name>RF-Error-MissingQueryParam</Name>
        <Condition>request.queryparam.zipcode = null</Condition>
    </Step>
   ...
   </Request>
   ...
   <Condition>(proxy.pathsuffix MatchesPath "/locations") and (request.verb = "GET")</Condition>
</Flow>
A continuación, se ilustra lo que tendría RaiseFault:
<RaiseFault name='RF-Error-MissingQueryParam'>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType='application/json'>{
  "error" : {
    "code" : 400.02,
    "message" : "invalid request. Pass a zipcode queryparam."
  }
}
</Payload>
      <StatusCode>400</StatusCode>
    </Set>
  </FaultResponse>
</RaiseFault>

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

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

Código de falla Estado de HTTP Causa
steps.raisefault.RaiseFault 500 Consulta la cadena de errores.

Errores en la implementación

Ninguno

Variables con fallas

Estas variables se configuran cuando se genera un error de entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables Donde Ejemplo
fault.name="fault_name" fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. fault.name = "RaiseFault"
raisefault.policy_name.failed policy_name es el nombre especificado por el usuario de la política que generó la falla. raisefault.RF-ThrowError.failed = true

Ejemplo de respuesta de error

{
   "fault":{
      "detail":{
         "errorcode":"steps.raisefault.RaiseFault"
      },
      "faultstring":"Raising fault. Fault name: [name]"
   }
}

Esquema

Un esquema XML (.xsd) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.

Temas relacionados

Consulta Controla errores