Freigeben über

Kaufschutz-APIs integrieren

  • Artikel

In diesem Artikel wird erläutert, wie Echtzeit-Anwendungsprogrammierschnittstellen (APIs) in Microsoft Dynamics 365 Fraud Protection integriert werden.

Um den vollen Umfang von Fraud Protection-Funktionen zu nutzen, senden Sie Ihre Transaktionsdaten an die Echtzeit-Fraud Protection-APIs. In der Evaluierungsfunktion können Sie durch das Senden Ihrer Transaktionsdaten mithilfe von Fraud Protection die Ergebnisse analysieren. In der „Protect“-Erfahrung können Sie Entscheidungen auch basierend auf den von Ihnen konfigurierten Regeln anerkennen.

Je nachdem, wie Sie Fraud Protection verwenden möchten, nutzen Sie ggf. verschiedene Sätze der folgenden Kaufschutz-APIs, wie unten angezeigt:

  • Bestellung
  • Kaufstatus
  • Bankereignis
  • Rückbuchung
  • Rückerstattung
  • Konto aktualisieren
  • Beschriftung

API-Integrationsphasen

Die Integration von Käuferschutz-APIs erfolgt in drei Phasen:

  1. Erstellen Sie Microsoft Entra-Anwendungen über Betrugsschutz.
  2. Erstellen Sie ein Zugriffstoken.
  3. Aufrufen der APIs.

Anmelden

Wichtig

Sie müssen ein globaler Administrator in Ihrem Azure-Mandanten sein, um die Erstanmeldung durchzuführen.

Besuchen Sie die folgenden Portale für jede Umgebung, die Sie verwenden möchten. Melden Sie sich an und akzeptieren Sie die Nutzungsbedingungen, wenn Sie dazu aufgefordert werden.

Erstellen von Microsoft Entra-Anwendungen

Wichtig

Sie müssen Anwendungsadministrator, Cloudanwendungsadministrator oder globaler Administrator in Ihrem Azure-Mandanten sein, um diesen Schritt durchführen zu können.

Um die Token abzurufen, die zum Aufrufen der APIs erforderlich sind, müssen Sie Microsoft Entra-Anwendungen konfigurieren und verwenden, wie in diesem Abschnitt beschrieben.

Konfigurieren von Microsoft Entra-Anwendungen

Führen Sie die folgenden Schritte aus, um Microsoft Entra-Anwendungen zu konfigurieren.

  1. Wählen Sie im Portal "Betrugsschutz" im linken Navigationsbereich "Integration > Erstellen von Microsoft Entra-Anwendungssetup > " jetzt aus.

  2. Füllen Sie die Seite aus, um die App zu erstellen. Es wird empfohlen, eine Microsoft Entra-Anwendung für jede Umgebung zu erstellen, die Sie in Betrugsschutz integrieren möchten.

  3. Geben Sie in den folgenden Pflichtfeldern Werte ein, oder wählen Sie Werte aus:

    • Anwendungsanzeigename – Geben Sie der Anwendung einen beschreibenden Namen. Der Text kann maximal 93 Zeichen umfassen.
    • Authentifizierungsmethode – Wählen Sie aus, ob Sie sich mit Zertifikat oder einem geheimen Schlüssel (Kennwort) authentifizieren möchten.

  4. Wenn Sie die Zertifikatauthentifizierungsmethode ausgewählt haben, gehen Sie folgendermaßen vor:

    1. Wählen Sie Datei wählen, um den öffentlichen Schlüssel hochzuladen. (Sie benötigen den entsprechenden privaten Schlüssel, wenn Sie Token abrufen.)
    2. Wählen Sie Geheim, um automatisch ein Kennwort zu generieren, nachdem die Anwendung erstellt worden ist.

  5. Wenn Sie alle Einstellungen wie erforderlich ausgefüllt haben, wählen Sie Anwendung erstellen aus. Die Bestätigungsseite fasst den Namen, die ID und den Zertifikatsfingerabdruck oder das Geheimnis der App zusammen, abhängig von der ausgewählten Authentifizierungsmethode.

Wichtig

Speichern Sie das Geheimnis oder die Zertifikatsfingerabdruckinformationen als Referenz für die spätere Verwendung. Das Geheimnis wird nur einmal angezeigt.

Weitere Anwendung erstellen

Wählen Sie Erstellen einer weiteren Anwendung aus, um eine weitere Anwendung zu erstellen. Sie können beliebig viele Apps nach Bedarf erstellen, um API-Aufrufe in jeder Ihrer Umgebungen auszuführen.

Verwalten vorhandener Microsoft Entra-Anwendungen

Nachdem Sie Ihre Microsoft Entra-Apps erstellt haben, können Sie sie über die [Azure-Portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps) verwalten. Weitere Informationen finden Sie unter Wie und warum werden Anwendungen zu Microsoft Entra ID hinzugefügt?.

Erstellen eines Zugriffstokens

Um Ihre Systeme sicher in Betrugsschutz zu integrieren, rufen Sie ein Microsoft Entra-Token ab, und stellen Sie es im Header jedes API-Aufrufs bereit.

Hinweis

Zugriffstokens haben eine begrenzte Lebensdauer von 60 Minuten. Wir empfehlen Ihnen, ein Token zwischenzuspeichern und dann erneut zu verwenden, bis dieses sich kurz vor dem Ablauf befindet. Sie können dann ein neues Zugriffstoken erhalten.

Die folgenden Informationen sind erforderlich, um ein Token zu erhalten.

Erforderliche IDs und Informationen

  • Umgebungs-URI – Die URIs für Ihre Sandbox- oder Produktionsumgebung werden in der Registerkarte Konfiguration der Seite API Management im Fraud Protection-Portal angezeigt.
  • Verzeichnis (Mandanten)-ID – Diese Verzeichnis-ID bezeichnet den Globally Unique Identifier (GUID) der Domäne des Mandanten in Azure. Sie wird im Azure-Portal und auf der Registerkarte Konfiguration der Seite API Management im Fraud Protection-Portal angezeigt.
  • Anwendungs-ID (Client-ID) – Diese ID identifiziert die Microsoft Entra-App, die Sie zum Aufrufen von APIs erstellt haben. Rufen Sie die ID der Echtzeit-APIs-Bestätigungsseite ab oder suchen Sie diese später unter App-Registrierungen im Azure-Portal. Es gibt eine ID für jede App, die Sie erstellt haben.
  • Zertifikatsfingerabdruck oder Geheimnis – Rufen Sie den Fingerabdruck oder das Geheimnis der Echtzeit-APIs-Bestätigungsseite ab.
  • Instanz-ID – Diese ID ist die GUID Ihrer Umgebung in Fraud Protection. Es wird in der Integration-Kachel auf dem Fraud Protection-Dashboard angezeigt.

Beispiele: Codebeispiele zeigen, wie Sie mithilfe Ihres Zertifikats oder Geheimnisses ein Token abrufen.

Die folgenden C#-Codebeispiele enthalten Beispiele zum Abrufen eines Tokens mit Ihrem Zertifikat oder Geheimnis. Ersetzen Sie die Platzhalter mit Ihren bestimmten Informationen. Für die beiden C#-Beispiele müssen Sie das Microsoft.Identity.Client NuGet Paket importieren.

Beispiele in anderen Sprachen finden Sie unter https://aka.ms/aaddev.

Rufen Sie ein Zugriffstoken ab, indem Sie eine App-ID und einen privaten Zertifikatschlüssel verwenden

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

Rufen Sie ein Zugriffstoken ab, indem Sie eine App-ID und ein Geheimnis verwenden

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

Das AuthenticationResult-Objekt enthält jeweils den Zugriffstoken Wert und eine ExpiresOn-Eigenschaft, die angibt, wann das Token ungültig wird.

  • POST-Anforderung an:

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

  • Kopfzeilen:

    • Inhaltstyp: application/x-www-form-urlencoded

  • Text (Schlüsselwert):

    • grant_type: client_credentials
    • client_id : {Ihre Client-ID aus dem vorherigen Schritt}
    • client_secret : {Ihr Geheimnis aus dem vorherigen Schritt}
    • Ressource : https://api.dfp.microsoft.com (für Integration, https://api.dfp.microsoft-int.com)

  • Antwort:

    • Verwenden Sie den Wert von Zugang‑Token aus der Antwort für den nächsten Schritt aus..

Weitere Informationen finden Sie in der folgenden Azure-Dokumentationsseite:

Aufrufen der APIs

Gehen Sie zum Aufrufen der APIs folgendermaßen vor.

  1. Übergeben Sie die folgenden erforderlichen HTTP-Kopfzeilen für jede Anforderung.

    Headername Headerwert
    Autorisierung

    Verwenden Sie für diese Kopfzeile das folgende Format. (Ersetzen Sie accesstoken durch den tatsächlichen Tokenwert, der von Microsoft Entra ID zurückgegeben wird.)

    Bearer accesstoken
    x-ms-correlation-id Senden Sie einen neuen GUID-Wert für jeden Satz von API-Aufrufen, die zusammen gemacht werden.
    x-ms-dfpenvid Senden Sie den GUID-Wert Ihrer Instanz-ID.

  2. Erstellen Sie eine ereignisbasierte Nutzlast. Füllen Sie die Ereignisdaten mit den relevanten Informationen vom System aus. Eine Dokumentation für alle unterstützten Ereignisse finden Sie unter Dynamics 365 Fraud Protection-API.

  3. Kombinieren Sie die Kopfzeile (die das Zugriffstoken enthält) und die Nutzlast, und senden Sie diese dann zum Fraud Protection-Endpunkt.

    • POST-Anforderung an:

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

    • Kopfzeilen:

      • x-ms-correlation-id : {Eine GUID, die pro Anfrage eindeutig sein muss}
      • Inhaltstyp: application/json
      • Authorization : {Das Token aus dem vorherigen Schritt}
      • x-ms-dfpenvid : {Die Umgebungs-ID der Zielumgebung}

    • Text:

      • Holen Sie sich den Beispieltext für die Anfrage zum Schutz des Kontos aus der freigegebenen Swagger-Seite.

Notiz

Wenn Sie eine neue Umgebung erstellen, geben Sie bei der Integration die Umgebungs-ID im API-Header an, damit die Transaktionen korrekt weitergeleitet werden können.

Die folgenden Optionen sind für x-ms-dfpenvid im API-Aufruf akzeptabel. Das Verhalten ist identisch.

  • Verwenden Sie die Umgebungs-ID für die aufgerufene Umgebung. Die ID ist auf der Seite Integration im Feld Umgebungs-ID aufgeführt.
  • Verwenden Sie den vollständigen Teil der Kunden-API-ID vom Stamm bis zur untergeordneten Umgebung, die Sie aufrufen, und verwenden Sie den Schrägstrich (/) als Trennzeichen. Zum Beispiel /primary/XYZ.
  • Verwenden Sie den vollständigen Pfad der Umgebungs-ID oder Kunden-API-ID vom Stamm bis zur untergeordneten Umgebung, die Sie aufrufen, und verwenden Sie den Schrägstrich (/) als Trennzeichen. Zum Beispiel: 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Informationen zum Angeben der Kunden-API-ID beim Erstellen einer Umgebung finden Sie im Artikel Umgebungen verwalten.

Bewährte Methoden

  • Jedes Microsoft Entra-Token wird 60 Minuten lang gültig Standard. Wir empfehlen, dass Sie es für eine kürzere Dauer zwischenspeichern und wiederverwenden.
  • Stellen Sie sicher, dass Ihr HttpClient über Keepalive-Verbindungen verfügt.
  • Übergeben Sie immer die x-ms-dfpenvid Kopfzeile und stellen Sie sicher, dass sie auf die Umgebung des Händlers verweist, in dessen Namen Sie Transaktionen senden möchten.
  • Speichern Sie das Geheimnis in einem geheimen Speicher.
  • Übergeben Sie immer die x-ms-correlation-id Kopfzeile für zukünftige Debugging-Sitzungen mit Fraud Protection.
  • Stellen Sie sicher, dass die x-ms-correlation-id Kopfzeile für jede Transaktion eindeutig ist, die an Fraud Protection gesendet wird. 

Beispiel-App anzeigen

Weitere Informationen finden Sie unter Beispielhändler-App und der dazugehörigen Entwicklerdokumentation. Die Beispiel-App ist ein Beispiel dafür, wie Fraud Protection-APIs, einschließlich API-Ereignisse wie das Senden von Kundenkonto-Updates, -Rückerstattungen und Rückbuchungen in Echtzeit aufgerufen werden. Die Dokumentation zur Beispiel-App ist mit dem tatsächlichen Beispielcode verknüpft, wenn diese Links möglich sind. Andernfalls sind Codebeispiele direkt in der Dokumentation.

Eine Anleitung zum Konfigurieren der Beispielwebsite für Ihren Einsatz finden Sie unter Konfigurieren der Beispielwebsite.