Esta página se ha traducido con Cloud Translation API.

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 de error que se devuelva a la aplicación que realiza la solicitud cuando se dé una condición específica.

Esta política 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 de cada tipo de entorno, consulta Tipos de políticas.

Para obtener información general sobre cómo gestionar los errores, consulta el artículo Gestión de errores.

Ejemplos

Devuelve FaultResponse

En el uso más habitual, RaiseFault se utiliza para devolver una respuesta de error personalizada a la aplicación que hace la solicitud. Por ejemplo, esta política devolverá un código de estado 404 sin carga útil:

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

Devuelve la carga útil FaultResponse

Un ejemplo más complejo consiste en devolver una carga útil de respuesta de error personalizada, junto con encabezados HTTP y un código de estado HTTP. En el siguiente ejemplo, la respuesta de error se rellena con un mensaje XML que contiene el código de estado HTTP recibido por Apigee del servicio backend y una cabecera que contiene el tipo de error que se ha producido:

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

Para ver una lista de todas las variables que se pueden usar para rellenar dinámicamente los mensajes FaultResponse, consulta la referencia de variables.

Gestionar errores de llamadas de servicio

Acerca de la política RaiseFault

Apigee te permite gestionar excepciones personalizadas mediante una política de tipo RaiseFault. La política RaiseFault, que es similar a la política AssignMessage, te permite generar una respuesta de error personalizada en respuesta a una condición de error.

Usa la política RaiseFault para definir una respuesta de error que se devuelva a la aplicación que realiza la solicitud cuando se produzca un error específico. La respuesta de error puede constar de encabezados HTTP, parámetros de consulta y una carga útil de mensaje. Una respuesta de error personalizada puede ser más útil para los desarrolladores de aplicaciones y los usuarios finales de aplicaciones que los mensajes de error genéricos o los códigos de respuesta HTTP.

Cuando se ejecuta, la política RaiseFault transfiere el control del flujo actual al flujo Error, que devuelve la respuesta de error designada a la aplicación cliente solicitante. Cuando el flujo de mensajes cambia al flujo Error, no se produce ningún otro procesamiento de políticas. Se omiten todos los pasos de procesamiento restantes y la respuesta de error se devuelve directamente a la aplicación que ha enviado la solicitud.

Puede usar RaiseFault en un ProxyEndpoint o un TargetEndpoint. Normalmente, se adjunta una condición a la política RaiseFault. Después de que se ejecute RaiseFault, Apigee realizará el procesamiento de errores normal, evaluará las FaultRules o, si no hay ninguna definida, finalizará el procesamiento de la solicitud.

Referencia de elemento

En la referencia de elementos 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 de <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 superiores de la política:

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. Opcionalmente, usa el elemento `<DisplayName>` para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.	N/A	Obligatorio
`continueOnError`	Asigna el valor `false` para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor `true` para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también: Las reglas de errores solo se activan cuando hay un error (sobre continueOnError) Gestionar fallos en el flujo actual	falso	Opcional
`enabled`	Asigna el valor `true` para aplicar la política. Selecciona `false` para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.	true	Opcional
`async`	Este atributo está obsoleto.	falso	Obsoleto

Elemento <DisplayName>

Úsalo junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

<DisplayName>Policy Display Name</DisplayName>

Predeterminado

Predeterminado	N/A Si omite este elemento, se usará el valor del atributo `name` de la política.
Presencia	Opcional
Tipo	Cadena

N/A

Si omite este elemento, se usará el valor del atributo name de la política.

Presencia Opcional

Tipo Cadena

Elemento <IgnoreUnresolvedVariables>

(Opcional) Ignora cualquier error de variable sin resolver en el flujo. Valores válidos: true o false. true predeterminado.

Elemento <FaultResponse>

(Opcional) Define el mensaje de respuesta que se devuelve al cliente que realiza la solicitud. FaultResponse usa los mismos ajustes que la política 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 definir la variable llamada myFaultVar en la política RaiseFault:

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

Después, puedes hacer referencia a esa variable en las plantillas de mensajes más adelante en la política RaiseFault. Además, una política asociada a un elemento FaultRule puede acceder a la variable. Por ejemplo, la siguiente política AssignMessage usa la variable definida en RaiseFault para definir un encabezado en la respuesta de error:

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

Añade encabezados HTTP al mensaje de error. Ten en cuenta que el encabezado vacío <Add><Headers/></Add> no añade 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 de cadenas dinámicas llamada plantillas de mensajes.

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

Valor predeterminado:	N/A
Presencia:	Opcional
Tipo:	Cadena

Elemento <FaultResponse><Copy>

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

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

Valor predeterminado:	N/A
Presencia:	Opcional
Tipo:	Cadena

Atributos

 <Copy source="response">

Atributo	Descripción	Presencia	Tipo
fuente	Especifica el objeto de origen de la copia. Si no se especifica source, se trata como un mensaje simple. Por ejemplo, si la política está en el flujo de solicitud, la fuente se asigna de forma predeterminada al objeto request. Si la política se encuentra en el flujo de respuesta, se asigna de forma predeterminada al objeto response. Si omite source, puede usar una referencia absoluta a una variable de flujo como origen de la copia. Por ejemplo, especifique el valor {request.header.user-agent}. Si no se puede resolver la variable de origen o se resuelve en un tipo que no es de mensaje, se produce un error en <Copy>.	Opcional	Cadena

Atributo

Descripción

Presencia

Tipo

fuente

Especifica el objeto de origen de la copia.

Si no se especifica source, se trata como un mensaje simple. Por ejemplo, si la política está en el flujo de solicitud, la fuente se asigna de forma predeterminada al objeto request. Si la política se encuentra en el flujo de respuesta, se asigna de forma predeterminada al objeto response. Si omite source, puede usar una referencia absoluta a una variable de flujo como origen de la copia. Por ejemplo, especifique el valor {request.header.user-agent}.
Si no se puede resolver la variable de origen o se resuelve en un tipo que no es de mensaje, se produce un error en <Copy>.

Opcional

Cadena

Elemento <FaultResponse><Copy>/<Headers>

Copia el encabezado HTTP especificado de la fuente 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, utiliza la siguiente sintaxis:

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

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

Valor predeterminado:	N/A
Presencia:	Opcional
Tipo:	Cadena

Elemento <FaultResponse><Copy>/<StatusCode>

El código de estado HTTP que se va a copiar del objeto especificado por el atributo de origen al mensaje de error.

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

Valor predeterminado:	falso
Presencia:	Opcional
Tipo:	Cadena

Elemento <FaultResponse><Remove>/<Headers>

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

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

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

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

En este ejemplo, se eliminan "h1", "h2" y el segundo valor de "h3". Si "h3" solo tiene un valor, no se elimina.

Valor predeterminado:	N/A
Presencia:	Opcional
Tipo:	Cadena

Elemento <FaultResponse><Set>

Define la información del mensaje de error.

Los subelementos de <Set> admiten la función de sustitución de cadenas dinámicas llamada plantillas de mensajes.

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

Valor predeterminado:	N/A
Presencia:	Opcional
Tipo:	N/A

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

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

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

Valor predeterminado:	N/A
Presencia:	Opcional
Tipo:	Cadena

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

Define la carga útil del mensaje de error.

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

Define 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, tal como se muestra en el siguiente ejemplo.

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

o bien, desde la versión 16.08.17 de la nube, puedes usar llaves para insertar variables:

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

Definir una carga útil mixta en XML:

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

Valor 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	Especifica de forma opcional el delimitador inicial de una variable de flujo, ya que las cargas útiles JSON no pueden usar el carácter predeterminado "{".	Opcional	Char
variableSuffix	Especifica de forma opcional el delimitador final de una variable de flujo, ya que las cargas útiles JSON no pueden usar el carácter "}" predeterminado.	Opcional	Char

Elemento <FaultResponse>/<Set>/<StatusCode>

Asigna el código de estado de la respuesta.

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

Valor predeterminado:	falso
Presencia:	Opcional
Tipo:	Booleano

Elemento <ShortFaultReason>

Especifica que se muestre un breve motivo del error en la respuesta:

<ShortFaultReason>true|false</ShortFaultReason>

De forma predeterminada, el motivo del error en la respuesta de la política es el siguiente:

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

Para que el mensaje sea más legible, puedes asignar el valor true al elemento <ShortFaultReason> para acortar el faultstring y que solo se muestre el nombre de la política:

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

Valores válidos: true o false(valor predeterminado).

Valor predeterminado:	falso
Presencia:	Opcional
Tipo:	Booleano

Variables de flujo

Las variables de flujo permiten que las políticas y los flujos tengan un comportamiento dinámico en el tiempo de ejecución, en función de los encabezados HTTP, el contenido de los mensajes o el contexto del flujo. Las siguientes variables de flujo predefinidas están disponibles después de que se ejecute una política RaiseFault. Para obtener más información sobre las variables de flujo, consulta la referencia de variables.

Variable	Tipo	Permiso	Descripción
fault.name	Cadena	Solo lectura	Cuando se ejecuta la política RaiseFault, esta variable siempre se asigna a la cadena `RaiseFault`.
fault.type	Cadena	Solo lectura	Devuelve el tipo de fallo en el error y, si no está disponible, una cadena vacía.
fault.category	Cadena	Solo lectura	Devuelve la categoría de error en el error y, si no está disponible, una cadena vacía.

Ejemplo de uso de RaiseFault

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

<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 habría en 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 error y los mensajes de error que se devuelven, así como las variables de error que define Apigee cuando esta política activa un error. Es importante conocer esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de las políticas y Cómo gestionar los fallos.

Errores de tiempo de ejecución

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

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

Errores de implementación

Ninguno

Variables de error

Estas variables se definen cuando se produce un error de tiempo de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de las políticas.

Variables	Dónde	Ejemplo
`fault.name="fault_name"`	`fault_name` es el nombre del error, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error.	`fault.name = "RaiseFault"`
`raisefault.policy_name.failed`	`policy_name` es el nombre de la política especificado por el usuario que ha provocado el error.	`raisefault.RF-ThrowError.failed = true`

Ejemplo de respuesta de error

Nota: Para gestionar los errores, la práctica recomendada es detectar la parte errorcode de la respuesta de error. No te fíes del texto de la faultstring, ya que podría cambiar.

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

Esquema

Cada tipo de política se define mediante un esquema XML (.xsd). Puedes consultar los esquemas de políticas en GitHub.

Temas relacionados

Consulta Gestionar fallos.

Política RaiseFault Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Qué

Ejemplos

Devuelve FaultResponse

Devuelve la carga útil FaultResponse

Gestionar errores de llamadas de servicio

Acerca de la política RaiseFault

Referencia de elemento

Atributos de <RaiseFault>

Elemento <DisplayName>

Elemento <IgnoreUnresolvedVariables>

Elemento <FaultResponse>

Elemento <FaultResponse><AssignVariable>

Elemento <FaultResponse><Add>/<Headers>

Elemento <FaultResponse><Copy>

Atributos

Elemento <FaultResponse><Copy>/<Headers>

Elemento <FaultResponse><Copy>/<StatusCode>

Elemento <FaultResponse><Remove>/<Headers>

Elemento <FaultResponse><Set>

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

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

Atributos

Elemento <FaultResponse>/<Set>/<StatusCode>

Elemento <ShortFaultReason>

Variables de flujo

Ejemplo de uso de RaiseFault

Referencia de errores

Errores de tiempo de ejecución

Errores de implementación

Variables de error

Ejemplo de respuesta de error

Esquema

Temas relacionados

Política RaiseFault