Sdílet prostřednictvím

Integrace rozhraní API ochrany účtů

  • Článek

Pokud chcete využít kompletní sadu funkcí v aplikaci Microsoft Dynamics 365 Fraud Protection, odešlete data transakcí do programovacích rozhraní aplikací v reálném čase (API). Vyhodnocovaných prostředí pak můžete analyzovat výsledky použití ochrany před podvody. V prostředí ochrany můžete také respektovat rozhodnutí založená na nakonfigurovaných pravidlech.

V závislosti na tom, jak se rozhodnete použít ochranu před podvody, můžete použít různá rozhraní API ochrany účtů. Například AccountCreation, AccountLogin, AccountCreationStatus, AccountLoginStatus, AccountUpdate a Label.

Informace o všech podporovaných událostech najdete v tématu Dynamics 365 Fraud Protection API.

Nastavení

Přihlásit se

Důležité

K dokončení počátečního onboardingu rozhraní API musíte být globálním Správa istratorem ve vašem tenantovi Microsoft Azure.

Přihlášení k ochraně před podvody:

  • Pokud se zobrazí výzva k jejich přijetí, přejděte na portál ochrany před podvody, přihlaste se a přijměte podmínky a ujednání.

    Tento krok zajistí správnou konfiguraci ochrany před podvody ve vašem tenantovi Azure. (Tento krok jste už možná dokončili během počáteční registrace.)

Vytváření aplikací Microsoft Entra

Důležité

K dokončení tohoto kroku musíte být aplikační Správa istrator, cloudová aplikace Správa istrator nebo globální Správa istrator ve vašem tenantovi Azure.

Pokud chcete získat tokeny potřebné k volání rozhraní API, musíte použít aplikace Microsoft Entra. Tyto aplikace můžete nakonfigurovat pomocí stránky rozhraní API v reálném čase v části Ochrana před podvody .

Konfigurace aplikací Microsoft Entra:

  1. V levém navigačním podokně vyberte Konfigurace a pak vyberte rozhraní API v reálném čase.

  2. Vyplňte pole pro vytvoření aplikace. Jsou vyžadována následující pole:

    • Zobrazovaný název aplikace – Zadejte popisný název aplikace. Maximální délka je 93 znaků.
    • Prostředí – Vyberte produkční koncový bod.
    • Metoda ověřování – Vyberte, jestli se k ověřování používá certifikát nebo tajný klíč (heslo). Pokud vyberete Certifikát, vyberte Zvolit soubor a nahrajte veřejný klíč. Při získávání tokenů budete potřebovat odpovídající privátní klíč. Pokud vyberete Tajný kód, po vytvoření aplikace se pro vás vygeneruje heslo.

  3. Po vyplnění polí vyberte Vytvořit aplikaci.

    Potvrzovací stránka shrnuje název a ID aplikace a buď kryptografický otisk certifikátu, nebo tajný klíč v závislosti na vybrané metodě ověřování.

Důležité

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

Můžete vytvořit tolik aplikací, kolik potřebujete ke spouštění volání rozhraní API v produkčních prostředích.

Vytvoření jiné aplikace:

  1. Vyberte Vytvořit jinou aplikaci.
  2. Vyplňte pole pro vytvoření aplikace a pak vyberte Vytvořit aplikaci.

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 najdete na webu dokumentace Azure.

Volání rozhraní API ochrany před podvody v reálném čase

Informace v této části slouží k integraci systémů s ochranou před podvody.

Požadovaná ID a informace

  • Koncový bod rozhraní API – identifikátor URI pro vaše prostředí se zobrazí na dlaždici Informace o účtu na řídicím panelu Ochrana před podvody.
  • ID adresáře (tenanta) – ID adresáře je globálně jedinečný identifikátor (GUID) domény tenanta v Azure. Zobrazí se na webu Azure Portal a na dlaždici Informace o účtu na řídicím panelu Ochrana před podvody.
  • ID aplikace (klienta) – ID aplikace identifikuje aplikaci Microsoft Entra, kterou jste vytvořili pro volání rozhraní API. Toto ID najdete na potvrzovací stránce, která se zobrazí po výběru možnosti Vytvořit aplikaci na stránce Rozhraní API v reálném čase. Najdete ho také 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ý klíč – kryptografický otisk certifikátu nebo tajný klíč najdete na stránce potvrzení, která se zobrazí po výběru možnosti Vytvořit aplikaci na stránce Rozhraní API v reálném čase.
  • ID instance – ID instance je globálně jedinečný identifikátor (GUID) pro vaše prostředí v ochraně před podvody. Zobrazí se na dlaždici Integrace na řídicím panelu Ochrana před podvody.

Vygenerování přístupového tokenu

Tento token musíte vygenerovat a poskytnout ho každému volání rozhraní API. Upozorňujeme, že přístupové tokeny mají omezenou životnost. Doporučujeme ukládat do mezipaměti a opakovaně používat každý přístupový token, dokud nebude čas získat nový přístupový token.

Následující ukázky kódu jazyka C# poskytují příklady, které ukazují, jak získat token pomocí certifikátu nebo tajného kódu. Zástupné symboly nahraďte vlastními informacemi.

Kryptografický otisk certifikátu

public async Task<string> AcquireTokenWithCertificateAsync()
{
    var x509Cert = CertificateUtility.GetByThumbprint("<Certificate thumbprint>");
    var clientAssertion = new ClientAssertionCertificate("<Client ID>", x509Cert);
    var context = new AuthenticationContext("<Authority URL. Typically https://login.microsoftonline.com/[Directory_ID]>");
    var authenticationResult = await context.AcquireTokenAsync("<API endpoint>", clientAssertion);

    return authenticationResult.AccessToken;
}

Tajný kód

public async Task<string> AcquireTokenWithSecretAsync()
{
    var clientAssertion = new ClientCredential("<Client ID>", "<Client secret>");
    var context = new AuthenticationContext("<Authority URL. Typically https://login.microsoftonline.com/[Directory_ID]>");
    var authenticationResult = await context.AcquireTokenAsync("<API endpoint>", clientAssertion);

    return authenticationResult.AccessToken;
}

Response

Předchozí kód na pozadí vygeneruje požadavek HTTP a obdrží odpověď, která se podobá následujícímu příkladu.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: <date>
Content-Length: <content length>

{
    "token_type":"Bearer",
    "expires_in":"3599",
    "ext_expires_in":"3599",
    "expires_on":"<date timestamp>",
    "not_before":"<date timestamp>",
    "resource":"https://api.dfp.dynamics.com",
    "access_token":"<your access token; e.g.: eyJ0eXA...NFLCQ>"
}

Další informace najdete v 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: Bearer accesstoken, kde accesstoken je token vrácený id Microsoft Entra.
    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 instance.

  2. Vygenerujte datovou část založenou na událostech. Vyplňte data události relevantními informacemi z vašeho systému. Informace o všech podporovaných událostech najdete v tématu Dynamics 365 Fraud Protection API.

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

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.

Zobrazení ukázkové aplikace

Další referenční informace najdete v ukázkové obchodní aplikaci a v doprovodné dokumentaci pro vývojáře. Ukázková aplikace poskytuje příklad, který ukazuje, jak v reálném čase volat rozhraní API pro ochranu před podvody. 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ě se ukázky kódu zahrnou přímo do dokumentace.

Informace o tom, jak nakonfigurovat ukázkový web, abyste ho mohli použít, najdete v tématu Konfigurace ukázkového webu.