Appels externes

Les appels externes vous permettent d’ingérer des données provenant d’API externes à Microsoft Dynamics 365 Fraud Protection, puis d’utiliser ces données pour prendre des décisions éclairées en temps réel. Par exemple, des services tiers de vérification d’adresse et de téléphone, ou vos propres modèles de notation personnalisés, peuvent fournir des données cruciales pour déterminer le niveau de risque de certains événements. En utilisant des appels externes, vous pouvez vous connecter à n’importe quel point de terminaison d’API, envoyer une requête à ce point de terminaison à partir de votre règle selon les besoins, et utiliser la réponse de ce point de terminaison pour prendre une décision.

Types d’API pouvant être utilisés dans un appel externe

Avant de créer un appel externe, vous devez connaître les limitations suivantes :

• Fraud Protection ne prend actuellement en charge que les méthodes d’authentification suivantes : Anonyme et AAD.
• Fraud Protection ne prend actuellement en charge que les méthodes HTTP suivantes : GET et POST.

Créer un appel externe

1. Dans le portail Fraud Protection, puis dans la navigation gauche, sélectionnez Appels externes, puis Nouvel appel externe.

2. Passez en revue et définissez les champs suivants en fonction des besoins.

   • Nom : entrez le nom que vous utiliserez pour référencer l’appel externe à partir de vos règles. Le nom ne peut contenir que des chiffres, des lettres et des traits de soulignement. Il ne peut pas commencer par un chiffre.

     Note

     Vous ne pouvez pas modifier le nom d’un appel externe après l’avoir utilisé dans une règle.

   • Description : ajoutez une description pour aider votre équipe à identifier rapidement l’appel externe.

   • Requête Web : sélectionnez la méthode HTTP appropriée (GET ou POST), puis entrez le point de terminaison de l’API.

     Note

     Seuls les points de terminaison HTTPS sont pris en charge.

   • Activez les appels de préchauffage périodiques : si le trafic vers votre point de terminaison d’appel externe est trop faible, la connexion peut être froide et peut augmenter la latence de réponse du service externe. Pour atténuer ce problème, activez les appels de préchauffage à partir de la page de configuration des appels externes. Utilisez le bouton bascule pour activer les appels de préchauffement. Vous devez fournir une URL GET Keep-alive valide. Comme avec le point de terminaison principal, le point de terminaison keep-alive doit également passer la connexion test. Si vous configurez votre appel externe avec des appels de préchauffage activés, lorsque votre volume de trafic est trop faible, Fraud Protection effectue automatiquement des appels de préchauffage anonymes au point de terminaison keep-alive à l’aide de la méthode GET uniquement.

     Remarque

     Aucun paramètre, configurations ou en-têtes configurables ne peut être utilisé dans les appels de préchauffement.

   • Authentification : sélectionnez la méthode qui doit être utilisée pour authentifier les demandes entrantes.

     • Si vous sélectionnez Anonyme, aucun en-tête d’autorisation n’est envoyé.
     • Si vous sélectionnez AAD, un jeton Azure Active Directory (Azure AD) est généré dans votre locataire et le jeton> du porteur <est utilisé comme en-tête d’autorisation.

     Pour plus d’informations sur l’authentification, l’autorisation et les jetons Azure AD, consultez la section Comprendre l’authentification et l’autorisation, plus loin dans cet article.

   • Audience : si vous sélectionnez AAD comme méthode d’authentification, vous êtes invité à fournir un public. Vous pouvez utiliser une application Azure existante en tant qu’audience ou en créer une nouvelle via l’expérience d’intégration dans le portail Fraud Protection. Assurez-vous que le public est autorisé à accéder à l’appel/au service externe. Pour en savoir plus sur la façon de configurer l’authentification Azure Active Directory (Azure AD), voir Configurer l’authentification Azure AD.

   • ID d’application : vous devez également fournir l’ID d’application d’une application Azure AD nouvelle ou existante au sein de votre locataire d’abonnement Fraud Protection. Générez un certificat dans votre Azure Key Vault. L’application Fraud Protection doit avoir accès en lecture à ce stockage Azure Key Vault. Chargez le certificat vers cette application Azure AD. Pour plus d’informations sur la création et la gestion d’applications Azure AD, consultez Créer des applications Azure Active Directory.

   • URL du certificat : fournissez l’URL de l’identificateur du certificat depuis votre stockage Azure Key Vault. Il s’agit du même certificat que vous avez chargé dans l’application Azure AD à l’étape précédente. Pour plus d’informations sur la génération d’un certificat dans Azure Key Vault, consultez Créer et fusionner une demande de signature de certificat dans Azure Key Vault

   • Ajouter un paramètre : vous pouvez utiliser des paramètres pour transmettre des données de Fraud Protection à votre point de terminaison d’API. Selon la méthode HTTP que vous sélectionnez, ces paramètres sont envoyés au point de terminaison dans la chaîne de requête ou dans le corps de la requête.

     Vous pouvez ajouter des exemples de valeur pour chaque paramètre. Fraud Protection utilise ces valeurs de paramètre pour effectuer un exemple d’appel à votre point de terminaison, soit avant la création, soit chaque fois que vous sélectionnez Test.

     Remarque

     Toutes les valeurs de paramètre sont interprétées comme des chaînes.

   • Exemple de requête : donnez un exemple de la requête envoyée à votre appel externe. La demande doit refléter les noms et valeurs des paramètres que vous avez spécifiés et elle ne peut pas être modifiée.

     Pour les méthodes GET, l’URL de la requête est affichée. Pour les méthodes POST, le corps de la requête est affiché.

     L’exemple de requête sert à effectuer un exemple d’appel vers votre point de terminaison, soit avant la création, soit à chaque fois que vous sélectionnez Tester.

   • Exemple de réponse : fournissez un exemple des données renvoyées dans une réponse réussie de la part de votre point de terminaison d’API. Ces données doivent être au format JavaScript Object Notation (JSON) et peuvent être référencées dans vos règles. L’exemple que vous fournissez ici s’affiche lorsque vous créez des règles.

     Sélectionnez Tester pour saisir automatiquement une réponse réelle de votre API dans ce champ.

   • Délai d’expiration : spécifiez combien de temps, en millisecondes, la requête doit attendre avant de parvenir à expiration. Vous devez spécifier un nombre compris entre 1 et 1000.

   • Réponse par défaut : spécifiez la réponse par défaut à renvoyer si votre demande échoue ou dépasse le délai d’expiration spécifié. La valeur doit être un objet JSON ou un élément JSON valide.

3. Facultatif : pour envoyer un exemple de requête à votre point de terminaison d’API et afficher la réponse, sélectionnez Tester. Pour plus d’informations, consultez la section suivante, Tester un appel externe.

4. Lorsque vous avez terminé de définir les champs requis, sélectionnez Créer.

Tester un appel externe

Pour vous assurer que Fraud Protection peut se connecter à votre point de terminaison, testez la connexion à tout moment.

• Pour tester une connexion pendant que vous créez un nouvel appel externe ou que vous modifiez un appel externe existant, définissez tous les champs obligatoires, puis sélectionnez Tester.

  Fraud Protection utilise le point de terminaison et les paramètres que vous avez fournis pour envoyer une requête à votre appel externe.

  • Si Fraud Protection atteint avec succès le point de terminaison cible, une barre de message verte apparaît en haut du volet pour vous informer que la connexion a réussi. Pour afficher la réponse complète, sélectionnez Afficher les détails de la réponse.
  • Si Fraud Protection ne peut pas atteindre le point de terminaison cible ou s’il ne reçoit pas de réponse avant l’expiration du délai spécifié, une barre de message rouge apparaît en haut du volet et affiche l’erreur rencontrée. Pour afficher plus d’informations sur l’erreur, sélectionnez Afficher les détails de l’erreur.

Surveiller les appels externes

Surveiller les appels externes dans le portail Fraud Protection

Fraud Protection présente une vignette contenant trois éléments de mesure pour chaque appel externe que vous définissez :

• Requêtes par seconde : le nombre total de requêtes divisé par le nombre total de minutes dans le délai d’exécution sélectionné.
• Latence moyenne : le nombre total de requêtes divisé par le nombre total de minutes dans le délai d’exécution sélectionné.
• Taux de réussite : nombre total de demandes réussies divisées par le nombre total de demandes effectuées.

Les chiffres et les graphiques affichés sur cette vignette incluent uniquement les données du délai d’exécution que vous sélectionnez dans la liste déroulante dans le coin supérieur droit de la page.

1. Pour approfondir l’étude des données relatives à votre appel externe, sélectionnez Performances dans le coin droit de la tuile.

   Fraud Protection affiche une nouvelle page offrant une vue plus détaillée des métriques.

2. Pour afficher les métriques pour n’importe quelle délai d’exécution au cours des trois derniers mois, ajustez le paramètre Plage de dates en haut de la page.

En plus des trois métriques décrites précédemment, un graphique Erreur est affiché. Ce graphique affiche le nombre d’erreurs, par type d’erreur et par code. Pour afficher le nombre d’erreurs au fil du temps ou pour afficher la distribution des erreurs, sélectionnez Diagramme circulaire.

En plus des erreurs du client HTTP (400, 401 et 403), vous pouvez voir les erreurs suivantes :

• ID d’application non valide : l’ID d’application qui a été fourni n’existe pas dans votre client ou il n’est pas valide.
• Échec AAD : le jeton Azure AD n’a pas pu être récupéré.
• Définition introuvable : l’appel externe a été supprimé, mais il est toujours référencé dans une règle.
• Délai d’exécution : la requête adressée à la cible a pris plus de temps que le délai d’expiration spécifié.
• Échec de la communication : aucune connexion n’a pu être établie avec la cible en raison d’un problème réseau ou parce que la cible n’est pas disponible.
• Disjoncteur : si l’appel externe a échoué en continu et a dépassé un certain seuil, tous les autres appels sont suspendus pendant un court intervalle.
• Échec inconnu : une défaillance interne de Dynamics 365 s’est produite.

Utiliser le suivi des événements pour surveiller les appels externes

Vous pouvez utiliser la fonction de traçage des événements de Fraud Protection pour transférer les événements liés à vos appels externes vers vos propres instances d’Azure Event Hubs ou du Stockage Blob Azure. Dans le portail Fraud Protection, sur la page Suivi des événements, vous pouvez vous abonner aux deux événements suivants liés aux appels externes :

• FraudProtection.Monitoring.ExternalCalls
• FraudProtection.Errors.ExternalCalls

Chaque fois qu’une requête est adressée à un appel externe, un événement est envoyé à l’espace de noms FraudProtection.Monitoring.ExternalCalls. La charge utile de l’événement comprend des informations sur la latence de l’appel, le statut de la requête et la règle et la clause à partir desquelles la requête a été déclenchée.

Lorsqu’un appel externe échoue, un événement est envoyé à l’espace de noms FraudProtection.Errors.ExternalCalls. La charge utile d’événement inclut le corps et la requête d’URI qui ont été envoyés à l’appel externe, et la réponse qui a été reçue.

Pour plus d’informations sur le suivi des événements, comment vous abonner à des événements et ce que vous pouvez faire avec les événements, consultez Suivi des événements.

Pour plus d’informations sur l’intégration de ces données aux flux de travail de votre propre organisation et sur la configuration de la surveillance, des alertes et des rapports personnalisés, consultez Extensibilité via Event Hubs.

Gérer les appels externes

• Pour modifier un appel externe existant, sélectionnez Modifier sur l’en-tête de la carte.

  Note

  Vous ne pouvez pas modifier le nom et les paramètres d’un appel externe après l’avoir utilisé dans une règle.

• Pour supprimer un appel externe existant, sélectionnez les points de suspension (...), puis sélectionnez Supprimer.

  Note

  Vous ne pouvez pas supprimer un appel externe après l’avoir référencé dans une règle.

• Pour afficher les mesures de performances détaillées pour un appel externe, sélectionnez Performances.

• Pour vérifier que Fraud Protection peut toujours se connecter à votre appel externe, sélectionnez les points de suspension (...), puis sélectionnez Tester la connexion.

Utiliser un appel externe dans les règles

Pour utiliser vos appels externes pour prendre des décisions, référencez-les à partir de vos règles.

Par exemple, pour référencer un appel externe nommé myCall dans votre règle, utilisez la syntaxe suivante :

External.myCall()

Si myCall nécessite un paramètre, tel que IPaddress, utilisez la syntaxe suivante :

External.myCall(@"device.ipAddress")

Pour plus d’informations sur le langage des règles et sur la façon dont vous pouvez utiliser les appels externes dans les règles, consultez le Guide de référence du langage.

Comprendre l’authentification et l’autorisation

Pour garantir l’accès sécurisé aux données, les API authentifient souvent l’émetteur d’une requête pour vérifier qu’il est autorisé à accéder aux données. Les appels externes dans Fraud Protection prennent en charge deux méthodes d’authentification : Anonyme et AAD.

Si vous sélectionnez Anonyme, l’en-tête d’autorisation dans la requête HTTP vers le point de terminaison cible est laissé vide. Utilisez cette option lorsque le point de terminaison cible ne nécessite pas d’en-tête d’autorisation. Par exemple, si votre point de terminaison utilise une clé API, configurez la paire clé-valeur dans le cadre de l’URL de requête que vous entrez dans le champ Requête web. Le point de terminaison cible peut ensuite valider si la clé API de l’URL de requête est autorisée, puis décider si l’autorisation doit être accordée.

Si vous sélectionnez AAD, l’en-tête d’autorisation dans la requête HTTP vers le point de terminaison cible inclut un jeton du porteur. Un jeton du porteur est un jeton Web JSON (JWT) émis par Azure AD. Pour plus d’informations sur les JWT, consultez Jetons d’accès à la plateforme d’identité Microsoft. Fraud Protection ajoute la valeur du jeton au texte « Bearer » (Porteur) au format requis dans l’en-tête d’autorisation de la requête, comme indiqué ici :

<Jeton> du porteur

Réclamations de jeton

Le tableau suivant répertorie les réclamations auxquelles vous pouvez vous attendre dans les jetons du porteur émis par Fraud Protection.

Lorsque votre API reçoit un jeton, elle doit ouvrir le jeton et valider que chacune des réclamations précédentes correspond à sa description.

Voici un exemple qui montre comment vous pouvez authentifier une requête entrante en utilisant 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.");
}

Pratiques de données externes

Vous reconnaissez que vous êtes responsable du respect de toutes les lois et réglementations en vigueur, y compris, sans se limiter à ce qui suit, les lois sur la protection des données, les restrictions contractuelles et/ou les politiques relatives aux jeux de données que vous fournissez à Microsoft via la fonction Appels externes de Fraud Protection. En outre, vous reconnaissez que votre utilisation de Fraud Protection est soumise à des restrictions d’utilisation détaillées dans le Contrat client Microsoft, qui stipule que vous ne pouvez pas utiliser Fraud Protection (i) comme seul facteur pour déterminer s’il faut exécuter une transaction de paiement ; (ii) comme facteur permettant de déterminer la situation financière, les antécédents financiers, la solvabilité ou l’admissibilité à l’assurance, au logement ou à l’emploi d’une personne ; ou (iii) pour prendre des décisions produisant des effets juridiques ou affectant de manière significative une personne. Il vous est également interdit de fournir ou d’utiliser de toute autre manière des types de données sensibles ou hautement réglementés dans le cadre de la fonction d’appels externes de Fraud Protection. Prenez le temps de passer en revue tout jeu de données ou types de données avant de les utiliser avec la fonctionnalité d’appels externes de Fraud Protection pour vous assurer que vous êtes conforme à cette disposition. Microsoft se réserve également le droit de vérifier que vous respectez cette disposition.

Ressources supplémentaires

• Vidéo : Découvrir la nouvelle fonction d’appels externes dans Dynamics 365 Fraud Protection
• Blog : Personnaliser votre protection avec de nouvelles fonctionnalités dans la version préliminaire de Dynamics 365 Fraud Protection : prendre des décisions éclairées en temps réel au moyen des appels externes