Integrera API:er för köpskydd

Artikel
05/20/2024

Den här artikeln beskriver hur du integrerar API:er (Application Programming Interfaces) i realtid i Microsoft Dynamics 365 Fraud Protection.

Om du vill dra nytta av hela paketet med funktioner för bedrägeriskydd måste du skicka dina transaktionsdata till API:erna för bedrägeriskydd i realtid. När du skickar dina transaktionsdata kan du analysera resultatet av att använda Bedrägeriskydd. I skyddsmiljön kan du också respektera beslut baserat på de regler som du har konfigurerat.

Beroende på hur du använder Bedrägeriskydd kan du använda olika uppsättningar av följande API:er för köpskydd:

Köpa
PurchaseStatus
BankEvent
Betalningsmodell baserad på faktisk förbrukning
Återbetalning
UpdateAccount
Etikett

API-integreringsfaser

Integreringen av API:er för köpskydd sker i tre faser:

Skapa Microsoft Entra-program via Bedrägeriskydd.
Generera en åtkomsttoken.
Anropa API:erna.

Viktigt!

Du måste vara global administratör i din Azure-klient för att slutföra den första inloggningen.

Besök följande portaler för varje miljö som du tänker använda. Logga in och godkänn villkoren om du uppmanas att göra det.

Sandbox-miljö
Produktionsmiljö (Du kanske redan har slutfört det här steget i produktionen under den första registreringen.)

Skapa Microsoft Entra-program

Viktigt!

Du måste vara programadministratör, molnprogramadministratör eller global administratör i Din Azure-klientorganisation för att slutföra det här steget.

Om du vill hämta de token som krävs för att anropa API:erna måste du konfigurera och använda Microsoft Entra-program enligt beskrivningen i det här avsnittet.

Konfigurera Microsoft Entra-program

Följ dessa steg för att konfigurera Microsoft Entra-program.

I den vänstra navigeringsfönstret i bedrägeriskyddsportalen väljer du Integrering > Skapa Microsoft Entra-programinstallation > nu.
Slutför sidan för att skapa din app. Vi rekommenderar att du skapar ett Microsoft Entra-program för varje miljö som du vill integrera med Bedrägeriskydd.
Ange eller välj värden för följande obligatoriska fält:
- Programvisningsnamn – Ge programmet ett beskrivande namn. Den maximala längden är 93 tecken.
- Autentiseringsmetod – Välj om du vill autentisera via ett certifikat eller en hemlighet (lösenord).
Följ dessa steg om du har valt certifikatautentiseringsmetoden:
1. Välj Välj fil för att ladda upp den offentliga nyckeln. (Den matchande privata nyckeln krävs när du hämtar token.)
2. Välj Hemlighet för att automatiskt generera ett lösenord när programmet har skapats.
När du har angett de obligatoriska fälten väljer du Skapa program. Bekräftelsesidan sammanfattar appens namn, ID och certifikatets tumavtryck eller hemlighet, beroende på vilken autentiseringsmetod du har valt.

Viktigt!

Spara information om ditt hemlighets- eller certifikattumavtryck för framtida referens. Hemligheten visas bara en gång.

Skapa ett annat program

Om du vill skapa ett annat program väljer du Skapa ett annat program. Du kan skapa så många appar som du behöver för att köra API-anrop i var och en av dina miljöer.

Hantera befintliga Microsoft Entra-program

När du har skapat dina Microsoft Entra-appar kan du hantera dem via [Azure Portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Mer information finns i Hur och varför program läggs till i Microsoft Entra-ID.

Generera en åtkomsttoken

Om du vill integrera dina system på ett säkert sätt med Bedrägeriskydd hämtar du en Microsoft Entra-token och anger den i rubriken för varje API-anrop.

Kommentar

Åtkomsttoken har en begränsad livslängd på 60 minuter. Vi rekommenderar att du cachelagrar och återanvänder en token tills den snart upphör att gälla. Du kan sedan hämta en ny åtkomsttoken.

Följande information behövs för att hämta en token.

Nödvändiga ID:ar och information

Miljö-URI – URI:er för sandbox-miljön eller produktionsmiljön visas på fliken Konfiguration på sidan API Management i bedrägeriskyddsportalen.
Katalog-ID (klientorganisation) – det här ID:t är den globalt unika identifieraren (GUID) för en klientorganisations domän i Azure. Den visas i Azure-portalen och på fliken Konfiguration på sidan API Management i bedrägeriskyddsportalen.
Program-ID (klient) – Det här ID:t identifierar Microsoft Entra-appen som du har skapat för att anropa API:er. Hämta ID:t från bekräftelsesidan för API:er i realtid eller hitta det senare under Appregistreringar i Azure-portalen. Det kommer att finnas ett ID för varje app som du har skapat.
Certifikatets tumavtryck eller hemlighet – Hämta tumavtrycket eller hemligheten från bekräftelsesidan för API:er i realtid.
Instans-ID – det här ID:t är GUID för din miljö i Bedrägeriskydd. Den visas i integrationspanelen på instrumentpanelen för bedrägeriskydd.

Exempel: Kodexempel som visar hur du hämtar en token med hjälp av ditt certifikat eller din hemlighet

Följande C#-kodexempel innehåller exempel på hur du hämtar en token med ditt certifikat eller din hemlighet. Ersätt platshållarna med din specifika information. För båda C#-exemplen måste du importera NuGet-paketet Microsoft.Identity.Client.

Exempel på andra språk https://aka.ms/aaddevfinns i .

Hämta en åtkomsttoken med hjälp av ett app-ID och en privat certifikatnyckel

/// <summary>
/// Gets an access token using an app ID and private certificate key.
/// </summary>
/// <param name="tenantId">Directory (tenant) ID, in GUID format</param>
/// <param name="clientId">Application (client) ID</param>
/// <param name="certPath">File path to the certificate file (pfx) used to authenticate your application to Microsoft Entra ID</param>
/// <param name="certPassword">Password to access to the certificate file's private key</param>
public async Task<string> AcquireTokenWithCertificate(string tenantId, string clientId, string certPath, string certPassword)
{
    var certificate = new X509Certificate2(certPath, certPassword);

    var app = ConfidentialClientApplicationBuilder.Create(clientId)
            .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
            .WithCertificate(certificate)
            .Build();

    var scopes = new string[] { "<API endpoint for INT or PROD>; should be https://api.dfp.microsoft-int.com/.default or https://api.dfp.microsoft.com/.default" };

    try
    {
        var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
        return result.AccessToken;
    }
    catch (MsalServiceException ex)
    {
        //Handle authentication exceptions
        throw ex;
    }
}

Hämta en åtkomsttoken med hjälp av ett app-ID och en hemlighet

/// <summary>
/// Gets an access token using an app ID and secret.
/// </summary>
/// <param name="tenantId">Directory (tenant) ID, in GUID format</param>
/// <param name="clientId">Application (client) ID</param>
/// <param name="clientSecret">The secret (password) used to authenticate the client (application) ID</param>
public async Task<string> AcquireTokenWithSecret(string tenantId, string clientId, string clientSecret)

{
    var app = ConfidentialClientApplicationBuilder.Create(clientId)
            .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
            .WithClientSecret(clientSecret)
            .Build();

    var scopes = new string[] { "<API endpoint for INT or PROD>; should be https://api.dfp.microsoft-int.com/.default or https://api.dfp.microsoft.com/.default" };

    try
    {
        var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
        return result.AccessToken;
    }
    catch (MsalServiceException ex)
    {
        //Handle authentication exceptions
        throw ex;
    }
}

AuthenticationResult-objektet i varje fall innehåller värdet AccessToken och egenskapen ExpiresOn som anger när token blir ogiltig.

POST-begäran till:
- https://login.microsoftonline.com/<Microsoft Entra tenant ID>/oauth2/token
Sidhuvuden:
- Innehållstyp: application/x-www-form-urlencoded
Brödtext (nyckelvärde):
- grant_type: client_credentials
- client_id: {Ditt klient-ID från föregående steg}
- client_secret: {Din hemlighet från föregående steg}
- resurs: https://api.dfp.microsoft.com (för int, https://api.dfp.microsoft-int.com)
Svar:
- Använd värdet för access_token från svaret för nästa steg.

Mer information finns i följande Azure-dokumentation:

Anropa API:erna

Följ dessa steg för att anropa API:erna.

Skicka följande nödvändiga HTTP-huvuden för varje begäran.

Huvudnamn	Huvudvärde
Auktorisering	Använd följande format för den här rubriken. (Ersätt accesstoken med det faktiska tokenvärdet som returneras av Microsoft Entra-ID.) Bearer accesstoken
x-ms-correlation-id	Skicka ett nytt GUID-värde för varje uppsättning API-anrop som görs tillsammans.
x-ms-dfpenvid	Skicka GUID-värdet för ditt instans-ID.

Huvudnamn

Huvudvärde

Auktorisering

Använd följande format för den här rubriken. (Ersätt accesstoken med det faktiska tokenvärdet som returneras av Microsoft Entra-ID.)

Bearer accesstoken

x-ms-correlation-id

Skicka ett nytt GUID-värde för varje uppsättning API-anrop som görs tillsammans.

x-ms-dfpenvid

Skicka GUID-värdet för ditt instans-ID.

Generera en händelsebaserad nyttolast. Fyll i händelsedata med relevant information från systemet. Dokumentation om alla händelser som stöds finns i Dynamics 365 Fraud Protection API.
Kombinera huvudet (som innehåller åtkomsttoken) och nyttolasten och skicka dem sedan till din bedrägeriskyddsslutpunkt.
- POST-begäran till:
  - <Base URL>/v1.0/merchantservices/events/purchase
- Sidhuvuden:
  - x-ms-correlation-id: {A GUID, som måste vara unikt per begäran}
  - content-type: application/json
  - Auktorisering: {Token från föregående steg}
  - x-ms-dfpenvid: {Miljö-ID för målmiljön}
- Brödtext:
  - Hämta exempeltexten för kontoskyddsbegäran från den delade Swagger-sidan.

Kommentar

Om du skapar en ny miljö ska du inkludera miljö-ID:t i API-huvudet under integreringen, så att transaktionerna kan dirigeras korrekt.

Följande alternativ är acceptabla för x-ms-dfpenvid i API-anropet och beteendet är identiskt.

Använd miljö-ID:t för den miljö som du anropar. ID:t visas på sidan Integrering i fältet Miljö-ID .
Använd den fullständiga klappen för kundens API-ID från roten till den underordnade miljö som du anropar med snedstrecket (/) som avdelare. Till exempel /primary/XYZ.
Använd den fullständiga sökvägen för miljö-ID:t eller kundens API-ID från roten till den underordnade miljö som du anropar med snedstrecket () som snedstreck (/) som avdelare. Till exempel 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Information om hur du anger kundens API-ID när du skapar en miljö finns i artikeln Hantera miljöer.

Bästa praxis

Varje Microsoft Entra-token förblir giltig i 60 minuter. Vi rekommenderar att du cachelagrade den under en kortare tid och återanvänder den.
Kontrollera att din HttpClient har keep-alive-anslutningar.
Skicka alltid rubriken x-ms-dfpenvid och se till att den pekar på miljön för den handlare som du vill skicka transaktioner för.
Lagra hemligheten i en hemlig butik.
Skicka alltid rubriken x-ms-correlation-id för framtida felsökningssessioner med Bedrägeriskydd.
Kontrollera att rubriken x-ms-correlation-id är unik för varje transaktion som skickas till Bedrägeriskydd.

Visa exempelappen

Om du vill ha mer information kan du visa exempelappen och den medföljande utvecklardokumentationen. Exempelappen innehåller ett exempel på hur du anropar API:er för bedrägeriskydd, inklusive API-händelser som att skicka kundkontouppdateringar, återbetalningar och återbetalningar i realtid. Dokumentationen för exempelappen är länkad till den faktiska exempelkoden när sådana länkar är möjliga. Annars finns kodexempel direkt i dokumentationen.

Vägledning om hur du konfigurerar exempelplatsen för din användning finns i Konfigurera exempelwebbplatsen.

Dela via

Integrera API:er för köpskydd

API-integreringsfaser

Skapa Microsoft Entra-program

Konfigurera Microsoft Entra-program

Skapa ett annat program

Hantera befintliga Microsoft Entra-program

Generera en åtkomsttoken

Nödvändiga ID:ar och information

Exempel: Kodexempel som visar hur du hämtar en token med hjälp av ditt certifikat eller din hemlighet

Hämta en åtkomsttoken med hjälp av ett app-ID och en privat certifikatnyckel

Hämta en åtkomsttoken med hjälp av ett app-ID och en hemlighet

Anropa API:erna

Bästa praxis

Visa exempelappen

Feedback

Ytterligare resurser