Política RaiseFault

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

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.

Para obtener información general sobre el manejo de fallas, consulta Manejo de fallas.

Ejemplos

Muestra FaultResponse

En el uso más común, ElevateFault se usa para mostrar una respuesta de error 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>
     <ReasonPhrase>The resource requested was not found</ReasonPhrase>
   </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 ante fallas se propaga con un mensaje XML que contiene el código de estado HTTP que recibió Edge 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>
     <ReasonPhrase>Server error</ReasonPhrase>
   </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 Edge te permite realizar un control de excepciones personalizado con una política del tipo ledgeFault. La política ElevateFault, que es similar a la política deAssignMessage, 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/>
            <ReasonPhrase/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <ReasonPhrase/>
            <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 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 <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íticaAssignMessage (no está disponible en Apigee Edge para la nube privada).

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>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

<AssignVariable> en la política RaiseFault usa la misma sintaxis que el elemento <AssignVariable> en la política AssignMessage. Ten en cuenta que, por el momento, esta función no está disponible en Apigee Edge para la nube privada.

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:

No disponible

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/>
        <ReasonPhrase/>
    </Copy>

Predeterminado:

No disponible

Presencia:

Opcional

Tipo:

Cadena

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 Cadena

Elemento <FaultResponse><Copy>/<Headers>

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:

No disponible

Presencia:

Opcional

Tipo:

Cadena

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:

false

Presencia:

Opcional

Tipo:

Cadena

Elemento <FaultResponse><Copy>/<Reasonphrase>

La descripción del motivo para copiar desde el objeto especificado por el atributo de origen al mensaje de error.

<Copy source='response'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</Copy>

Predeterminado:

false

Presencia:

Opcional

Tipo:

Cadena

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:

No disponible

Presencia:

Opcional

Tipo:

String

Elemento <FaultResponse><AssignVariable>

Establece la información en el mensaje de error.

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

Predeterminado:

No disponible

Presencia:

Opcional

Tipo:

No disponible

Elemento <FaultResponse>/<Set>/<Headers>

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:

No disponible

Presencia:

Opcional

Tipo:

Cadena

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:

Cadena

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 Cadena
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>/<StatusCode>

Establece el código de estado de la respuesta.

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

Predeterminado:

false

Presencia:

Opcional

Tipo:

Booleano

Elemento <FaultResponse>/<Set>/<Reasonphrase>

Establece la frase de motivo de la respuesta.

<Set source='request'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Set>

Predeterminado:

false

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:

false

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 Permisos Descripción
fault.name Cadena Solo lectura Cuando se ejecuta la política RaiseFault, esta variable siempre se establece en la string RaiseFault.
fault.type Cadena 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 muestra lo que sería en ElevateFault:
<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>
      <ReasonPhrase>Bad Request</ReasonPhrase>
    </Set>
  </FaultResponse>
</RaiseFault>

Referencia de errores

En esta sección, se describen los códigos y mensajes de error que se muestran, así como las variables de fallas que establece Edge 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 que especifica el usuario de la política que produjo 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