Externa anrop
Med externa anrop kan du mata in data från API:er utanför Microsoft Dynamics 365 Fraud Protection och sedan använda dessa data för att fatta välgrundade beslut i realtid. Till exempel kan adress- och telefonverifieringstjänster från tredje part, eller dina egna anpassade bedömningsmodeller, ge kritiska indata som hjälper till att fastställa risknivån för vissa händelser. Genom att använda externa anrop kan du ansluta till valfri API-slutpunkt, göra en begäran till slutpunkten från din regel efter behov och använda svaret från slutpunkten för att fatta ett beslut.
Kommentar
Om dessa ytterligare data behövs för alla händelser kan du även skicka dem som en del av utvärderingsschemat. Mer information om hur du skickar anpassade data som en del av en API-begäran finns i Exempel på anpassade data.
Typer av API:er som kan användas i ett externt anrop
Innan du skapar ett externt anrop bör du känna till följande begränsningar:
- Bedrägeriskydd stöder för närvarande endast följande autentiseringsmetoder: Anonym och AAD.
- Bedrägeriskydd stöder för närvarande endast följande HTTP-metoder: GET och POST.
Skapa ett externt anrop
I det vänstra navigeringsfönstret i bedrägeriskyddsportalen väljer du Externa anrop och sedan Nytt externt anrop.
Granska och ange följande fält efter behov.
Namn – Ange det namn som du ska använda för att referera till det externa anropet från dina regler. Namnet får bara innehålla siffror, bokstäver och understreck. Det kan inte börja med ett tal.
Kommentar
Du kan inte ändra namnet på ett externt anrop när du har använt det i en regel.
Beskrivning – Lägg till en beskrivning som hjälper ditt team att snabbt identifiera det externa anropet.
Webbbegäran – Välj lämplig HTTP-metod (GET eller POST) och ange sedan API-slutpunkten.
Kommentar
Endast HTTPS-slutpunkter stöds.
Aktivera periodiska uppvärmningsanrop – Om trafiken till den externa samtalsslutpunkten är för låg kan anslutningen bli kall och kan öka svarstiden från den externa tjänsten. Du kan åtgärda det här problemet genom att aktivera uppvärmningsanrop från sidan Konfiguration av externt samtal. Använd reglaget för att aktivera uppvärmningssamtal. Du måste ange en giltig GET Keep-alive-URL. Precis som med den primära slutpunkten måste keep-alive-slutpunkten också klara testanslutningen. Om du konfigurerar ditt externa samtal med uppvärmningsanrop aktiverade, när din trafikvolym sjunker för lågt, gör Fraud Protection automatiskt anonyma uppvärmningsanrop till slutpunkten keep-alive med endast GET-metoden.
Kommentar
Inga parametrar, konfigurationer eller konfigurerbara rubriker kan användas i uppvärmningsanrop.
Autentisering – Välj den metod som ska användas för att autentisera inkommande begäranden.
- Om du väljer Anonym skickas inte ett auktoriseringshuvud.
- Om du väljer AAD genereras en Azure Active Directory-token (Azure AD) i klientorganisationen och ägartoken <> används som auktoriseringshuvud.
Mer information om autentisering, auktorisering och Azure AD-token finns i avsnittet Förstå autentisering och auktorisering senare i den här artikeln.
Målgrupp – Om du väljer AAD som autentiseringsmetod uppmanas du att ange en målgrupp. Du kan använda ett befintligt Azure-program som målgrupp eller skapa ett nytt via integreringsupplevelsen i Bedrägeriskyddsportalen. Kontrollera att målgruppen har behörighet att komma åt det externa samtalet/tjänsten. Mer information om hur du konfigurerar Azure Active Directory-autentisering (Azure AD) finns i Konfigurera Azure AD-autentisering.
Program-ID – Du måste också ange program-ID för ett nytt eller befintligt Azure AD-program i din klientorganisation för bedrägeriskyddsprenumeration. Generera ett certifikat i Azure Key Vault. Bedrägeriskyddsappen bör ha läsbehörighet till det här Azure Key Vault. Läs in certifikatet till det här Azure AD-programmet. Mer information om hur du skapar och hanterar Azure AD-program finns i Skapa Azure Active Directory-program.
Certifikat-URL – Ange url:en för certifikatidentifieraren från ditt Azure Key Vault. Det här är samma certifikat som du läste in i Azure AD-appen i föregående steg. Mer information om hur du genererar ett certifikat i Azure Key Vault finns i Skapa och slå samman en begäran om certifikatsignering i Azure Key Vault
Lägg till parameter – Du kan använda parametrar för att skicka data från Bedrägeriskydd till API-slutpunkten. Beroende på vilken HTTP-metod du väljer skickas dessa parametrar till slutpunkten antingen i frågesträngen eller som en del av begärandetexten.
Du kan lägga till exempelvärden för varje parameter. Bedrägeriskydd använder dessa parametervärden för att göra ett exempelanrop till slutpunkten, antingen innan du skapar eller när du väljer Testa.
Kommentar
Alla parametervärden tolkas som strängar.
Exempelbegäran – Ange ett exempel på den begäran som skickas till ditt externa anrop. Begäran bör återspegla de parameternamn och värden som du har angett och kan inte redigeras.
För GET-metoder visas begärande-URL:en. För POST-metoder visas begärandetexten.
Exempelbegäran används för att göra ett exempelanrop till slutpunkten, antingen innan du skapar eller när du väljer Testa.
Exempelsvar – Ange ett exempel på de data som returneras i ett lyckat svar från API-slutpunkten. Dessa data ska vara i JSON-format (JavaScript Object Notation) och kan refereras till i dina regler. Exemplet som du anger här visas när du skapar regler.
Välj Testa för att automatiskt ange ett verkligt svar från api:et i det här fältet.
timeout- – Ange hur länge, i millisekunder, begäran ska vänta innan tidsgränsen uppnås. Du måste ange ett tal mellan 1 och 5 000.
Standardsvar – Ange det standardsvar som ska returneras om din begäran misslyckas eller överskrider den angivna tidsgränsen. Värdet måste vara ett giltigt JSON-objekt eller JSON-element.
Valfritt: Om du vill skicka en exempelbegäran till API-slutpunkten och visa svaret väljer du Testa. Mer information finns i nästa avsnitt, Testa ett externt anrop.
När du har angett de obligatoriska fälten väljer du Skapa.
Testa ett externt anrop
Testa anslutningen när som helst för att säkerställa att Bedrägeriskydd kan ansluta till slutpunkten.
Om du vill testa en anslutning när du skapar ett nytt externt anrop eller redigerar ett befintligt externt anrop anger du alla obligatoriska fält och väljer sedan Testa.
Bedrägeriskydd använder slutpunkten och parametrarna som du angav för att skicka en begäran till ditt externa anrop.
- Om Bedrägeriskydd når målslutpunkten visas ett grönt meddelandefält överst i panelen för att informera dig om att anslutningen lyckades. Om du vill visa det fullständiga svaret väljer du Se svarsinformation.
- Om Bedrägeriskydd inte kan nå målslutpunkten, eller om det inte får något svar före den angivna tidsgränsen, visas ett rött meddelandefält överst i panelen och visar felet som påträffades. Om du vill visa mer information om felet väljer du Se felinformation.
Övervaka externa anrop
Övervaka externa anrop i bedrägeriskyddsportalen
Bedrägeriskydd visar en panel som innehåller tre mått för varje externt anrop som du definierar:
- Begäranden per sekund – Det totala antalet begäranden dividerat med det totala antalet minuter under den valda tidsramen.
- Genomsnittlig svarstid – Det totala antalet svarstider för begärande dividerat med det totala antalet minuter inom den valda tidsramen.
- Lyckad frekvens – det totala antalet lyckade begäranden dividerat med det totala antalet begäranden som görs.
De siffror och diagram som visas på den här panelen innehåller endast data för den tidsram som du väljer i listrutan i det övre högra hörnet på sidan.
Kommentar
Mått visas endast när ditt externa anrop används i en aktiv regel.
Om du vill fördjupa dig i data om ditt externa anrop väljer du Prestanda i panelens högra hörn.
Bedrägeriskydd visar en ny sida med en mer detaljerad vy över måtten.
Om du vill visa mått för en tidsram under de senaste tre månaderna justerar du inställningen Datumintervall överst på sidan.
Förutom de tre mått som beskrevs tidigare visas ett feldiagram . Det här diagrammet visar antalet fel efter feltyp och kod. Om du vill visa antalet fel över tid eller om du vill visa fördelningen av fel väljer du Cirkeldiagram.
Förutom HTTP-klientfel (400, 401 och 403) kan följande fel visas:
- Ogiltigt program-ID – det program-ID som angavs finns inte i din klientorganisation eller så är det inte giltigt.
- AAD-fel – Azure AD-token kunde inte hämtas.
- Det går inte att hitta definitionen – det externa anropet har tagits bort, men det refereras fortfarande till i en regel.
- Tidsgräns – Begäran till målet tog längre tid än den angivna tidsgränsen.
- Kommunikationsfel – Det gick inte att upprätta någon anslutning till målet på grund av ett nätverksproblem eller på grund av att målet inte är tillgängligt.
- Kretsbrytare – Om det externa anropet har misslyckats kontinuerligt och har överskridit ett visst tröskelvärde, pausas alla ytterligare anrop under ett kort intervall.
- Okänt fel – Ett internt Dynamics 365-fel inträffade.
Använda händelsespårning för att övervaka externa anrop
Du kan använda funktionen för spårning av bedrägerier för att vidarebefordra händelser som är relaterade till dina externa anrop till dina egna instanser av Azure Event Hubs eller Azure Blob Storage. På sidan Händelsespårning i bedrägeriskyddsportalen kan du prenumerera på följande två händelser som är relaterade till externa anrop:
- FraudProtection.Monitoring.ExternalCalls
- FraudProtection.Errors.ExternalCalls
När en begäran görs till ett externt anrop skickas en händelse till namnområdet FraudProtection.Monitoring.ExternalCalls. Händelsenyttolasten innehåller information om svarstiden för anropet, begärandestatus och regeln och satsen som begäran utlöstes från.
När ett externt anrop misslyckas skickas en händelse till namnområdet FraudProtection.Errors.ExternalCalls. Händelsenyttolasten innehåller URI-begäran och brödtexten som skickades till det externa anropet och det svar som togs emot.
Mer information om händelsespårning, hur du prenumererar på händelser och vad du kan göra med händelser finns i Händelsespårning.
Information om hur du integrerar dessa data med din egen organisations arbetsflöden och konfigurerar anpassad övervakning, aviseringar och rapportering finns i Utökningsbarhet via Event Hubs.
Hantera externa anrop
Om du vill redigera ett befintligt externt anrop väljer du Redigera i kortrubriken.
Kommentar
Du kan inte ändra namn och parametrar för ett externt anrop när du har använt det i en regel.
Om du vill ta bort ett befintligt externt anrop väljer du ellipsen (...) och väljer sedan Ta bort.
Kommentar
Du kan inte ta bort ett externt anrop när det har refererats till i en regel.
Om du vill visa detaljerade prestandamått för ett externt anrop väljer du Prestanda.
Om du vill testa att Bedrägeriskydd fortfarande kan ansluta till ditt externa anrop väljer du ellipsen (...) och väljer sedan Testa anslutning.
Använda ett externt anrop i regler
Om du vill använda dina externa anrop för att fatta beslut refererar du till dem från dina regler.
Om du till exempel vill referera till ett externt anrop med namnet myCall i din regel använder du följande syntax:
External.myCall()
Om myCall kräver en parameter, till exempel IPaddress, använder du följande syntax:
External.myCall(@"device.ipAddress")
Information om regelspråket och hur du kan använda externa anrop i regler finns i språkreferensguiden.
Kommentar
Om externa anrop används i en regel kan svarstiden för regeln öka.
Förstå autentisering och auktorisering
För att säkerställa säker åtkomst till data autentiserar API:er ofta avsändaren av en begäran för att verifiera att de har behörighet att komma åt data. Externa anrop i Bedrägeriskydd stöder två autentiseringsmetoder: Anonym och AAD.
Om du väljer Anonym lämnas auktoriseringshuvudet i HTTP-begäran till målslutpunkten tomt. Använd det här alternativet när målslutpunkten inte kräver ett auktoriseringshuvud. Om slutpunkten till exempel använder en API-nyckel konfigurerar du nyckel/värde-paret som en del av begärande-URL:en som du anger i fältet Webbbegäran . Målslutpunkten kan sedan verifiera om API-nyckeln från begärande-URL:en tillåts och sedan bestämma om behörighet ska beviljas.
Om du väljer AAD innehåller auktoriseringshuvudet i HTTP-begäran till målslutpunkten en ägartoken. En ägartoken är en JSON-webbtoken (JWT) som utfärdas av Azure AD. Information om JWT finns i Microsofts identitetsplattform åtkomsttoken. Bedrägeriskydd lägger till tokenvärdet i texten "Bearer" i det format som krävs i begärandeauktoriseringshuvudet enligt följande:
<Ägartoken>
Tokenanspråk
I följande tabell visas de anspråk som du kan förvänta dig i ägartoken som utfärdas av Bedrägeriskydd.
| Name | Anspråk | beskrivning |
|---|---|---|
| Klientorganisations-ID | tid | Det här anspråket identifierar Azure-klientorganisations-ID:t för den prenumeration som är associerad med ditt bedrägeriskyddskonto. Information om hur du hittar ditt klient-ID i bedrägeriskyddsportalen finns i Obligatoriska ID:er och information. Information om hur du hittar ditt klient-ID i Azure Portal finns i Så här hittar du ditt Azure Active Directory-klient-ID. |
| Målgrupp | Aud | Det här anspråket identifierar den avsedda mottagaren av token. Värdet återspeglar exakt det program-ID som du angav när du konfigurerade ditt externa anrop i bedrägeriskyddsportalen. |
| Program-ID:t | appid | Detta påstående är Bedrägeriskydds program-ID: * bf04bdab-e06f-44f3-9821-d3af64fc93a9*. Det här ID:t ägs enbart av Bedrägeriskydd och endast Microsoft kan begära en token för dess räkning. |
När ditt API tar emot en token bör den öppna token och verifiera att vart och ett av de föregående anspråken matchar dess beskrivning.
Här är ett exempel som visar hur du kan autentisera en inkommande begäran med hjälp av 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.");
}
Metoder för externa data
Du bekräftar att du ansvarar för att följa alla tillämpliga lagar och förordningar, inklusive dataskyddslagar, avtalsbegränsningar och/eller principer som rör datamängder som du tillhandahåller Microsoft via funktionen Externa samtal i Bedrägeriskydd. Dessutom bekräftar du att din användning av bedrägeriskydd är föremål för användningsbegränsningar som beskrivs i Microsoft-kundavtal, som anger att du inte får använda Bedrägeriskydd (i) som den enda faktorn för att avgöra om du ska fortsätta med en betalningstransaktion; ii) som en faktor för att fastställa en persons ekonomiska status, finansiella historia, kreditvärdighet eller berättigande till försäkring, bostad eller anställning, eller (iii) att fatta beslut som ger upphov till rättsliga effekter eller väsentligt påverkar en person. Du är också förbjuden att tillhandahålla eller på annat sätt använda känsliga eller strikt reglerade datatyper i samband med din användning av funktionen för externa anrop i Bedrägeriskydd. Ta dig tid att granska datamängder eller datatyper innan du använder dem med funktionen för externa anrop i Bedrägeriskydd för att säkerställa att du är kompatibel med den här etableringen. Microsoft förbehåller sig också rätten att kontrollera att du är kompatibel med den här etableringen.