Sdílet prostřednictvím

Integrace rozhraní API pro ochranu nákupů

  • Článek

Tento článek vysvětluje, jak integrovat rozhraní API (Application Programming Interfaces) v reálném čase v Microsoft Dynamics 365 Fraud Protection.

Pokud chcete využít celou sadu funkcí ochrany před podvody, musíte odesílat data transakcí do rozhraní API ochrany před podvody v reálném čase. V prostředí pro vyhodnocení vám odesílání dat transakcí umožňuje analyzovat výsledky použití ochrany před podvody. V prostředí ochrany můžete také respektovat rozhodnutí na základě pravidel, která jste nakonfigurovali.

V závislosti na tom, jak používáte ochranu před podvody, můžete použít různé sady následujících rozhraní API pro ochranu před nákupem:

  • Nákup
  • PurchaseStatus
  • BankEvent
  • Vratka
  • Refundovat
  • UpdateAccount
  • Popisek

Fáze integrace rozhraní API

Integrace rozhraní API ochrany nákupu probíhá ve třech fázích:

  1. Vytvářejte aplikace Microsoft Entra prostřednictvím ochrany před podvody.
  2. Vygenerujte přístupový token.
  3. Volejte rozhraní API.

Přihlásit se

Důležité

Abyste mohli dokončit počáteční přihlášení, musíte být ve svém tenantovi Azure globálním správcem.

Pro každé prostředí, které chcete použít, navštivte následující portály. Pokud se zobrazí výzva k přihlášení, přijměte podmínky a ujednání.

Vytváření aplikací Microsoft Entra

Důležité

Abyste mohli tento krok dokončit, musíte být správcem aplikace, správcem cloudových aplikací nebo globálním správcem ve vašem tenantovi Azure.

Pokud chcete získat tokeny potřebné k volání rozhraní API, musíte nakonfigurovat a používat aplikace Microsoft Entra, jak je popsáno v této části.

Konfigurace aplikací Microsoft Entra

Chcete-li nakonfigurovat aplikace Microsoft Entra, postupujte takto.

  1. Na portálu Pro ochranu před podvody v levém navigačním podokně vyberte Možnost Integrace > Vytvořit instalaci aplikace > Microsoft Entra.

  2. Dokončete stránku a vytvořte aplikaci. Doporučujeme vytvořit jednu aplikaci Microsoft Entra pro každé prostředí, které chcete integrovat s ochranou před podvody.

  3. Zadejte nebo vyberte hodnoty pro následující povinná pole:

    • Zobrazovaný název aplikace – Dejte aplikaci popisný název. Maximální délka je 93 znaků.
    • Metoda ověřování – Vyberte, jestli chcete provést ověření pomocí certifikátu nebo tajného klíče (hesla).

  4. Pokud jste vybrali metodu ověřování certifikátu, postupujte takto:

    1. Vyberte Zvolit soubor , který chcete nahrát veřejný klíč. (Při získávání tokenů se vyžaduje odpovídající privátní klíč.)
    2. Výběrem možnosti Tajný kód automaticky vygenerujete heslo po vytvoření aplikace.

  5. Po dokončení nastavení požadovaných polí vyberte Vytvořit aplikaci. Potvrzovací stránka shrnuje název, ID a tajný klíč nebo kryptografický otisk certifikátu vaší aplikace v závislosti na vybrané metodě ověřování.

Důležité

Uložte informace o kryptografickém otisku tajného kódu nebo certifikátu pro budoucí referenci. Tajný kód se zobrazí jenom jednou.

Vytvoření jiné aplikace

Pokud chcete vytvořit jinou aplikaci, vyberte Vytvořit jinou aplikaci. V každém prostředí můžete vytvořit tolik aplikací, kolik potřebujete ke spouštění volání rozhraní API.

Správa existujících aplikací Microsoft Entra

Po vytvoření aplikací Microsoft Entra je můžete spravovat prostřednictvím webu [Azure Portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Další informace naleznete v tématu How and why applications are added to Microsoft Entra ID.

Vygenerování přístupového tokenu

Pokud chcete bezpečně integrovat systémy s ochranou před podvody, získejte token Microsoft Entra a poskytněte ho do hlavičky každého volání rozhraní API.

Poznámka:

Přístupové tokeny mají omezenou životnost 60 minut. Doporučujeme ukládat tokeny do mezipaměti a opakovaně ho používat, dokud nevypršela jeho platnost. Pak můžete získat nový přístupový token.

K získání tokenu jsou potřeba následující informace.

Požadovaná ID a informace

  • Identifikátor URI prostředí – Identifikátory URI vašeho sandboxu nebo produkčního prostředí se zobrazí na kartě Konfigurace na stránce API Management na portálu Ochrany před podvody.
  • ID adresáře (tenanta) – Toto ID je globálně jedinečný identifikátor (GUID) domény tenanta v Azure. Zobrazí se na webu Azure Portal a na kartě Konfigurace na stránce API Management na portálu Pro ochranu před podvody.
  • ID aplikace (klienta) – Toto ID identifikuje aplikaci Microsoft Entra, kterou jste vytvořili pro volání rozhraní API. Získejte ID ze stránky s potvrzením rozhraní API v reálném čase nebo ho vyhledejte později v části Registrace aplikací na webu Azure Portal. Pro každou aplikaci, kterou jste vytvořili, bude existovat jedno ID.
  • Kryptografický otisk certifikátu nebo tajný kód – Získejte kryptografický otisk nebo tajný kód ze stránky potvrzení rozhraní API v reálném čase.
  • ID instance – Toto ID je IDENTIFIKÁTOR GUID vašeho prostředí v ochraně před podvody. Zobrazí se na dlaždici Integrace na řídicím panelu Ochrana před podvody.

Příklady: Ukázky kódu, které ukazují, jak získat token pomocí certifikátu nebo tajného kódu

Následující ukázky kódu jazyka C# poskytují příklady získání tokenu pomocí certifikátu nebo tajného kódu. Zástupné symboly nahraďte konkrétními informacemi. U obou ukázek jazyka C# budete muset importovat balíček NuGet Microsoft.Identity.Client.

Ukázky v jinýchch https://aka.ms/aaddev

Získání přístupového tokenu pomocí ID aplikace a privátního klíče certifikátu

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

Získání přístupového tokenu pomocí ID aplikace a tajného kódu

/// <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 objekt v každém případě obsahuje AccessToken hodnotu a ExpiresOn vlastnost, která označuje, kdy token bude neplatný.

  • Požadavek POST na:

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

  • Hlavičky:

    • Typ obsahu: application/x-www-form-urlencoded

  • Základní text (hodnota klíče):

    • grant_type: client_credentials
    • client_id: {ID klienta z předchozího kroku}
    • client_secret: {Váš tajný kód z předchozího kroku}
    • zdroj: https://api.dfp.microsoft.com (pro int, https://api.dfp.microsoft-int.com)

  • Odpověď:

    • Použijte hodnotu access_token z odpovědi pro další krok.

Další informace najdete v následující dokumentaci k Azure:

Volání rozhraní API

Pokud chcete volat rozhraní API, postupujte podle těchto kroků.

  1. Pro každý požadavek předejte následující povinná hlavička HTTP.

    Název hlavičky Hodnota hlavičky
    Autorizace

    Pro tuto hlavičku použijte následující formát. (Nahraďte accesstoken skutečnou hodnotou tokenu vrácenou id Microsoft Entra.)

    Nosný přístup kekenu
    x-ms-correlation-id Odešle novou hodnotu GUID pro každou sadu volání rozhraní API, která jsou vytvořená společně.
    x-ms-dfpenvid Odešle hodnotu GUID ID vaší instance.

  2. Vygenerujte datovou část založenou na událostech. Vyplňte data události relevantními informacemi z vašeho systému. Dokumentaci ke všem podporovaným událostem najdete v tématu Rozhraní API dynamics 365 pro ochranu před podvody.

  3. Zkombinujte hlavičku (která zahrnuje přístupový token) a datovou část a odešlete je do koncového bodu Ochrany před podvody.

    • Požadavek POST na:

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

    • Hlavičky:

      • x-ms-correlation-id: {A GUID, který musí být jedinečný pro každý požadavek}
      • content-type: application/json
      • Autorizace: {Token z předchozího kroku}
      • x-ms-dfpenvid: {ID prostředí cílového prostředí}

    • Text:

      • Na sdílené stránce Swaggeru získejte text žádosti o ochranu ukázkových účtů.

Poznámka:

Pokud vytvoříte nové prostředí, zahrňte ID prostředí do hlavičky rozhraní API během integrace, aby bylo možné transakce správně směrovat.

Následující možnosti jsou přijatelné pro x-ms-dfpenvid ve volání rozhraní API a chování je stejné.

  • Použijte ID prostředí pro prostředí, které voláte. ID je uvedené na stránce Integrace v poli ID prostředí.
  • Použijte úplný pat ID rozhraní API zákazníka z kořenového adresáře do podřízeného prostředí, které voláte pomocí lomítka (/) jako oddělovače. Například /primary/XYZ.
  • Použijte úplnou cestu ID prostředí nebo ID rozhraní API zákazníka z kořenového adresáře do podřízeného prostředí, které voláte pomocí lomítka (/) jako oddělovače. Například 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Pokud chcete zadat ID rozhraní API zákazníka při vytváření prostředí, přečtěte si článek Správa prostředí.

Osvědčené postupy

  • Každý token Microsoft Entra zůstane platný po dobu 60 minut. Doporučujeme ji uložit do mezipaměti po kratší dobu a znovu ji použít.
  • Ujistěte se, že má httpClient připojení k udržování naživu.
  • Vždy předejte hlavičku x-ms-dfpenvid a ujistěte se, že odkazuje na prostředí obchodníka, kterému chcete odesílat transakce jménem.
  • Uložte tajný kód do úložiště tajných kódů.
  • Vždy předejte hlavičku x-ms-correlation-id pro budoucí ladicí relace s ochranou před podvody.
  • Ujistěte se, že hlavička x-ms-correlation-id je jedinečná pro každou transakci, která se odesílá do ochrany před podvody. 

Zobrazení ukázkové aplikace

Další referenční informace najdete v ukázkové obchodní aplikaci a doprovodné dokumentaci pro vývojáře. Ukázková aplikace poskytuje příklad volání rozhraní API pro ochranu před podvody, včetně událostí rozhraní API, jako je odesílání aktualizací zákaznického účtu, refundace a vracení peněz v reálném čase. Dokumentace k ukázkové aplikaci je propojená se skutečným vzorový kódem, kdykoli je to možné. V opačném případě ukázky kódu existují přímo v dokumentaci.

Pokyny ke konfiguraci ukázkového webu pro vaše použití najdete v tématu Konfigurace ukázkové lokality.