Valutazioni esterne

La valutazione esterna è un meccanismo per richiamare una valutazione da qualsiasi altra valutazione. Una valutazione esterna non è una valutazione stessa. Funziona invece come una fonte di dati che consente di inviare dati e ricevere una risposta da una valutazione di destinazione. Una valutazione può avere una delle due possibili impostazioni di condivisione:

• Privato: accessibile solo nell'ambiente radice della valutazione.
• Condiviso: accessibile in tutti gli ambienti nel tenant.

Le valutazioni esterne possono puntare a qualsiasi valutazione privata disponibile nello stesso ambiente radice o a qualsiasi valutazione condivisa disponibile in qualsiasi ambiente radice del tenant.

Nota

Per altre informazioni su come modificare l'impostazione Condivisione di una valutazione da Privato a Condiviso o Condiviso a Privato, vedere Panoramica della configurazione della valutazione.

Dopo aver configurato una valutazione esterna, può essere chiamata tramite una regola di qualsiasi valutazione in tale ambiente.

Per valutazione privata: Ambiente Y = Ambiente X

Per valutazione condivisa: Ambiente Y = qualsiasi ambiente radice all'interno dello stesso tenant

Una valutazione chiamante si riferisce a qualsiasi valutazione che chiama una valutazione privata o condivisa tramite una valutazione esterna. La valutazione chiamante deve avere una regola di valutazione esterna configurata. Quando viene soddisfatta la condizione della regola, la regola chiamerà la valutazione esterna ed eseguirà le azioni configurate. Analogamente alle chiamate esterne, le valutazioni esterne non vengono ereditate dagli elementi figlio. Per usare una valutazione esterna in una regola, è necessario configurare la valutazione esterna nell'ambiente da cui si vuole chiamarla.

Creare una valutazione esterna

Per creare una valutazione esterna, assicurarsi prima di tutto di disporre dell'autorizzazione corretta per eseguire questa operazione. Per altre informazioni sui ruoli utente e sulle autorizzazioni, vedere Ruoli utente e accesso

1. Nel portale di Fraud Protection, nella barra di navigazione a sinistra seleziona Valutazioni esterne, quindi + Nuova valutazione esterna.
2. Nella pagina Nuova valutazione esterna, imposta i seguenti campi:

• Valutazione di destinazione da chiamare : nell'elenco a discesa è possibile visualizzare tutte le valutazioni private, configurare nello stesso ambiente radice, nonché eventuali valutazioni condivise disponibili, configurate in qualsiasi ambiente radice dello stesso tenant. Seleziona la valutazione che desideri scegliere come destinazione.

Nota

Se la valutazione condivisa a cui si vuole puntare la valutazione esterna non viene visualizzata nell'elenco a discesa, controllare l'impostazione Condivisione della valutazione e assicurarsi che sia impostata su Condiviso. Per altre informazioni su come configurare l'impostazione Condivisione , vedere Panoramica della configurazione della valutazione.

• Nome: immetti il nome che si utilizzerà per fare riferimento alla valutazione 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 valutazione esterna dopo averlo utilizzata in una regola.

• Descrizione: aggiungi una descrizione per aiutare il team a identificare rapidamente la valutazione esterna.
• API per anteprima : seleziona l'API per cui si desideri visualizzare l'anteprima del codice di esempio. Il codice di esempio è l'FQL che puoi usare in una regola per richiamare questa valutazione condivisa

Nota

È possibile usare la valutazione esterna per chiamare l'API di valutazione, osservazione o etichetta della valutazione condivisa o privata a cui punta.

• Risposta di esempio: questa sezione contiene la risposta di esempio prevista dalla valutazione di destinazione. Le informazioni visualizzate vengono fornite manualmente dall'amministratore della valutazione di destinazione e vengono usate per abilitare descrizioni (descrizioni comando) e suggerimenti per il completamento automatico quando viene fatto riferimento alla valutazione in una regola.

3. Al termine dell'impostazione dei campi obbligatori, selezionare Crea.

Chiamare una valutazione esterna

Per utilizzare valutazioni esterne, fare riferimento alle regole. Ad esempio, per fare riferimento a una valutazione esterna denominata myAssessment nella regola, utilizzare la sintassi seguente:

Assessments.myAssessment.Evaluate($baseInput = @@)

Nell'esempio precedente, $baseInput = @@mapperà tutti i campi necessari per la valutazione condivisa/esterna dal payload della valutazione chiamante. Puoi anche mappare solo campi specifici. Puoi anche definire quali azioni vuoi che la regola intraprenda in base alle informazioni che riceverà dalla chiamata di valutazione esterna.

Ad esempio:

LET $card = {
  number: 12345,
  expy: "2023-03-10".ToDateTime()
}
LET $response = Assessments.MicroTx.evaluate(card = $card, user = @@"user")
OBSERVE Output(decision = $response.decisionDetails.merchantRuleDecision)

Puoi impostare una regola per richiamare la valutazione esterna utilizzando il modello di regola Utilizza una valutazione esterna o copiando e incollando l'FQL di esempio dalla pagina della valutazione esterna. Assicurarsi di usare il codice di esempio per l'API (valutare, osservare, etichetta) che si vuole chiamare. Il codice di esempio mostrerà tutti i campi che possono essere inviati alla valutazione condivisa. I campi obbligatori sono contrassegnati come tali nel codice.

Ecco un altro FQL di esempio per chiamare l'API di valutazione della valutazione esterna denominata ExtAssessment1:

LET $customUser = {
    id: "userId123456",
    username: "johnsmith2",
    firstName: "John",
    lastName: "Smith",
    email: "johnsmith2@gmail.com",
    address: {
        street1: "0123 Bechtelar Loop",
        city: "Kubtown",
        state: "SC",
        zipCode: "44329",
        countryRegion: "US"
    }
}

LET $result = Assessments.ExtAssessment1.Evaluate(
    user = $customUser,
    specialConsideration = true)
OBSERVE Output(Result = $result)

È anche possibile accedere all'oggetto di diagnostica nelle regole, che consente di individuare informazioni di diagnostica e debug importanti dalla risposta di una valutazione esterna. L'oggetto diagnostics contiene il payload request, il codice HttpStatus, il messaggio di errore e la latenza. L'oggetto diagnostics deve essere creato per primo usando il metodo di estensione corrispondente, ". GetDiagnostics()", prima che i campi dell'oggetto possano essere usati nelle regole.

Di seguito è riportato un esempio di regola che usa l'oggetto diagnostics nella risposta di una valutazione esterna denominata ExtAssessment2:

LET $result = Assessments.ExtAssessment2.evaluate($baseInput =@@)
LET $diagnostics = $result.GetDiagnostics()
RETURN Approve(), Output (Diagnostics = $diagnostics)
WHEN $diagnostics.httpStatusCode==200

Le chiamate esterne e le valutazioni esterne possono richiedere oggetti strutturati complessi come parte dello schema di richiesta. Per altre informazioni su come usare matrici e oggetti JSON, vedere la Guida di riferimento al linguaggio.

Nota

È anche possibile fare riferimento alle valutazioni esterne all'interno di Funzioni. Per altre informazioni, vedere Funzioni.

Monitorare le valutazioni esterne nel portale di Protezione dalle frodi

Fraud Protection mostra un riquadro che contiene tre metriche per ogni valutazione esterna definita:

• Richieste al secondo - Il numero totale di richieste diviso per il numero totale di minuti nell'intervallo di tempo selezionato.
• Latenza media - Il numero totale di 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 valutazione esterna viene utilizzata in una regola attiva.

• Per approfondire i dati sulla valutazione esterna, seleziona 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 Microsoft Entra: non è stato possibile recuperare il token Microsoft Entra.
• Definizione non trovata : la chiamata esterna è stata eliminata, ma viene ancora fatto riferimento a 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.