Llamadas externas
Las llamadas externas le permiten ingerir datos de API fuera de Microsoft Dynamics 365 Fraud Protection y luego usar esos datos para tomar decisiones informadas en tiempo real. Por ejemplo, los servicios de verificación de direcciones y teléfonos de terceros, o sus propios modelos de puntuación personalizados, pueden proporcionar información fundamental que ayude a determinar el nivel de riesgo para algunos eventos. Mediante el uso de llamadas externas, puede conectarse a cualquier punto final de la API, realizar una solicitud a ese punto final desde dentro de su regla según sea necesario y utilizar la respuesta de ese punto final para tomar una decisión.
Nota:
Si se necesitan datos adicionales para todos los eventos, también puede enviarlos como parte del esquema de evaluación. Para obtener más información sobre cómo enviar datos personalizados como parte de una solicitud de API, consulte Muestra de datos personalizados.
Tipos de API que se pueden utilizar en una llamada externa
Antes de crear una llamada externa, debe conocer las siguientes limitaciones:
- Actualmente, Fraud Protection solo admite los siguientes métodos de autenticación: Anónimo y AAD.
- Actualmente, Fraud Protection solo admite los siguientes métodos HTTP: GET y POST.
Crear una llamada externa
En el portal de Fraud Protection, en la zona de navegación izquierda, seleccione Llamadas externas y luego Nueva llamada externa.
Revise y establezca los siguientes campos según sea necesario.
Nombre : escriba el nombre que usará para hacer referencia a la llamada externa desde las reglas. El nombre solo puede contener números, letras y guiones bajos. No puede comenzar con un número.
Nota:
No puede cambiar el nombre de una llamada externa después de usarlo en una regla.
Descripción - Agregue una descripción para ayudar a su equipo a identificar rápidamente la llamada externa.
Solicitud web - Seleccione el método HTTP apropiado (GET o POST) y luego ingrese el punto final de la API.
Nota:
Solo se admiten los puntos finales HTTPS.
Habilitar llamadas de preparación periódicas: si el tráfico al punto de conexión de llamada externo es demasiado bajo, la conexión puede estar inactiva y puede aumentar la latencia de respuesta del servicio externo. Para mitigar este problema, habilite las llamadas de preparación desde la página Configuración de llamadas externas. Use el botón de alternancia para habilitar las llamadas de preparación. Debe proporcionar una dirección URL get keep-alive válida. Al igual que con el punto de conexión principal, el punto de conexión keep-alive también debe superar la conexión de prueba. Si configura la llamada externa con llamadas de preparación habilitadas, cuando el volumen de tráfico se reduce demasiado, Protección contra fraudes realiza automáticamente llamadas de preparación anónimas al punto de conexión de mantenimiento activo mediante el método GET únicamente.
Nota:
No se pueden usar parámetros, configuraciones ni encabezados configurables en llamadas de preparación.
Autenticación : seleccione el método que se debe usar para autenticar las solicitudes entrantes.
- Si selecciona Anónimo, no se envía un encabezado de autorización.
- Si selecciona AAD, se genera un token de Azure Active Directory (Azure AD) en el inquilino y > de portador como encabezado de autorización.
Para obtener más información sobre autenticación, autorización y tokens de Azure AD, vea Comprender la autenticación y la autorización más adelante en este artículo.
Audiencia : si selecciona AAD como método de autenticación, se le pedirá que proporcione una audiencia. Puede usar una aplicación de Azure existente como audiencia o crear una nueva a través de la experiencia de integración en el portal de Protección contra fraudes. Asegúrese de que el público tenga permiso para acceder a la llamada/servicio externo. Para obtener más información sobre cómo configurar la autenticación Azure Active Directory (Azure AD), consulte Configurar autenticación Azure AD.
Id. de aplicación: también debe proporcionar el identificador de aplicación de una aplicación de Azure AD nueva o existente en el inquilino de la suscripción de Protección contra fraudes. Genere un certificado en su Azure Key Vault. La aplicación Fraud Protection debe tener acceso de lectura a este Azure Key Vault. Cargue el certificado para esta aplicación de Azure AD. Para obtener más información sobre cómo crear y administrar aplicaciones de Azure AD, vea Crear aplicaciones de Azure Active Directory.
Certificar URL -Proporcione la dirección URL del identificador de certificado desde su Azure Key Vault. Este es el mismo certificado que cargó en la aplicación Azure AD en el paso anterior. Para obtener más información sobre cómo generar un certificado en Azure Key Vault, consulte Creación y fusión de una solicitud de firma de certificado en Azure Key Vault
Agregar parámetro - Puede utilizar parámetros para pasar datos de Fraud Protection a su punto final de API. Dependiendo del método HTTP que seleccione, estos parámetros se envían al punto de conexión en la cadena de consulta o como parte del cuerpo de la solicitud.
Puede agregar valores de muestra para cada parámetro. Protección contra fraudes usa estos valores de parámetro para realizar una llamada de ejemplo al punto de conexión, ya sea antes de la creación o cada vez que seleccione Probar.
Nota:
Todos los valores de los parámetros se interpretan como cadenas.
Solicitud de muestra - Proporcione un ejemplo de la solicitud que se envía a su llamada externa. La solicitud debe reflejar los nombres y valores de los parámetros que especificó y no se puede editar.
Para métodos GET, se muestra la URL de la solicitud. Para métodos POST, se muestra el cuerpo de la solicitud.
La solicitud de muestra se usa para realizar una llamada de muestra a su punto final, ya sea antes de la creación o siempre que seleccione Prueba.
Respuesta de muestra - Proporcione un ejemplo de los datos que se devuelven en una respuesta exitosa desde su punto final de API. Estos datos deben estar en formato de notación de objetos JavaScript (JSON) y se puede hacer referencia a ellos en sus reglas. El ejemplo que proporciona aquí se muestra a medida que crea reglas.
Seleccione Prueba para ingresar automáticamente una respuesta real de su API en este campo.
tiempo de espera: especifique cuánto tiempo, en milisegundos, la solicitud debe esperar antes de que se agote el tiempo de espera. Debe especificar un número entre 1 y 5000.
Respuesta predeterminada - Especifique la respuesta predeterminada que debe devolverse si su solicitud falla o excede el tiempo de espera especificado. El valor debe ser un objeto JSON válido o un elemento JSON.
Opcional: para enviar una solicitud de muestra a su punto final de API y ver la respuesta, seleccione Prueba. Para obtener más información, consulte la siguiente sección, Probar una llamada externa.
Cuando termine de establecer los campos necesarios, seleccione Crear.
Probar una llamada externa
Para asegurarse de que Fraud Protection pueda conectarse a su punto final, pruebe la conexión en cualquier punto.
Para probar una conexión mientras crea una nueva llamada externa o edita una llamada externa existente, configure todos los campos obligatorios y luego seleccione Prueba.
La Fraud Protection utiliza el punto final y los parámetros que proporcionó para enviar una solicitud a su llamada externa.
- Si la Fraud Protection llega con éxito al punto final de destino, aparece una barra de mensaje verde en la parte superior del panel para informarle que la conexión fue exitosa. Para ver la respuesta completa, seleccione Ver detalles de la respuesta.
- Si la Fraud Protection no puede llegar al punto final de destino, o si no recibe una respuesta antes del tiempo de espera especificado, aparece una barra de mensaje roja en la parte superior del panel y muestra el error que se encontró. Para ver más información sobre el error, seleccione Ver detalles del error.
Monitorear llamadas externas
Supervise las llamadas externas en el portal de Fraud Protection
Fraud Protection muestra un mosaico que contiene tres métricas para cada llamada externa que defina:
- Solicitudes por segundo - El número total de solicitudes dividido por el número total de minutos en el período de tiempo seleccionado.
- latencia media: número total de latencias de solicitud divididas por el número total de minutos en el período de tiempo seleccionado.
- Tasa de éxito: el número total de solicitudes correctas divididas por el número total de solicitudes realizadas.
Los números y gráficos que se muestran en este mosaico incluyen solo datos para el período de tiempo que seleccione en la lista desplegable en la esquina superior derecha de la página.
Nota:
Las métricas se muestran solo cuando su llamada externa se usa en una regla activa.
Para profundizar en los datos sobre su llamada externa, seleccione Actuación en la esquina derecha del mosaico.
Fraud Protection muestra una nueva página que tiene una vista más detallada de las métricas.
Para ver las métricas de cualquier período de los últimos tres meses, ajuste Rango de fechas en la parte superior de la página.
Además de las tres métricas que se describieron anteriormente, se muestra el gráfico de Error. Este gráfico muestra el número de errores, por tipo de error y código. Para ver los recuentos de errores a lo largo del tiempo o para ver la distribución de errores, seleccione Gráfico circular.
Además de los errores del cliente HTTP (400, 401 y 403), es posible que vea los siguientes errores:
- ID de aplicación no válido - El ID de la aplicación que se proporcionó no existe en su inquilino o no es válido.
- Fallo de AAD - el token de Azure AD no se pudo recuperar.
- Definición no encontrada - La llamada externa se ha eliminado, pero todavía se hace referencia a ella en una regla.
- Se acabó el tiempo - La solicitud al objetivo tardó más que el tiempo de espera especificado.
- Fallo de comunicación - No se pudo establecer conexión con el destino debido a un problema de red o porque el destino no está disponible.
- Interruptor: si la llamada externa ha fallado continuamente y ha superado un umbral determinado, todas las llamadas adicionales se suspenden durante un intervalo corto.
- Falla desconocida - Se produjo un error interno de Dynamics 365.
Utilice el seguimiento de eventos para monitorear llamadas externas
Puede usar la capacidad de seguimiento de eventos de Fraud Protection para reenviar eventos relacionados con sus llamadas externas a sus propias instancias de Azure Event Hubs o Azure Blob Storage. En el portal de Fraud Protection, en la página Seguimiento de eventos, puede suscribirse a los dos eventos siguientes relacionados con llamadas externas:
- FraudProtection.Monitoring.ExternalCalls
- FraudProtection.Errors.ExternalCalls
Siempre que se realiza una solicitud a una llamada externa, se envía un evento al espacio de nombres FraudProtection.Monitoring.ExternalCalls. La carga útil del evento incluye información sobre la latencia de la llamada, el estado de la solicitud y la regla y cláusula desde la que se desencadenó la solicitud.
Cuando una llamada externa falla, se envía un evento al espacio de nombres FraudProtection.Errors.ExternalCalls. La carga útil del evento incluye la solicitud de URI y el cuerpo que se enviaron a la llamada externa y la respuesta que se recibió.
Para obtener más información sobre el seguimiento de eventos, cómo suscribirse a eventos y qué puede hacer con los eventos, consulte Seguimiento de eventos.
Para obtener información sobre cómo integrar estos datos con los flujos de trabajo de su propia organización y configurar la supervisión, las alertas y los informes personalizados, consulte Extensibilidad a través de Event Hubs.
Gestionar llamadas externas
Para editar una llamada externa existente, seleccione Editar en el encabezado de la tarjeta.
Nota:
No puede cambiar el nombre y los parámetros de una llamada externa después de usarlo en una regla.
Para eliminar una llamada externa existente, seleccione los puntos suspensivos (...) y luego seleccione Eliminar.
Nota:
No puede eliminar una llamada externa después de que se haga referencia a ella en una regla.
Para ver métricas de rendimiento detalladas para una llamada externa, seleccione Actuación.
Para probar que Fraud Protection aún puede conectarse a su llamada externa, seleccione los puntos suspensivos (...) y luego seleccione Conexión de prueba.
Usar una llamada externa en las reglas
Para usar sus llamadas externas para tomar decisiones, refiérase a ellas en sus reglas.
Por ejemplo, para hacer referencia a una llamada externa que se denomina myCall en su regla, use la siguiente sintaxis:
External.myCall()
Si myCall requiere un parámetro, como IPaddress, use la siguiente sintaxis:
External.myCall(@"device.ipAddress")
Para obtener información sobre el lenguaje de las reglas y cómo puede utilizar llamadas externas en las reglas, consulte la Guía de referencia de idiomas.
Nota:
Si se utilizan llamadas externas en una regla, la latencia de la regla puede aumentar.
Comprender la autenticación y la autorización
Para garantizar que se acceda a los datos de forma segura, las API suelen autenticar al remitente de una solicitud para verificar que tiene permiso para acceder a los datos. Las llamadas externas en Fraud Protection admiten dos métodos de autenticación: Anónimo y AAD.
Si selecciona Anónimo, el encabezado de autorización de la solicitud HTTP al punto de conexión de destino se deja en blanco. Utilice esta opción cuando el punto final de destino no requiera un encabezado de autorización. Por ejemplo, si su punto final utiliza una clave API, configure el par clave-valor como parte de la URL de solicitud que ingresa en el campo Solicitud web. El punto final de destino puede validar si la clave de API de la URL de solicitud está permitida y luego decidir si se debe otorgar el permiso.
Si selecciona AAD, el encabezado de autorización de la solicitud HTTP al punto de conexión de destino incluye un token de portador. Un token de portador es un JSON Web Token (JWT) emitido por Azure AD. Para obtener información sobre los JWT, consulte Tokens de acceso a la plataforma de identidad de Microsoft. Fraud Protection agrega el valor del token al texto "Portador" en el formato requerido en el encabezado de autorización de solicitud como se muestra aquí:
Portador <token>
Reclamaciones de tokens
La siguiente tabla enumera las reclamaciones que puede esperar en los tokens al portador emitidos por Fraud Protection.
| Nombre | Reclamar | Descripción |
|---|---|---|
| Id. de suscriptor | tid | Esta reclamación identifica el ID de inquilino de Azure de la suscripción que está asociada con su cuenta de Fraud Protection. Para obtener información sobre cómo encontrar su ID de inquilino en el portal de Fraud Protection, consulte ID e información obligatorios. Para obtener información sobre cómo encontrar su Id. De inquilino en Azure Portal, consulte Cómo encontrar tu ID de inquilino de Azure Active Directory. |
| Público | aud | Esta afirmación identifica al destinatario previsto del token. El valor refleja exactamente el identificador de aplicación que proporcionó al configurar la llamada externa en el portal de Protección contra fraudes. |
| Id. de aplicación | appid | Esta notificación es el identificador de aplicación de Protección contra fraudes: * bf04bdab-e06f-44f3-9821-d3af64fc93a9*. Esta ID es propiedad exclusiva de Fraud Protection y solo Microsoft puede solicitar un token en su nombre. |
Cuando su API recibe un token, debe abrir el token y validar que cada una de las afirmaciones anteriores coincida con su descripción.
Aquí hay un ejemplo que muestra cómo puede autenticar una solicitud entrante usando JwtSecurityTokenHandler.
string authHeader = "Bearer <token>"; // the Authorization header value
var jwt = new JwtSecurityTokenHandler().ReadJwtToken(token);
string tid = jwt.Claims.Where(c => c.Type == "tid").FirstOrDefault()?.Value;
string aud = jwt.Claims.Where(c => c.Type == "aud").FirstOrDefault()?.Value;
string appid = jwt.Claims.Where(c => c.Type == "appid").FirstOrDefault()?.Value;
if(tid != "<my tenant id>" || aud != "<my application id>" || appid != "bf04bdab-e06f-44f3-9821-d3af64fc93a9")
{
throw new Exception("the token is not authorized.");
}
Prácticas de datos externos
Usted reconoce que es responsable de cumplir con todas las leyes y regulaciones aplicables, incluidas, entre otras, las leyes de protección de datos, las restricciones contractuales y / o las políticas relacionadas con los conjuntos de datos que proporciona a Microsoft a través de la función Llamadas externas de Fraud Protection. Además, reconoce que el uso de la Fraud Protection está sujeto a las restricciones de uso detalladas en el Acuerdo de cliente de Microsoft, que establece que no puede utilizar la Fraud Protection (i) como el único factor para determinar si debe continuar con una transacción de pago; (ii) como factor para determinar el estado financiero, historial financiero, solvencia crediticia o elegibilidad para seguro, vivienda o empleo de cualquier persona; o (iii) tomar decisiones que produzcan efectos legales o afecten significativamente a una persona. También tiene prohibido proporcionar o utilizar de otro modo tipos de datos sensibles o altamente regulados en relación con su uso de la función de llamadas externas de Fraud Protection. Dedique tiempo a revisar cualquier conjunto de datos o tipos de datos antes de usarlos con la característica de llamadas externas de Protección contra fraudes para asegurarse de que cumple con esta disposición. Microsoft también se reserva el derecho de verificar que cumple con esta disposición.