Estás consultando la documentación de Apigee y Apigee Hybrid.
Consulta la documentación de
Apigee Edge.
La política RaiseFault permite a los desarrolladores de APIs iniciar un flujo de errores, definir variables de error en un mensaje del cuerpo de la respuesta y establecer códigos de estado de respuesta adecuados. También puedes usar la política RaiseFault para definir variables de flujo relacionadas con el error, como fault.name, fault.type y fault.category. Como estas variables se pueden ver en los datos analíticos y en los registros de acceso del router, que se usan para depurar, es importante identificar el fallo con precisión.
Puedes usar la política RaiseFault para tratar condiciones específicas como errores, aunque no se haya producido ningún error en otra política o en el servidor backend del proxy de la API. Por ejemplo, si quieres que el proxy envíe un mensaje de error personalizado a la aplicación cliente cada vez que el cuerpo de la respuesta del backend contenga la cadena unavailable, puedes invocar la política RaiseFault como se muestra en el fragmento de código siguiente:
<!-- /antipatterns/examples/raise-fault-conditions-1.xml --> <TargetEndpoint name="default"> ... <Response> <Step> <Name>RF-Service-Unavailable</Name> <Condition>(message.content Like "*unavailable*")</Condition> </Step> </Response> ...
El nombre de la política RaiseFault se muestra como fault.name en
Monitorización de APIs y como x_apigee_fault_policy en los registros de acceso de Analytics y Router.
Esto ayuda a diagnosticar fácilmente la causa del error.
Antipatrón
Usar la política RaiseFault en FaultRules después de que otra política ya haya generado un error
En el ejemplo siguiente, se ha producido un error InvalidAccessToken
en una política OAuthV2 del flujo del proxy de API. Si se produce un error, Apigee asignará el valor InvalidAccessToken a fault.name, entrará en el flujo de errores y ejecutará las FaultRules definidas. En FaultRule, hay una política RaiseFault llamada RaiseFault que envía una respuesta de error personalizada cada vez que se produce un error InvalidAccessToken. Sin embargo, si se usa la política RaiseFault en una FaultRule, la variable fault.name
se sobrescribe y oculta la verdadera causa del fallo.
<!-- /antipatterns/examples/raise-fault-conditions-2.xml --> <FaultRules> <FaultRule name="generic_raisefault"> <Step> <Name>RaiseFault</Name> <Condition>(fault.name equals "invalid_access_token") or (fault.name equals "InvalidAccessToken")</Condition> </Step> </FaultRule> </FaultRules>
Usar la política RaiseFault en una FaultRule en todas las condiciones
En el ejemplo siguiente, se ejecuta una política RaiseFault llamada RaiseFault si fault.name
no es RaiseFault:
<!-- /antipatterns/examples/raise-fault-conditions-3.xml --> <FaultRules> <FaultRule name="fault_rule"> .... <Step> <Name>RaiseFault</Name> <Condition>!(fault.name equals "RaiseFault")</Condition> </Step> </FaultRule> </FaultRules>
Al igual que en el primer caso, las variables de error clave fault.name, fault.code y fault.policy se sobrescriben con el nombre de la política RaiseFault. Este comportamiento hace que sea casi imposible determinar qué política ha provocado el error sin acceder a un archivo de seguimiento que muestre el error o sin reproducir el problema.
Usar la política RaiseFault para devolver una respuesta HTTP 2xx fuera del flujo de errores.
En el ejemplo siguiente, se ejecuta una política RaiseFault llamada HandleOptionsRequest cuando el verbo de la solicitud es OPTIONS:
<!-- /antipatterns/examples/raise-fault-conditions-4.xml --> <PreFlow name="PreFlow"> <Request> … <Step> <Name>HandleOptionsRequest</Name> <Condition>(request.verb Equals "OPTIONS")</Condition> </Step> … </PreFlow>
El objetivo es devolver la respuesta al cliente de la API inmediatamente sin procesar otras políticas. Sin embargo, esto dará lugar a datos analíticos engañosos, ya que las variables de error contendrán el nombre de la política RaiseFault, lo que hará que sea más difícil depurar el proxy. La forma correcta de implementar el comportamiento deseado es usar Flows con condiciones especiales, tal como se describe en Añadir compatibilidad con CORS.
Impacto
Si se usa la política RaiseFault tal como se ha descrito anteriormente, se sobrescribirán las variables de error clave con el nombre de la política RaiseFault en lugar del nombre de la política que ha fallado. En los registros de acceso de Analytics y NGINX, se sobrescriben las variables x_apigee_fault_code y x_apigee_fault_policy . En Monitorización de APIs, se sobrescriben Fault Code
y Fault Policy . Este comportamiento dificulta la resolución de problemas y la determinación de qué política es la causa real del error.
En la captura de pantalla de Monitorización de APIs que se muestra a continuación, puede ver que el código de error y la política de errores se han sustituido por valores genéricos RaiseFault, lo que hace que sea imposible determinar la causa principal del fallo a partir de los registros:
Práctica recomendada
Cuando una política de Apigee genera un error y quieres personalizar el mensaje de respuesta de error, usa las políticas AssignMessage o JavaScript en lugar de la política RaiseFault.
La política RaiseFault se debe usar en un flujo sin errores. Es decir, solo debe usar RaiseFault para tratar una condición específica como un error, aunque no se haya producido ningún error en una política o en el servidor backend del proxy de la API. Por ejemplo, puedes usar la política RaiseFault para indicar que faltan parámetros de entrada obligatorios o que tienen una sintaxis incorrecta.
También puedes usar RaiseFault en una regla de fallo si quieres detectar un error durante el procesamiento de un fallo. Por ejemplo, el propio controlador de errores podría provocar un error que quieras indicar mediante RaiseFault.