Política RaiseFault

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

Consulta la documentación de Apigee Edge.

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: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual	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

Predeterminada	N/A Si omites este elemento, se usa el valor del atributo `name` de la política.
Presencia	Opcional
Tipo	String

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.

El elemento <Header> admite la función de sustitución dinámica de string llamada plantillas de mensajes.

<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

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.

Los subelementos de <Set> admiten la función de Sustitución dinámica de strings llamada plantilla de mensajes.

    <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

Nota: Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

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