Megosztás a következőn keresztül:

Vásárlásvédelmi API-k integrálása

  • Cikk

Ez a cikk bemutatja, hogyan integrálhatók valós idejű alkalmazásprogramozási felületek (API-k) a Microsoft Dynamics 365 Fraud Protectionben.

A Csalás elleni védelem funkcióinak teljes körű kihasználásához el kell küldenie a tranzakciós adatokat a valós idejű Fraud Protection API-knak. A kiértékelési folyamat során a tranzakciós adatok elküldésével elemezheti a Fraud Protection használatának eredményeit. A védelmi felületen a konfigurált szabályok alapján a döntéseket is tiszteletben tarthatja.

A Fraud Protection használatának módjától függően az alábbi vásárlásvédelmi API-k különböző készletei használhatók:

  • Vásárlás
  • PurchaseStatus
  • BankEvent
  • Jóváírás
  • Visszatérítés
  • UpdateAccount
  • Címke

API-integrációs fázisok

A vásárlásvédelmi API-k integrálása három fázisban történik:

  1. Microsoft Entra-alkalmazások létrehozása a Fraud Protection használatával.
  2. Hozzáférési jogkivonat létrehozása.
  3. Hívja meg az API-kat.

Bejelentkezés

Fontos

A kezdeti bejelentkezés befejezéséhez globális rendszergazdának kell lennie az Azure-bérlőben.

Látogasson el a következő portálokra minden használni kívánt környezethez. Jelentkezzen be, és fogadja el a használati feltételeket, ha a rendszer erre kéri.

Microsoft Entra-alkalmazások létrehozása

Fontos

A lépés végrehajtásához az Azure-bérlő alkalmazásadminisztrátorának, felhőalkalmazás-rendszergazdájának vagy globális rendszergazdájának kell lennie.

Az API-k meghívásához szükséges jogkivonatok beszerzéséhez konfigurálnia és használnia kell a Microsoft Entra-alkalmazásokat az ebben a szakaszban leírtak szerint.

Microsoft Entra-alkalmazások konfigurálása

A Microsoft Entra-alkalmazások konfigurálásához kövesse az alábbi lépéseket.

  1. A Csalás elleni védelem portál bal oldali navigációs panelén válassza az Integráció > a Microsoft Entra alkalmazásbeállítás > létrehozása most lehetőséget.

  2. Töltse ki a lapot az alkalmazás létrehozásához. Javasoljuk, hogy hozzon létre egy Microsoft Entra-alkalmazást minden olyan környezethez, amelyet integrálni szeretne a Fraud Protection szolgáltatással.

  3. Adja meg vagy válassza ki az alábbi kötelező mezők értékeit:

    • Alkalmazásmegjelenítési név – Adjon egy leíró nevet az alkalmazásnak. A maximális hossz 93 karakter.
    • Hitelesítési módszer – Válassza ki, hogy tanúsítványon vagy titkos kódon (jelszón) keresztül szeretne-e hitelesítést végezni.

  4. Ha a tanúsítványhitelesítési módszert választotta, kövesse az alábbi lépéseket:

    1. Válassza a Fájl kiválasztása lehetőséget a nyilvános kulcs feltöltéséhez. (A jogkivonatok beszerzésekor az egyező titkos kulcs szükséges.)
    2. Válassza a Titkos kód lehetőséget, ha automatikusan létrehoz egy jelszót az alkalmazás létrehozása után.

  5. Ha befejezte a szükséges mezők beállítását, válassza az Alkalmazás létrehozása lehetőséget. A megerősítő oldal a kiválasztott hitelesítési módszertől függően összegzi az alkalmazás nevét, azonosítóját és tanúsítványának ujjlenyomatát vagy titkos kódját.

Fontos

Mentse a titkos vagy tanúsítvány ujjlenyomat-adatait későbbi referenciaként. A titkos kód csak egyszer jelenik meg.

Másik alkalmazás létrehozása

Másik alkalmazás létrehozásához válassza a Másik alkalmazás létrehozása lehetőséget. Tetszőleges számú alkalmazást hozhat létre az API-hívások futtatásához az egyes környezetekben.

Meglévő Microsoft Entra-alkalmazások kezelése

A Microsoft Entra-alkalmazások létrehozása után az [Azure Portalon](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps) kezelheti őket. További információ: Hogyan és miért vannak hozzáadva alkalmazások a Microsoft Entra-azonosítóhoz.

Hozzáférési jogkivonat létrehozása

A rendszerek csalás elleni védelemmel való biztonságos integrálásához szerezze be a Microsoft Entra-jogkivonatot, és adja meg az egyes API-hívások fejlécében.

Feljegyzés

A hozzáférési jogkivonatok élettartama korlátozott, 60 perc. Javasoljuk, hogy gyorsítótárazza és használja újra a jogkivonatot, amíg az el nem jár. Ezután lekérhet egy új hozzáférési jogkivonatot.

A jogkivonat beszerzéséhez a következő információkra van szükség.

Szükséges azonosítók és információk

  • Környezeti URI – A tesztkörnyezethez vagy éles környezethez tartozó URI-k az API Management lap Konfiguráció lapján jelennek meg a Csalásvédelem portálon.
  • Címtár (bérlő) azonosítója – Ez az azonosító egy bérlő tartományának globálisan egyedi azonosítója (GUID) az Azure-ban. Megjelenik az Azure Portalon és az API Management lap Konfiguráció lapján a Csalás elleni védelem portálon.
  • Alkalmazás (ügyfél) azonosítója – Ez az azonosító azonosítja az API-k meghívásához létrehozott Microsoft Entra-alkalmazást. Kérje le az azonosítót a valós idejű API-k megerősítési oldaláról, vagy keresse meg később az Azure Portal Alkalmazásregisztrációk alatt. Minden létrehozott alkalmazáshoz egy azonosító tartozik.
  • Tanúsítvány ujjlenyomata vagy titkos kódja – Kérje le az ujjlenyomatot vagy a titkos kulcsot a valós idejű API-k megerősítési oldaláról.
  • Példányazonosító – Ez az azonosító a környezet GUID azonosítója a Fraud Protectionben. Megjelenik a Csalás elleni védelem irányítópult Integráció csempéjén.

Példák: Kódminták, amelyek bemutatják, hogyan szerezhet be jogkivonatot a tanúsítvány vagy a titkos kód használatával

Az alábbi C#-kódminták példákat mutatnak be egy jogkivonat tanúsítványsal vagy titkos kóddal való beszerzésére. Cserélje le a helyőrzőket a megadott adatokra. Mindkét C#-minta esetében importálnia kell a Microsoft.Identity.Client NuGet-csomagot.

Más nyelvű mintákért lásd: https://aka.ms/aaddev.

Hozzáférési jogkivonat lekérése alkalmazásazonosító és privát tanúsítványkulcs használatával

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

Hozzáférési jogkivonat lekérése alkalmazásazonosító és titkos kód használatával

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

A AuthenticationResult objektum minden esetben tartalmazza az AccessToken értéket és egy ExpiresOn tulajdonságot, amely jelzi, hogy a jogkivonat mikor válik érvénytelenné.

  • POST kérés a következőhöz:

    • https://login.microsoftonline.com/<Microsoft Entra tenant ID>/oauth2/token

  • Fejlécek:

    • Tartalomtípus: application/x-www-form-urlencoded

  • Törzs (kulcs-érték):

    • grant_type: client_credentials
    • client_id: {Az ügyfélazonosító az előző lépésből}
    • client_secret: {Az előző lépés titkos kódja}
    • erőforrás: https://api.dfp.microsoft.com (int, https://api.dfp.microsoft-int.com)

  • Válasz:

    • Használja a következő lépés válaszából származó access_token értékét.

További információkért tekintse meg a következő Azure-dokumentációt:

Az API-k meghívása

Az API-k meghívásához kövesse az alábbi lépéseket.

  1. Minden kéréshez adja át a következő szükséges HTTP-fejléceket.

    Fejléc neve Fejléc értéke
    Engedélyezés

    Ehhez a fejléchez használja az alábbi formátumot. (Cserélje le a hozzáférési jogkivonatot a Microsoft Entra ID által visszaadott tényleges jogkivonat-értékre.)

    Bearer accesstoken
    x-ms-correlation-id Küldjön egy új GUID-értéket minden egyes, együtt végrehajtott API-hívásra.
    x-ms-dfpenvid Küldje el a példányazonosító GUID-értékét.

  2. Eseményalapú hasznos adatok létrehozása. Töltse ki az eseményadatokat a rendszerből származó releváns információkkal. Az összes támogatott esemény dokumentációját a Dynamics 365 Fraud Protection API-ban találja.

  3. Egyesítse a fejlécet (amely tartalmazza a hozzáférési jogkivonatot) és a hasznos adatokat, majd küldje el őket a Fraud Protection-végpontra.

    • POST kérés a következőhöz:

      • <Base URL>/v1.0/merchantservices/events/purchase

    • Fejlécek:

      • x-ms-correlation-id: {A GUID, amelynek kérésenként egyedinek kell lennie}
      • content-type: application/json
      • Engedélyezés: {Az előző lépés jogkivonata}
      • x-ms-dfpenvid: {A célkörnyezet környezeti azonosítója}

    • Törzs:

Feljegyzés

Ha új környezetet hoz létre, az integráció során adja meg a környezet azonosítóját az API fejlécében, hogy a tranzakciók megfelelően irányíthatók legyenek.

Az alábbi lehetőségek elfogadhatók az x-ms-dfpenvid esetében az API-hívásban, és a viselkedés azonos.

  • Használja a meghívni kívánt környezet környezeti azonosítóját. Az azonosító megjelenik a Környezetazonosító mező Integráció lapján.
  • Használja az ügyfél API-azonosítójának teljes patát a gyökértől a hívott gyermekkörnyezetig az előre perjel (/) használatával osztóként. Például: /primary/XYZ.
  • Használja a környezetazonosító vagy az ügyfél API-azonosító teljes elérési útját a gyökértől a hívott gyermekkörnyezetig az előre perjel (/) osztó használatával. Például : 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Ha meg szeretné adni az ügyfél API-azonosítóját egy környezet creat használatakor, olvassa el a Környezetek kezelése című cikket.

Ajánlott eljárások

  • Minden Microsoft Entra-jogkivonat 60 percig érvényes marad. Javasoljuk, hogy rövidebb ideig gyorsítótárazza, és használja újra.
  • Győződjön meg arról, hogy a HttpClient rendelkezik életben maradó kapcsolatokkal.
  • Mindig adja át az x-ms-dfpenvid fejlécet, és győződjön meg arról, hogy az annak a kereskedőnek a környezetére mutat, akinek a nevében tranzakciókat szeretne küldeni.
  • Tárolja a titkos kulcsot egy titkos tárban.
  • Mindig adja át az x-ms-correlation-id fejlécet a későbbi hibakeresési munkamenetekhez a Fraud Protection használatával.
  • Győződjön meg arról, hogy az x-ms-correlation-id fejléc minden, a Fraud Protectionnek küldött tranzakcióhoz egyedi. 

A mintaalkalmazás megtekintése

További információkért tekintse meg a kereskedői mintaalkalmazást és a hozzá tartozó fejlesztői dokumentációt. A mintaalkalmazás példaként szolgál a Fraud Protection API-k meghívására, beleértve az API-eseményeket, például az ügyfélfiók frissítéseinek, visszatérítéseinek és visszatérítéseinek valós idejű küldését. A mintaalkalmazás dokumentációja a tényleges mintakódhoz van csatolva, amikor ilyen hivatkozások lehetségesek. Ellenkező esetben a kódminták közvetlenül a dokumentációban találhatók.

A mintawebhely használatra való konfigurálásáról további információt a mintawebhely konfigurálása című témakörben talál.