Integrowanie interfejsów API ochrony zakupów

Artykuł
05/20/2024

W tym artykule wyjaśniono, jak zintegrować interfejsy programowania aplikacji w czasie rzeczywistym w usłudze Microsoft Dynamics 365 Fraud Protection.

Aby korzystać z pełnego zestawu funkcji ochrony przed oszustwami, musisz wysłać dane transakcji do interfejsów API ochrony przed oszustwami w czasie rzeczywistym. W środowisku oceny wysyłanie danych transakcji umożliwia analizowanie wyników korzystania z ochrony przed oszustwami. W środowisku ochrony możesz również przestrzegać decyzji na podstawie skonfigurowanych reguł.

W zależności od sposobu korzystania z ochrony przed oszustwami można użyć różnych zestawów następujących interfejsów API ochrony zakupów:

Zakup
PurchaseStatus
BankEvent
Obciążenie zwrotne
Zwrot
UpdateAccount
Etykieta

Fazy integracji interfejsu API

Integracja interfejsów API ochrony zakupów odbywa się w trzech fazach:

Tworzenie aplikacji Firmy Microsoft Entra za pomocą usługi Fraud Protection.
Generowanie tokenu dostępu.
Wywoływanie interfejsów API.

Ważne

Aby ukończyć początkowe logowanie, musisz być administratorem globalnym w dzierżawie platformy Azure.

Odwiedź następujące portale dla każdego środowiska, którego zamierzasz użyć. Zaloguj się i zaakceptuj warunki i postanowienia, jeśli zostanie wyświetlony monit o to.

Środowisko piaskownicy
Środowisko produkcyjne (ten krok można już wykonać w środowisku produkcyjnym podczas początkowej rejestracji).

Tworzenie aplikacji Firmy Microsoft Entra

Ważne

Aby wykonać ten krok, musisz być administratorem aplikacji, administratorem aplikacji w chmurze lub administratorem globalnym w dzierżawie platformy Azure.

Aby uzyskać tokeny wymagane do wywołania interfejsów API, należy skonfigurować i używać aplikacji Firmy Microsoft Entra zgodnie z opisem w tej sekcji.

Konfigurowanie aplikacji Firmy Microsoft Entra

Aby skonfigurować aplikacje Firmy Microsoft Entra, wykonaj następujące kroki.

W portalu ochrony przed oszustwami w okienku nawigacji po lewej stronie wybierz pozycję Integracja > Utwórz teraz instalatora aplikacji > firmy Microsoft Entra.
Ukończ stronę, aby utworzyć aplikację. Zalecamy utworzenie jednej aplikacji firmy Microsoft Entra dla każdego środowiska, które chcesz zintegrować z usługą Fraud Protection.
Wprowadź lub wybierz wartości dla następujących wymaganych pól:
- Nazwa wyświetlana aplikacji — nadaj aplikacji nazwę opisową. Maksymalna długość to 93 znaki.
- Metoda uwierzytelniania — wybierz, czy chcesz uwierzytelnić się za pośrednictwem certyfikatu, czy wpisu tajnego (hasła).
Jeśli wybrano metodę uwierzytelniania certyfikatu, wykonaj następujące kroki:
1. Wybierz pozycję Wybierz plik , aby przekazać klucz publiczny. (Pasujący klucz prywatny jest wymagany podczas uzyskiwania tokenów).
2. Wybierz pozycję Wpis tajny , aby automatycznie wygenerować hasło po utworzeniu aplikacji.
Po zakończeniu ustawiania wymaganych pól wybierz pozycję Utwórz aplikację. Strona potwierdzenia zawiera podsumowanie nazwy, identyfikatora i klucza tajnego certyfikatu aplikacji w zależności od wybranej metody uwierzytelniania.

Ważne

Zapisz informacje o wpisie tajnym lub odcisku palca certyfikatu na potrzeby przyszłego odwołania. Wpis tajny będzie wyświetlany tylko raz.

Tworzenie innej aplikacji

Aby utworzyć inną aplikację, wybierz pozycję Utwórz inną aplikację. Możesz utworzyć dowolną liczbę aplikacji, które są wymagane do uruchamiania wywołań interfejsu API w każdym środowisku.

Zarządzanie istniejącymi aplikacjami firmy Microsoft Entra

Po utworzeniu aplikacji microsoft Entra możesz zarządzać nimi za pośrednictwem witryny [Azure Portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Aby uzyskać więcej informacji, zobacz How and why applications are added to Microsoft Entra ID (Jak i dlaczego aplikacje są dodawane do identyfikatora Entra firmy Microsoft).

Generowanie tokenu dostępu

Aby bezpiecznie zintegrować systemy z usługą Fraud Protection, uzyskaj token firmy Microsoft Entra i podaj go w nagłówku każdego wywołania interfejsu API.

Uwaga

Tokeny dostępu mają ograniczoną żywotność wynoszącą 60 minut. Zalecamy buforowanie i ponowne używanie tokenu do momentu zamknięcia wygaśnięcia. Następnie możesz uzyskać nowy token dostępu.

Do uzyskania tokenu potrzebne są następujące informacje.

Wymagane identyfikatory i informacje

Identyfikator URI środowiska — identyfikatory URI dla piaskownicy lub środowiska produkcyjnego są wyświetlane na karcie Konfiguracja strony usługi API Management w portalu ochrony przed oszustwami.
Identyfikator katalogu (dzierżawy) — ten identyfikator jest globalnie unikatowym identyfikatorem domeny dzierżawy na platformie Azure. Zostanie on wyświetlony w witrynie Azure Portal i na karcie Konfiguracja strony usługi API Management w portalu ochrony przed oszustwami.
Identyfikator aplikacji (klienta) — ten identyfikator identyfikuje aplikację Firmy Microsoft Entra utworzoną do wywoływania interfejsów API. Pobierz identyfikator ze strony potwierdzenia interfejsów API czasu rzeczywistego lub znajdź go później w obszarze Rejestracje aplikacji w witrynie Azure Portal. Dla każdej utworzonej aplikacji będzie dostępny jeden identyfikator.
Odcisk palca lub wpis tajny certyfikatu — pobierz odcisk palca lub wpis tajny ze strony potwierdzenia interfejsów API czasu rzeczywistego.
Identyfikator wystąpienia — ten identyfikator jest identyfikatorem GUID środowiska w ochronie przed oszustwami. Zostanie on wyświetlony na kafelku Integracja na pulpicie nawigacyjnym Ochrona przed oszustwami.

Przykłady: przykłady kodu pokazujące sposób uzyskiwania tokenu przy użyciu certyfikatu lub wpisu tajnego

Poniższe przykłady kodu w języku C# zawierają przykłady uzyskiwania tokenu za pomocą certyfikatu lub wpisu tajnego. Zastąp symbole zastępcze określonymi informacjami. W przypadku obu przykładów języka C# należy zaimportować pakiet NuGet Microsoft.Identity.Client.

Przykłady w innych językach można znaleźć w temacie https://aka.ms/aaddev.

Uzyskiwanie tokenu dostępu przy użyciu identyfikatora aplikacji i klucza prywatnego certyfikatu

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

Uzyskiwanie tokenu dostępu przy użyciu identyfikatora aplikacji i wpisu tajnego

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

Obiekt AuthenticationResult w każdym przypadku zawiera wartość AccessToken i właściwość ExpiresOn wskazującą, kiedy token stanie się nieprawidłowy.

Żądanie POST do:
- https://login.microsoftonline.com/<Microsoft Entra tenant ID>/oauth2/token
Nagłówki:
- Typ zawartości: application/x-www-form-urlencoded
Treść (klucz-wartość):
- grant_type: client_credentials
- client_id: {Identyfikator klienta z poprzedniego kroku}
- client_secret: {Wpis tajny z poprzedniego kroku}
- resource: https://api.dfp.microsoft.com (for int, https://api.dfp.microsoft-int.com)
Reakcja:
- Użyj wartości access_token z odpowiedzi na następny krok.

Aby uzyskać więcej informacji, zobacz następującą dokumentację platformy Azure:

Wywoływanie interfejsów API

Aby wywołać interfejsy API, wykonaj następujące kroki.

Przekaż następujące wymagane nagłówki HTTP dla każdego żądania.

Nazwa nagłówka	Wartość nagłówka
Autoryzacja	Użyj następującego formatu dla tego nagłówka. (Zastąp wartość accesstoken rzeczywistą wartością tokenu zwróconą przez identyfikator Entra firmy Microsoft). Dostęp elementu nośnego
x-ms-correlation-id	Wyślij nową wartość identyfikatora GUID dla każdego zestawu wywołań interfejsu API, które są wykonywane razem.
x-ms-dfpenvid	Wyślij wartość identyfikatora GUID identyfikatora wystąpienia.

Nazwa nagłówka

Wartość nagłówka

Autoryzacja

Użyj następującego formatu dla tego nagłówka. (Zastąp wartość accesstoken rzeczywistą wartością tokenu zwróconą przez identyfikator Entra firmy Microsoft).

Dostęp elementu nośnego

x-ms-correlation-id

Wyślij nową wartość identyfikatora GUID dla każdego zestawu wywołań interfejsu API, które są wykonywane razem.

x-ms-dfpenvid

Wyślij wartość identyfikatora GUID identyfikatora wystąpienia.

Generowanie ładunku opartego na zdarzeniach. Wypełnij dane zdarzenia odpowiednimi informacjami z systemu. Aby uzyskać dokumentację dotyczącą wszystkich obsługiwanych zdarzeń, zobacz Dynamics 365 Fraud Protection API (Interfejs API ochrony przed oszustwami w usłudze Dynamics 365).
Połącz nagłówek (który zawiera token dostępu) i ładunek, a następnie wyślij go do punktu końcowego ochrony przed oszustwami.
- Żądanie POST do:
  - <Base URL>/v1.0/merchantservices/events/purchase
- Nagłówki:
  - x-ms-correlation-id: {Identyfikator GUID, który musi być unikatowy dla każdego żądania}
  - content-type: application/json
  - Autoryzacja: {Token z poprzedniego kroku}
  - x-ms-dfpenvid: {Identyfikator środowiska środowiska docelowego}
- Treść:
  - Pobierz treść przykładowego żądania ochrony konta ze strony udostępnionej struktury Swagger.

Uwaga

Jeśli tworzysz nowe środowisko, dołącz identyfikator środowiska do nagłówka interfejsu API podczas integracji, aby transakcje mogły być prawidłowo kierowane.

Następujące opcje są dopuszczalne dla x-ms-dfpenvid w wywołaniu interfejsu API i zachowanie jest identyczne.

Użyj identyfikatora środowiska dla wywoływanego środowiska. Identyfikator znajduje się na stronie Integracja w polu Identyfikator środowiska.
Użyj pełnego pat identyfikatora interfejsu API klienta z katalogu głównego do środowiska podrzędnego, które wywołujesz przy użyciu ukośnika (/) jako elementu dzielącego. Na przykład /primary/XYZ.
Użyj pełnej ścieżki identyfikatora środowiska lub identyfikatora interfejsu API klienta z katalogu głównego do środowiska podrzędnego, które wywołujesz przy użyciu ukośnika (/) jako elementu dzielącego. Na przykład 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Aby określić identyfikator interfejsu API klienta podczas tworzenia środowiska, zobacz artykuł Zarządzanie środowiskami.

Najlepsze rozwiązania

Każdy token Microsoft Entra pozostaje ważny przez 60 minut. Zalecamy buforowanie go przez krótszy czas i ponowne użycie go.
Upewnij się, że klient HttpClient ma aktywne połączenia.
Zawsze przekazuj nagłówek x-ms-dfpenvid i upewnij się, że wskazuje on środowisko sprzedawcy, którego chcesz wysłać transakcje w imieniu.
Zapisz wpis tajny w magazynie wpisów tajnych.
Zawsze przekazuj nagłówek x-ms-correlation-id na potrzeby przyszłych sesji debugowania za pomocą usługi Fraud Protection.
Upewnij się, że nagłówek x-ms-correlation-id jest unikatowy dla każdej transakcji wysyłanej do ochrony przed oszustwami.

Wyświetlanie przykładowej aplikacji

Aby uzyskać dodatkowe informacje, możesz wyświetlić przykładową aplikację kupców i dołączącą dokumentację dla deweloperów. Przykładowa aplikacja zawiera przykład sposobu wywoływania interfejsów API ochrony przed oszustwami, w tym zdarzeń interfejsu API, takich jak wysyłanie aktualizacji konta klienta, zwrotów i obciążeń zwrotnych w czasie rzeczywistym. Dokumentacja przykładowej aplikacji jest połączona z rzeczywistym kodem przykładowym zawsze, gdy takie linki są możliwe. W przeciwnym razie przykłady kodu istnieją bezpośrednio w dokumentacji.

Aby uzyskać wskazówki dotyczące konfigurowania przykładowej witryny do użycia, zobacz Konfigurowanie przykładowej witryny.

Udostępnij za pośrednictwem

Integrowanie interfejsów API ochrony zakupów

Fazy integracji interfejsu API

Tworzenie aplikacji Firmy Microsoft Entra

Konfigurowanie aplikacji Firmy Microsoft Entra

Tworzenie innej aplikacji

Zarządzanie istniejącymi aplikacjami firmy Microsoft Entra

Generowanie tokenu dostępu

Wymagane identyfikatory i informacje

Przykłady: przykłady kodu pokazujące sposób uzyskiwania tokenu przy użyciu certyfikatu lub wpisu tajnego

Uzyskiwanie tokenu dostępu przy użyciu identyfikatora aplikacji i klucza prywatnego certyfikatu

Uzyskiwanie tokenu dostępu przy użyciu identyfikatora aplikacji i wpisu tajnego

Wywoływanie interfejsów API

Najlepsze rozwiązania

Wyświetlanie przykładowej aplikacji

Opinia

Dodatkowe zasoby