Chiamate esterne
Le chiamate esterne consentono di inserire dati da API esterne a Microsoft Dynamics 365 Fraud Protection e quindi di utilizzare quei dati per prendere decisioni informate in tempo reale. Ad esempio, indirizzi di terze parti e servizi di verifica telefonica o modelli di punteggio personalizzati potrebbero fornire input critici che aiutano a determinare il livello di rischio per alcuni eventi. Utilizzando chiamate esterne, è possibile connettersi a qualsiasi endpoint API, effettuare una richiesta a tale endpoint a partire dalla regola come richiesto e utilizzare la risposta da tale endpoint per prendere una decisione.
Nota
Se questi dati aggiuntivi sono necessari per tutti gli eventi, è anche possibile inviarli come parte dello schema di valutazione. Per ulteriori informazioni su come inviare dati personalizzati come parte di una richiesta API, vedere Esempio di dati personalizzati.
Tipi di API che possono essere utilizzati in una chiamata esterna
Prima di creare una chiamata esterna, è necessario conoscere le seguenti limitazioni:
- Attualmente Fraud Protection supporta solo i seguenti metodi di autenticazione: Anonimo e AAD.
- Attualmente Fraud Protection supporta solo i seguenti metodi HTTP: GET e POST.
Crea una chiamata esterna
Nel portale di Fraud Protection, nella barra di navigazione a sinistra selezionare Chiamate esterne e quindi selezionare Nuova chiamata esterna.
Esaminare e impostare i campi seguenti in base alle esigenze.
Nome : immettere il nome che verrà usato per fare riferimento alla chiamata esterna dalle regole. Il nome può contenere solo numeri, lettere e trattini bassi. Non può iniziare con un numero.
Nota
Non è possibile modificare il nome di una chiamata esterna dopo averlo utilizzata in una regola.
Descrizione - Aggiungere una descrizione per aiutare il team a identificare rapidamente la chiamata esterna.
Richiesta web - Selezionare il metodo HTTP appropriato (GET o POST), quindi inserire l'endpoint API.
Nota
Sono supportati solo gli endpoint HTTPS.
Abilitare chiamate di riscaldamento periodiche: se il traffico verso l'endpoint di chiamata esterno è troppo basso, la connessione può andare a freddo e può aumentare la latenza di risposta dal servizio esterno. Per attenuare questo problema, abilitare le chiamate di riscaldamento dalla pagina Configurazione chiamata esterna. Usare l'interruttore per abilitare le chiamate di riscaldamento. È necessario specificare un URL Keep-alive GET valido. Come per l'endpoint primario, anche l'endpoint keep-alive deve superare la connessione di test. Se si configura la chiamata esterna con chiamate di riscaldamento abilitate, quando il volume del traffico aumenta troppo basso, La protezione dalle frodi effettua automaticamente chiamate di riscaldamento anonime all'endpoint keep-alive usando solo il metodo GET.
Nota
Non è possibile usare parametri, configurazioni o intestazioni configurabili nelle chiamate di riscaldamento.
Autenticazione : selezionare il metodo da usare per autenticare le richieste in ingresso.
- Se si seleziona Anonimo, non viene inviata un'intestazione di autorizzazione.
- Se si seleziona AAD, viene generato un token di Azure Active Directory (Azure AD) nel tenant e > bearer viene usato come intestazione di autorizzazione.
Per ulteriori informazioni su autenticazione, autorizzazione e token di Azure AD, vedi la sezione Informazioni sull'autenticazione e sull'autorizzazione più avanti in questo articolo.
Destinatari : se si seleziona AAD come metodo di autenticazione, viene chiesto di fornire un gruppo di destinatari. È possibile usare un'applicazione Azure esistente come gruppo di destinatari o crearne una nuova tramite l'esperienza di integrazione all'interno del portale di Protezione dalle frodi. Assicurarsi che il destinatario disponga dell'autorizzazione per accedere alla chiamata/al servizio esterno. Per ulteriori informazioni su come configurare l'autenticazione di Azure Active Directory (Azure AD), vedere Configurare l'autenticazione di Azure AD.
ID applicazione: è anche necessario specificare l'ID applicazione di un'applicazione Azure AD nuova o esistente all'interno del tenant della sottoscrizione di Fraud Protection. Generare un certificato in Azure Key Vault. L'app Fraud Protection deve disporre dell'accesso in lettura a Azure Key Vault. Caricare il certificato in questa applicazione Azure AD. Per ulteriori informazioni su come creare e gestire applicazioni Azure AD, vedere Creare applicazioni Azure Active Directory.
URL certificato - Specificare l'URL dell'identificatore del certificato di Azure Key Vault. Si tratta del certificato caricato nell'app Azure AD nel passaggio precedente. Per ulteriori informazioni su come generare un certificato in Azure Key Vault, vedere Creazione e unione di una richiesta di firma del certificato in Azure Key Vault
Aggiungi parametro - È possibile utilizzare parametri per trasferire dati da Fraud Protection all'endpoint API. A seconda del metodo HTTP selezionato, questi parametri vengono inviati all'endpoint nella stringa di query o come parte del corpo della richiesta.
È possibile aggiungere valori di esempio per ogni parametro. Fraud Protection usa questi valori di parametro per effettuare una chiamata di esempio all'endpoint, prima della creazione o ogni volta che si seleziona Test.
Nota
Tutti i valori dei parametri vengono interpretati come stringhe.
Esempio di richiesta - Fornire un esempio della richiesta inviata alla chiamata esterna. La richiesta deve riflettere i nomi e i valori dei parametri specificati e non può essere modificata.
Per i metodi GET, viene mostrato l'URL della richiesta. Per i metodi POST, viene mostrato il corpo della richiesta.
L'esempio di richiesta viene utilizzato per effettuare una chiamata di esempio all'endpoint, prima della creazione o ogni volta che si seleziona Test.
Risposta di esempio - Fornire un esempio dei dati restituiti in una risposta riuscita dell'endpoint API. Questi dati devono essere in formato JSON (JavaScript Object Notation) e possono essere referenziati nelle regole. L'esempio fornito qui viene mostrato durante la creazione delle regole.
Selezionare Test per immettere automaticamente una risposta reale dell'API in questo campo.
timeout: specificare per quanto tempo, in millisecondi, la richiesta deve attendere prima del timeout. È necessario specificare un numero compreso tra 1 e 5000.
Risposta predefinita - Specificare la risposta predefinita da restituire se la richiesta non riesce o supera il timeout specificato. Il valore deve essere un oggetto JSON valido o un elemento JSON.
Facoltativo: per inviare una richiesta di esempio all'endpoint API e visualizzare la risposta, selezionare Test. Per ulteriori informazioni, vedere la sezione successiva, Testare una chiamata esterna.
Al termine dell'impostazione dei campi obbligatori, selezionare Crea.
Testare una chiamata esterna
Per assicurarsi che Fraud Protection possa connettersi all'endpoint, testare la connessione in qualsiasi momento.
Per testare una connessione durante la creazione di una nuova chiamata esterna o la modifica di una chiamata esterna esistente, impostare tutti i campi necessari, quindi selezionare Test.
Fraud Protection utilizza l'endpoint ei parametri forniti per inviare una richiesta alla chiamata esterna.
- Se Fraud Protection raggiunge correttamente l'endpoint di destinazione, viene visualizzata una barra dei messaggi verde nella parte superiore del pannello per indicare che la connessione è riuscita. Per visualizzare la risposta completa, selezionare Vedere i dettagli della risposta.
- Se Fraud Protection non riesce a raggiungere l'endpoint di destinazione o se non riceve una risposta prima del timeout specificato, nella parte superiore del pannello viene visualizzata una barra dei messaggi rossa che mostra l'errore riscontrato. Per visualizzare ulteriori informazioni sull'errore, selezionare Vedere i dettagli dell'errore.
Monitorare le chiamate esterne
Monitorare le chiamate esterne nel portale di Fraud Protection
Fraud Protection mostra un riquadro che contiene tre metriche per ogni chiamata esterna definita:
- Richieste al secondo - Il numero totale di richieste diviso per il numero totale di minuti nell'intervallo di tempo selezionato.
- Latenza media: numero totale di latenze delle richieste diviso per il numero totale di minuti nell'intervallo di tempo selezionato.
- Percentuale di esito positivo: numero totale di richieste riuscite divise per il numero totale di richieste effettuate.
I numeri e i grafici visualizzati in questo riquadro includono solo i dati per l'intervallo di tempo selezionato nell'elenco a discesa nell'angolo in alto a destra della pagina.
Nota
Le metriche vengono visualizzate solo quando la chiamata esterna viene utilizzata in una regola attiva.
Per approfondire i dati sulla chiamata esterna, selezionare Prestazioni nell'angolo destro del riquadro.
Fraud Protection mostra una nuova pagina con una visualizzazione più dettagliata delle metriche.
Per visualizzare le metriche per qualsiasi intervallo di tempo negli ultimi tre mesi, regolare l'impostazione Intervallo di date nella parte superiore della pagina.
Oltre alle tre metriche descritte in precedenza, viene visualizzato un grafico Errore. Questo grafico mostra il numero di errori per tipo e codice di errore. Per visualizzare i conteggi degli errori nel tempo o per visualizzare la distribuzione degli errori, selezionare Grafico a torta.
Oltre agli errori del client HTTP (400, 401 e 403), è possibile che vengano visualizzati i seguenti errori:
- ID applicazione non valido - L'ID applicazione fornito non esiste nel tenant o non è valido.
- Errore di AAD - Il token di Azure AD non può essere recuperato.
- Definizione non trovata - La chiamata esterna è stata eliminata, ma è ancora referenziata in una regola.
- Timeout - La richiesta alla destinazione ha richiesto più tempo del timeout specificato.
- Errore di comunicazione - Non è stato possibile stabilire una connessione alla destinazione a causa di un problema di rete o perché la destinazione non è disponibile.
- Interruttore: se la chiamata esterna non è riuscita continuamente e ha superato una determinata soglia, tutte le altre chiamate vengono sospese per un breve intervallo.
- Errore sconosciuto - Si è verificato un errore interno di Dynamics 365.
Utilizzare la traccia di eventi per monitorare le chiamate esterne
È possibile usare la funzionalità di traccia di eventi di Fraud Protection per inoltrare eventi correlati alle chiamate esterne alle proprie istanze di Hub eventi di Azure o Archiviazione BLOB di Azure. Nel portale di Fraud Protection, nella pagina Traccia eventi è possibile iscriversi ai seguenti due eventi relativi alle chiamate esterne:
- FraudProtection.Monitoring.ExternalCalls
- FraudProtection.Errors.ExternalCalls
Ogni volta che viene effettuata una richiesta a una chiamata esterna, viene inviato un evento allo spazio dei nomi FraudProtection.Monitoring.ExternalCalls. Il payload dell'evento include informazioni sulla latenza della chiamata, lo stato della richiesta e la regola e la clausola da cui è stata attivata la richiesta.
Quando una chiamata esterna non riesce, viene inviato un evento allo spazio dei nomi FraudProtection.Errors.ExternalCalls. Il payload dell'evento include il corpo e la richiesta dell'URI inviati alla chiamata esterna e la risposta ricevuta.
Per ulteriori informazioni sulla traccia di eventi, su come iscriversi agli eventi e su cosa è possibile fare con gli eventi, vedere Traccia evento.
Per informazioni su come integrare questi dati con i flussi di lavoro della propria organizzazione e impostare monitoraggio, avvisi e report personalizzati, vedere Estendibilità tramite Hub eventi.
Gestire chiamate esterne
Per modificare una chiamata esterna esistente, selezionare Modifica nell'intestazione della scheda.
Nota
Non è possibile modificare il nome e i parametri di una chiamata esterna dopo averlo utilizzata in una regola.
Per eliminare una chiamata esterna esistente, selezionare i puntini di sospensione (...), quindi selezionare Elimina.
Nota
Non è possibile eliminare una chiamata esterna dopo che è stata referenziata in una regola.
Per visualizzare metriche dettagliate sulle prestazioni per una chiamata esterna, selezionare Prestazioni.
Per verificare che Fraud Protection possa ancora connettersi alla chiamata esterna, selezionare i puntini di sospensione (...), quindi selezionare Test connessione.
Usare una chiamata esterna nelle regole
Per utilizzare chiamate esterne per prendere decisioni, fare riferimento alle regole.
Ad esempio, per fare riferimento a una chiamata esterna denominata myCall nella regola, utilizzare la sintassi seguente:
External.myCall()
Se myCall richiede un parametro, come IPaddress, utilizzare la sintassi seguente:
External.myCall(@"device.ipAddress")
Per informazioni sulla lingua delle regole e su come utilizzare le chiamate esterne nelle regole, vedere la Guida di riferimento linguistico.
Nota
Se in una regola vengono utilizzate chiamate esterne, la latenza della regola potrebbe aumentare.
Comprendere l'autenticazione e l'autorizzazione
Per garantire l'accesso sicuro ai dati, le API spesso autenticano il mittente di una richiesta per verificare che disponga dell'autorizzazione per accedere ai dati. Le chiamate esterne in Fraud Protection supportano due metodi di autenticazione: Anonimo e AAD.
Se si seleziona Anonima, l'intestazione dell'autorizzazione nella richiesta HTTP all'endpoint di destinazione viene lasciata vuota. Utilizzare questa opzione quando l'endpoint di destinazione non richiede un'intestazione di autorizzazione. Ad esempio, se l'endpoint utilizza una chiave API, configura la coppia chiave-valore come parte dell'URL della richiesta immessa nel campo Richiesta web. L'endpoint di destinazione può quindi confermare se la chiave API dell'URL della richiesta è consentita e decidere se concedere l'autorizzazione.
Se si seleziona AAD, l'intestazione di autorizzazione nella richiesta HTTP all'endpoint di destinazione include un token di connessione. Un token di connessione è un token JWT (JSON Web Token) emesso da Azure AD. Per informazioni sui token JWT, vedere Token di accesso alla piattaforma di identità Microsoft. Fraud Protection aggiunge il valore del token al testo "Connessione" nel formato richiesto nell'intestazione dell'autorizzazione della richiesta come mostrato di seguito:
<Token> di connessione
Attestazioni di token
La tabella seguente elenca le attestazioni che possono verificarsi nei token di connessione emessi da Fraud Protection.
| Nome | Attestazione | descrizione |
|---|---|---|
| ID tenant | tid | Questa attestazione identifica l'ID tenant di Azure della sottoscrizione associata all'account di Fraud Protection. Per informazioni su come trovare l'ID tenant nel portale di Fraud Protection, vedere ID e informazioni necessari. Per informazioni su come trovare l'ID tenant nel portale di Azure, vedere Come trovare l'ID del tenant Azure Active Directory. |
| Destinatario | aud | Questa attestazione identifica il destinatario previsto del token. Il valore riflette esattamente l'ID applicazione specificato quando è stata configurata la chiamata esterna nel portale di Protezione dalle frodi. |
| ID domanda di lavoro | appid | Questa attestazione è l'ID applicazione di Fraud Protection: * bf04bdab-e06f-44f3-9821-d3af64fc93a9*. Questo ID è di proprietà esclusiva di Fraud Protection e solo Microsoft può richiedere un token per suo conto. |
Quando l'API riceve un token, deve aprire il token e convalidare che ciascuna delle attestazioni precedenti corrisponda alla relativa descrizione.
Di seguito è riportato un esempio che mostra come autenticare una richiesta in arrivo utilizzando 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.");
}
Pratiche relative a dati esterni
L'utente riconosce di essere responsabile dell'adesione a tutte le leggi e i regolamenti applicabili, incluse, a titolo esemplificativo, le leggi sulla protezione dei dati, le restrizioni contrattuali e/o le politiche relative ai set di dati forniti a Microsoft tramite la funzione Chiamate esterne di Fraud Protection. Inoltre, l'utente riconosce che l'utilizzo di Fraud Protection è soggetto alle limitazioni d'uso descritte in dettaglio nel Contratto con il cliente Microsoft, in cui si afferma che non è possibile utilizzare Fraud Protection (i) come unico fattore nel determinare se procedere con una transazione di pagamento; (ii) come fattore nel determinare la situazione finanziaria, la storia finanziaria, l'affidabilità creditizia o l'idoneità di qualsiasi persona per assicurazione, alloggio o occupazione; oppure (iii) per prendere decisioni che producono effetti giuridici o incidono in modo significativo su una persona. È inoltre vietato fornire o utilizzare in altro modo tipi di dati sensibili o altamente regolamentati in relazione al proprio utilizzo della funzionalità Chiamate esterne di Fraud Protection. È necessario esaminare qualsiasi set di dati o tipi di dati prima di usarli con la funzionalità chiamate esterne di Protezione dalle frodi per assicurarsi di essere conformi a questo provisioning. Microsoft si riserva inoltre il diritto di verificare la conformità dell'utente con questa disposizione.