Integrere API'er til indkøbsbeskyttelse

Artikel
05/20/2024

Denne artikel beskriver, hvordan du integrerer realtids-API'er (brugergrænseflade til program) i Microsoft Dynamics 365 Fraud Protection.

Hvis du vil drage nytte af samtlige funktioner i Fraud Protection, skal du sende dine transaktionsdata til Fraud Protection-realtids-API'erne. I evalueringsoplevelsen kan du sende dine transaktionsdata for at analysere resultaterne af brugen af Fraud Protection. I beskyttelsesoplevelsen kan du også imødekomme beslutninger baseret på de regler, du har konfigureret.

Afhængigt af, hvordan du vælger at bruge Fraud Protection, kan du bruge forskellige sæt af følgende API'er til købsbeskyttelse:

Køb
Købsstatus
BankEvent
Tilbageførsel
Refusion
UpdateAccount
Label

API-integrationsfaser

Integrationen af API'er til købsbeskyttelse sker i tre faser:

Opret Microsoft Entra-programmer via Fraud Protection.
Opret et adgangstoken.
Kald API'erne.

Vigtig

Du skal være global administrator i din Azure-lejer for at kunne logge på første gang.

Besøg følgende portaler for hvert af de miljøer, du vil bruge. Log på, og acceptér vilkår og betingelser, hvis du bliver bedt om det.

Sandkassemiljø
Produktionsmiljø (Du har muligvis allerede fuldført dette trin i produktionen under første tilmelding).

Opret Microsoft Entra-programmer

Vigtigt

Du skal være programadministrator, cloud-programadministrator eller global administrator i din Azure-lejer for at fuldføre disse trin.

Hvis du vil hente de tokens, der kræves for at kalde API'erne, skal du konfigurere og bruge Microsoft Entra-programmer som beskrevet i dette afsnit.

Konfigurer Microsoft Entra-programmer

Følg disse trin for at konfigurere Microsoft Entra-programmer.

Vælg Integration > Opret installation af Microsoft Entra-program > nu i navigationsruden til venstre på portalen Til beskyttelse af svindel.
Udfyld siden for at oprette appen. Vi anbefaler, at du opretter ét Microsoft Entra-program for hvert miljø, du vil integrere med Fraud Protection.
Indtast eller vælg værdier i følgende obligatoriske felter:
- Visningsnavn for program – Giv dit program et beskrivende navn. Beskrivelsen må højst være på 93 tegn.
- Godkendelsesmetode – Vælg, om du vil godkende via certifikat eller en hemmelighed (adgangskode).
Hvis du har valgt certifikat som godkendelsesmetode, skal du benytte følgende fremgangsmåde:
1. Vælg Vælg fil for at uploade den offentlige nøgle. (Når du henter tokens, skal du bruge den tilsvarende private nøgle).
2. Vælg Hemmelighed for automatisk at oprette en adgangskode, når programmet er blevet oprettet.
Vælg Opret applikation, når du er færdig med at udfylde de påkrævede felter. Bekræftelsessiden opsummerer din app's navn, ID og certifikataftryk eller hemmelighed, afhængigt af din valgte godkendelsesmetode.

Vigtigt

Gem oplysningerne om hemmeligheden eller certifikataftrykket til senere brug. Hemmeligheden vil kun blive vist én gang.

Opret en anden applikation

Hvis du vil oprette en anden applikation, skal du vælge Opret en anden applikation. Du kan oprette alle de apps, der er nødvendige for at køre API-kald i hvert af dine miljøer.

Administrer eksisterende Microsoft Entra-programmer

Når du har oprettet dine Microsoft Entra-apps, kan du administrere dem via [Azure-portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Du kan få flere oplysninger under Hvordan og hvorfor programmer føjes til Microsoft Entra ID.

Opret et adgangstoken

Hvis du vil integrere dine systemer sikkert med Fraud Protection, skal du anskaffe et Microsoft Entra-token og angive det i overskriften for hvert API-kald.

Bemærk

Adgangstokens har en begrænset levetid på 60 minutter. Det anbefales, at du cacher og genbruger et token, indtil det er tæt på at udløbe. Du kan derefter få et nyt adgangstoken.

Følgende oplysninger skal bruges til at finde et token.

Krævede ID'er og oplysninger

Miljø-URI – URI'erne for sandkasse- eller produktionsmiljøet vises under fanen Konfiguration på siden API-administration i Fraud Protection-portalen.
Mappe-id (lejer-id) – Dette id er en Globally Unique Identifier (GUID) for en lejers domæne i Azure. Det vises i Azure-portalen og under fanen Konfiguration på siden API-administration i Fraud Protection-portalen.
Program-id (klient) – Dette id identificerer den Microsoft Entra-app, du har oprettet til at kalde API'er. Hent id'et fra bekræftelsessiden API'er i realtid, eller find det senere i Azure-portalen under App-registreringer. Der vil være ét id for hver af de apps, du har oprettet.
Certifikataftryk eller hemmelighed – Hent aftrykket eller hemmeligheden fra siden med bekræftelse af API'er i realtid.
Forekomst-id – Dette id er GUID'et for dit miljø i Fraud Protection. Det vises i feltet Integration på Fraud Protection-dashboardet.

Eksempler : Kodeeksempler der viser, hvordan du kan anskaffe et token med dit certifikat eller din hemmelighed

Følgende C#-kodeeksempler indeholder eksempler på, hvordan du kan hente et token med dit certifikat eller din hemmelighed. Udskift pladsholderne med dine specifikke oplysninger. I begge disse eksempler på C# skal du importere følgende Microsoft.Identity.Client NuGet-pakke.

Du kan finde prøver på andre sprog under https://aka.ms/aaddev.

Få et adgangstoken ved hjælp af et app-id og en privat certifikatnøgle

/// <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;
    }
}

Få et adgangstoken ved hjælp af et app-id og hemmelighed

/// <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;
    }
}

I hvert tilfælde indeholder objektet AuthenticationResult værdien AccessToken og egenskaben ExpiresOn, der angiver, hvornår tokenet bliver ugyldigt.

POST-anmodning til:
- https://login.microsoftonline.com/<Microsoft Entra tenant ID>/oauth2/token
Overskrifter:
- Indholdstype: application/x-www-form-urlencoded
Body (key-value):
- grant_type: client_credentials
- client_id : {dit klient-id fra forrige trin}
- client_secret : {din hemmelighed fra forrige trin}
- resource : https://api.dfp.microsoft.com (for int, https://api.dfp.microsoft-int.com)
Svar:
- Brug værdien af adgangstoken fra svaret til næste trin.

Du kan finde flere oplysninger i følgende Azure-dokumentation:

Kald til API'erne

Hvis du vil kalde til API'erne, skal du følge disse trin.

Send følgende nødvendige påkrævede HTTP-overskrifter for hver anmodning.

Navn på overskrift	Værdi for overskrift
Godkendelse	Brug følgende format til denne overskrift. (Erstat adgangstoken med den faktiske tokenværdi, der returneres af Microsoft Entra ID). Ihændehavertoken
x-ms-korrelation-id	Send en ny GUID-værdi for hvert sæt API-kald, der er oprettet sammen.
x-ms-dfpenvid	Send GUID-værdien af dit forekomst-id.

Navn på overskrift

Værdi for overskrift

Godkendelse

Brug følgende format til denne overskrift. (Erstat adgangstoken med den faktiske tokenværdi, der returneres af Microsoft Entra ID).

Ihændehavertoken

x-ms-korrelation-id

Send en ny GUID-værdi for hvert sæt API-kald, der er oprettet sammen.

x-ms-dfpenvid

Send GUID-værdien af dit forekomst-id.

Generer hændelsesbaserede nyttedata. Udfyld hændelsesdataene med de relevante oplysninger fra systemet. Du kan finde dokumentation til alle understøttede hændelser under Dynamics 365 Fraud Protection API.
Kombiner overskriften (som indeholder adgangstoken) og nyttedataene, og send dem derefter til dit Fraud Protection-slutpunkt.
- POST-anmodning til:
  - <Base URL>/v1.0/merchantservices/events/purchase
- Overskrifter:
  - x-ms-correlation-id : {En GUID, der skal være entydigt for hver anmodning}
  - content-type: application/json
  - Autorisation : {Tokenet fra forrige trin}
  - x-ms-dfpenvid : {Miljø-id for målmiljø}
- Body:
  - Hent indholdet af anmodningen om eksempelkontobeskyttelse fra den delte Swagger-side.

Bemærk!

Hvis du opretter et nyt miljø, skal du medtage miljø-id i API-overskriften under integration, så posteringerne kan distribueres korrekt.

Følgende indstillinger kan accepteres for x-ms-dfpenvid i API-opkaldet, og funktionaliteten er identisk.

Brug miljø-id'et for det miljø, du ringer til. Den id, der er angivet på siden Integration i feltet Miljø-id.
Brug hele stien til Kunde API-id fra roden til det underordnede miljø, du kalder, ved hjælp af skråstregen (/) som adskiller. Angiv for eksempel /primary/XYZ.
Brug hele stien til miljø-id'et eller kunde API-id'et fra roden til det underordnede miljø, du kalder, ved hjælp af skråstregen (/) som adskiller. F.eks. 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Hvis du vil angive kunde-API-id'et, når du opretter et miljø, kan du finde oplysninger i artiklen Administrer miljøer.

Bedste praksis

Hvert Microsoft Entra-token forbliver gyldigt i 60 minutter. Det anbefales, at du cachelagrer det i en kort periode og genbruger det.
Kontrollér, at HttpClient har uafbrudte forbindelser.
Overfør aktid overskriften x-ms-dfpenvid, og sørg for, at den peger på miljøet for den handlende, som du vil sende transaktioner på vegne af.
Gem hemmeligheden i et hemmelighedslager.
Overfør altid overskriften x-ms-correlation-id til fremtidige fejlfindingssessioner med Fraud Protection.
Kontrollér, at overskriften x-ms-correlation-id er entydig for hver transaktion, der sendes til Fraud Protection.

Vis eksempel-appen

Du kan finde flere oplysninger i prøve på appen for forhandlere og den medfølgende dokumentation til udviklere. Eksempel-appen giver et eksempel på, hvordan du kan kalde Fraud Protection-API'er, herunder API-hændelser, som f.eks. afsendelse af opdateringer til kundekonti, refusioner og tilbageførsler i realtid. Dokumentationen til eksempel-appen er sammenkædet med den faktiske eksempelkode, når der er mulighed for sådanne links. Ellers findes der kodeeksempler direkte i dokumentationen.

Du kan finde en vejledning i, hvordan du konfigurerer eksempelwebstedet, under Konfigurer eksempelwebstedet.

Del via