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

Muestras

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

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

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

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:

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>

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>

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>

Atributos

 <Copy source="response">

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.

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>

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.

Elemento <FaultResponse><AssignVariable>

Establece la información en el mensaje de error.

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

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>

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>

Atributos

 <Payload contentType="content_type" variablePrefix="char" variableSuffix="char">

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

Establece el código de estado de la respuesta.

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

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

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.

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>

<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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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