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 estos datos adicionales serán necesarios 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 Microsoft Entra ID.
• Actualmente, Fraud Protection solo admite los siguientes métodos HTTP: GET y POST.

Crear una llamada externa

1. En el portal de Fraud Protection, en la zona de navegación izquierda, seleccione Llamadas externas y luego Nueva llamada externa.

2. Revise y establezca los siguientes campos, según sea necesario:

   • Nombre: ingrese el nombre que utilizará para hacer referencia a la llamada externa de sus 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.

   • Autenticación - Seleccione el método que se debe utilizar para autenticar las solicitudes entrantes:

     • Si selecciona Anónimo, no se enviará un encabezado de autorización.
     • Si selecciona Microsoft Entra ID, un token de Microsoft Entra se generará en su inquilino, y se usará Portador <token> como encabezado de autorización.

     Para obtener más información sobre autenticación, autorización y tokens de Microsoft Entra, vea Comprender la autenticación y la autorización más adelante en este artículo.

   • Público: si seleccionó Microsoft Entra ID como método de autenticación, se le pedirá que proporcione un público. Puede usar una aplicación de Azure existente como público o crear una nueva a través de la experiencia de integración dentro del portal DFP. 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 de Microsoft Entra, consulte Configurar autenticación de Microsoft Entra.

   • ID de aplicación - También necesita proporcionar el ID de aplicación de una aplicación nueva o existente de Microsoft Entra dentro de su inquilino de suscripción de Fraud Protection. 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 Microsoft Entra. Para obtener más información sobre cómo crear y administrar aplicaciones de Microsoft Entra, vea Crear aplicaciones de Microsoft Entra.

   • 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 Microsoft Entra 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. Según el método HTTP que haya seleccionado, estos parámetros se enviarán al punto final en la cadena de consulta o como parte del cuerpo de la solicitud.

     Puede agregar valores de muestra para cada parámetro. La Fraud Protection utilizará estos valores de parámetros para realizar una llamada de muestra a su punto final, ya sea antes de la creación o siempre que seleccione Prueba.

     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.

   • Se acabó el tiempo - Especifique cuánto tiempo, en milisegundos, debe esperar la solicitud antes de que se agote el tiempo de espera. Debe especificar un número entre 1 y 1000.

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

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

4. Cuando haya terminado 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 promedio - El número total de solicitudes dividido por el número total de minutos en el período de tiempo seleccionado.
• Tasa de éxito - El número total de solicitudes exitosas dividido por el número total de solicitudes que se han realizado.

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.

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

2. 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 Microsoft Entra: el token de Microsoft Entra 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.
• Cortacircuitos - Si la llamada externa ha fallado continuamente y ha superado un cierto umbral, todas las llamadas posteriores se suspenderán durante un breve intervalo.
• 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")

También puede acceder al objeto Diagnóstico en reglas, lo que puede permitirle descubrir información importante de diagnóstico y depuración a partir de una respuesta de llamada externa. El objeto Diagnóstico contiene la carga útil de la solicitud, el punto final, el código HttpStatus, el mensaje de error y la latencia. Se puede acceder a cualquiera de estos campos en la experiencia de reglas y se puede utilizar con el método Observar salida para crear propiedades personalizadas. Es importante tener en cuenta que el objeto Diagnóstico debe crearse utilizando su método de extensión correspondiente, ".GetDiagnostics()", antes de que los campos del objeto puedan usarse en las reglas.

A continuación se muestra una regla de ejemplo que utiliza el objeto Diagnóstico:

LET $extResponse = External. myCall(@"device.ipAddress")
LET $extResponseDiagnostics = $extResponse.GetDiagnostics()
OBSERVE Output(Diagnostics = $extResponseDiagnostics ) 
WHEN $extResponseDiagnostics.HttpStatusCode != 200

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 estos métodos de autenticación:

1. Anónimo
2. Microsoft Entra ID
3. Base
4. Certificado

Nota

Actualmente, Fraud Protection solo admite los siguientes métodos HTTP: • GET • POST

Anónimo

Si selecciona Anónimo, el encabezado de autorización en la solicitud HTTP al punto final de destino se dejará 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.

Microsoft Entra ID

Si selecciona Microsoft Entra ID, el encabezado de autorización en la solicitud HTTP al punto final de destino se incluirá un token de portador. Un token de portador es un JSON Web Token (JWT) emitido por Microsoft Entra ID (anteriormente Microsoft Entra). 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 Microsoft Entra.
Público	aud	Esta notificación identifica la aplicación de Azure que está autorizada para acceder al servicio externo al que desea llamar. Para obtener más información sobre cómo configurar la autenticación de Microsoft Entra, consulte Configurar autenticación de Microsoft Entra
Id. de aplicación	appid	Esta solicitud identifica quién solicita un token. Para obtener más información sobre cómo configurar la autenticación de Microsoft Entra, consulte Configurar autenticación de Microsoft Entra

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 audience>" || appid != "<my application id>")
{
    throw new Exception("the token is not authorized.");
}

Base

Si selecciona Básico como método de autenticación, siga estos pasos para cargar su contraseña en el almacén de claves de Azure y otorgar permisos de acceso a Fraud Protection.

1. Inicie sesión en Azure Portal usando sus credenciales de inquilino.
2. Si tiene un almacén de claves existente que desea usar, vaya allí. Asegúrese de que Get y List estén seleccionados en los permisos secretos. Si desea crear un nuevo almacén de claves, siga las instrucciones en Inicio rápido: crear un almacén de claves mediante Azure Portal.
3. En el panel izquierdo, seleccione Secretos y después seleccione Generar/Importar.
4. En la página Crear un secreto, introduzca un nombre para su secreto. El valor secreto debe ser la contraseña de la URL web a la que intenta conectarse mediante llamadas externas.
5. Escriba información en los campos requeridos y seleccione Crear.
6. Copie y guarde el identificador secreto porque lo necesitará más adelante.
7. En el panel de navegación izquierdo, en Configuración, seleccione Directivas de acceso y luego seleccione Agregar nueva directiva de acceso.
8. En la sección Permisos de secreto, seleccione las casillas Lista y Obtener.
9. En los campos Principal y Aplicación autorizada, busque Dynamics 365 Fraud Protection y luego seleccione Seleccionar.
10. Seleccione Agregar y, a continuación, seleccione Guardar.
11. En el portal de Fraud Protection, en la página Llamadas externas, seleccione Llamada externa nueva.
12. En el campo Método de autenticación , seleccione Básico.
13. En el campo Nombre de usuario, ingrese su nombre de usuario para la URL a la que intenta conectarse. En el campo URL de contraseña, pegue el identificador secreto que copió anteriormente.

Certificado

Si selecciona Certificado como método de autenticación, siga estos pasos para cargar su certificado en el almacén de claves y otorgar permisos de acceso a Fraud Protection.

1. Inicie sesión en Azure Portal usando sus credenciales de inquilino.
2. Si tiene un almacén de claves existente que desea usar, vaya allí. Si desea crear un nuevo almacén de claves, siga las instrucciones en Inicio rápido: crear un almacén de claves mediante Azure Portal.
3. En el panel izquierdo, seleccione Certificados y después seleccione Generar/Importar.
4. En la página Crear un certificado, introduzca un nombre para su certificado. En el campo Asunto, escriba el asunto del certificado.
5. Escriba información en los campos requeridos y seleccione Crear.
6. Copie el identificador del certificado y péguelo en la caja de texto en Fraud Protection.
7. En el panel de navegación izquierdo, en Configuración, seleccione Directivas de acceso y luego seleccione Agregar nueva directiva de acceso.
8. En la sección Permisos de certificado, seleccione las casillas Lista y Obtener.
9. En los campos Principal y Aplicación autorizada, busque Dynamics 365 Fraud Protection y luego seleccione Seleccionar.
10. Seleccione Agregar y, a continuación, seleccione Guardar.
11. En el portal de Fraud Protection, en la página Llamadas externas, seleccione Llamada externa nueva.
12. En el campo Método de autenticación , seleccione Certificado.
13. Introduzca el nombre del certificado que está utilizando para acceder a la URL. En el campo URL de certificado, introduzca el identificador del certificado que copió anteriormente.

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. Tómese el tiempo para revisar cualquier conjunto de datos o tipos de datos antes de usarlos en relación con la función de llamadas externas de Fraud Protection para asegurarse de que cumple con esta disposición. Microsoft también se reserva el derecho de verificar que cumple con esta disposición.

Recursos adicionales

• Vídeo: Obtener información sobre la nueva función de llamadas externas en Dynamics 365 Fraud Protection
• Blog: Personalizar su protección con nuevas funciones en la versión preliminar de Dynamics 365 Fraud Protection: tome decisiones informadas en tiempo real con llamadas externas