購入保護 API を統合する

この記事では、Microsoft Dynamics 365 Fraud Protection でリアルタイム アプリケーション プログラミング インターフェイス (API) を統合する方法について説明します。

不正防止機能の完全なスイートを利用するには、トランザクション データをリアルタイムの Fraud Protection API に送信する必要があります。 評価エクスペリエンスでは、トランザクション データを送信することで、Fraud Protection を使用した結果を分析できます。 保護エクスペリエンスでは、構成した規則に基づいて決定を受け入れることもできます。

Fraud Protection の使用方法によっては、次の購入保護 API の異なるセットを使用する場合があります。

• Purchase
• PurchaseStatus
• BankEvent
• 配賦
• 払戻
• UpdateAccount
• Label

API 統合フェーズ

購入保護 API の統合は、次の 3 つのフェーズで行われます。

1. Fraud Protection を使用して Microsoft Entra アプリケーションを作成します 。
2. アクセス トークンを生成します。
3. API を呼び出します。

サインイン

重要

初期サインインを完了するには、Azure テナントのグローバル管理者である必要があります。

使用する環境ごとに、次のポータルにアクセスします。 サインインし、要求された場合は使用条件に同意します。

• サンドボックス環境
• 運用環境 (初期サインアップ中に運用環境でこの手順を既に完了している可能性があります)。

Microsoft Entra アプリケーションを作成する

重要

この手順を完了するには、Azure テナントのアプリケーション管理者、クラウド アプリケーション管理者、またはグローバル管理者である必要があります。

API を呼び出すために必要なトークンを取得するには、このセクションで説明するように Microsoft Entra アプリケーションを構成して使用する必要があります。

Microsoft Entra アプリケーションを構成する

Microsoft Entra アプリケーションを構成するには、次の手順に従います。

1. Fraud Protection ポータルの左側のナビゲーション ウィンドウで、[Integration > Create Microsoft Entra Application > Setup now] を選択します。

2. ページを完成してアプリを作成します。 Fraud Protection と統合する環境ごとに 1 つの Microsoft Entra アプリケーションを作成することをお勧めします。

3. 次の必須フィールドの値を入力または選択します。

   • アプリケーションの表示名 – アプリケーションにわかりやすい名前を付けます。 最大長は 93 文字です。
   • 認証方法 – 証明書またはシークレット (パスワード) を使用して認証するかどうかを選択します。

4. 証明書の認証方法を選択した場合は、次の手順に従います。

   1. [ファイルの選択] を選択して公開キーをアップロードします。 (トークンを取得するときは、一致する秘密キーが必要です)。
   2. アプリケーションの作成後にパスワードを自動的に生成するには、[シークレット] を選択します。

5. 必須フィールドの設定が完了したら、[アプリケーションの作成] を選択します。 確認ページには、選択した認証方法に応じて、アプリの名前、ID、証明書の拇印またはシークレットが要約されます。

重要

後で参照するために、シークレットまたは証明書の拇印情報を保存します。 シークレットは 1 回だけ表示されます。

別のアプリケーションを作成する

別のアプリケーションを作成するには、[別のアプリケーションの作成] を選択します。 各環境で API 呼び出しを実行するために必要な数のアプリを作成できます。

既存の Microsoft Entra アプリケーションを管理する

Microsoft Entra アプリを作成したら、[Azure portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps) を使用して管理できます。 詳細については、「アプリケーションを Microsoft Entra に追加する方法と理由」を参照してください。

アクセス トークンを生成する

システムを Fraud Protection と安全に統合するには、Microsoft Entra トークンを取得し、各 API 呼び出しのヘッダーに提供します。

Note

アクセス トークンの有効期間は 60 分に制限されています。 有効期限が近づくまでトークンをキャッシュして再利用することをお勧めします。 その後、新しいアクセス トークンを取得できます。

トークンを取得するには、次の情報が必要です。

必要な ID と情報

• 環境 URI – サンドボックスまたは運用環境の URI が、Fraud Protection ポータルの API Management ページの [構成] タブに表示されます。
• ディレクトリ (テナント) ID – この ID は、Azure のテナントの doメイン のグローバル一意識別子 (GUID) です。 これは、Azure portal と、Fraud Protection ポータルの API Management ページの [構成] タブに表示されます。
• アプリケーション (クライアント) ID – この ID は、API を呼び出すために作成した Microsoft Entra アプリを識別します。 リアルタイム API の確認ページから ID を取得するか、後で Azure portal のアプリの登録で見つけます。 作成したアプリごとに 1 つの ID があります。
• 証明書の拇印またはシークレット – リアルタイム API の確認ページから拇印またはシークレットを取得します。
• インスタンス ID – この ID は、Fraud Protection の環境の GUID です。 不正アクセス防止ダッシュボードの [統合 ] タイルに表示されます。

例: 証明書またはシークレットを使用してトークンを取得する方法を示すコード サンプル

次の C# コード サンプルでは、証明書またはシークレットを使用してトークンを取得する例を示します。 プレースホルダーを特定の情報に置き換えます。 どちらの C# サンプルでも、Microsoft.Identity.Client NuGet パッケージをインポートする必要があります。

その他の言語のサンプルについては、以下を参照してください https://aka.ms/aaddev。

アプリ ID と秘密証明書キーを使用してアクセス トークンを取得する

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

アプリ ID とシークレットを使用してアクセス トークンを取得する

/// <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 オブジェクトには、AccessToken 値と、トークンが無効になるタイミングを示す ExpiresOn プロパティが含まれています。

• POST 要求:

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

• Headers:

  • Content-type: application/x-www-form-urlencoded

• 本文 (キー値):

  • grant_type: client_credentials
  • client_id: {前の手順のクライアント ID}
  • client_secret: {前の手順のシークレット}
  • resource: https://api.dfp.microsoft.com (int, https://api.dfp.microsoft-int.comの場合)

• 応答:

  • 次の手順では、応答の access_token の値を使用します。

詳細については、次の Azure ドキュメントを参照してください。

• Microsoft Authentication Library (MSAL) の概要
• Microsoft Authentication Library (MSAL) を使用してトークンを取得し、キャッシュする

API を呼び出す

API を呼び出すには、次の手順に従います。

1. 次の必須 HTTP ヘッダーを各要求に渡します。

   ヘッダー名	ヘッダー値
   承認	このヘッダーには、次の形式を使用します。 (accesstoken は、Microsoft Entra ID によって返される実際のトークン値に置き換えます。 Bearer accesstoken
   x-ms-correlation-id	一緒に作成した各 API 呼び出しセットで新しい GUID 値を送信します。
   x-ms-dfpenvid	インスタンス ID の GUID 値を送信します。

2. イベント ベースのペイロードを生成します。 イベント データにシステムの関連情報を入力します。 サポートされているすべてのイベントのドキュメントについては、Dynamics 365 Fraud Protection API を参照してください。

3. ヘッダー (アクセス トークンを含む) とペイロードを組み合わせて、Fraud Protection エンドポイントに送信します。

   • POST 要求:

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

   • Headers:

     • x-ms-correlation-id: {A GUID。要求ごとに一意である必要があります}
     • content-type: application/json
     • 承認: {前の手順のトークン}
     • x-ms-dfpenvid: {ターゲット環境の環境 ID}

   • 本文は次のようになります。

     • 共有 Swagger ページからサンプル アカウント保護要求本文を取得します。

Note

新しい環境を作成する場合は、統合時に API ヘッダーに環境 ID を含めて、トランザクションを正しくルーティングできるようにします。

次のオプションは、API 呼び出しの x-ms-dfpenvid で許容され、動作は同じです。

• 呼び出す環境の環境 ID を使用します。 ID は、[環境 ID] フィールドの [統合] ページに一覧表示されます。
• スラッシュ (/) を区切り記号として使用して、ルートから呼び出している子環境への Customer API ID の完全なパターンを使用します。 たとえば、 /primary/XYZ です。
• スラッシュ (/) を区切り記号として使用して、ルートから呼び出している子環境への環境 ID または顧客 API ID の完全なパスを使用します。 たとえば、 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ などです。

環境の作成時に顧客 API ID を指定するには、環境の管理に関する記事を参照してください。

ベスト プラクティス

• 各 Microsoft Entra トークンはメイン 60 分間有効です。 より短い期間キャッシュし、再利用することをお勧めします。
• HttpClient にキープアライブ接続があることを確認します。
• x-ms-dfpenvid ヘッダーを常に渡し、トランザクションを送信するマーチャントの環境を指していることを確認します。
• シークレット ストアにシークレットを格納します。
• Fraud Protection を使用した今後の デバッグ セッションでは、常に x-ms-correlation-id ヘッダーを渡します。
• x-ms-correlation-id ヘッダーが、Fraud Protection に送信されるすべてのトランザクションで一意であることを確認します。 

サンプル アプリを表示する

追加のリファレンスについては、サンプルのマーチャント アプリと付属の開発者向けドキュメントを参照してください。 このサンプル アプリでは、顧客アカウントの更新の送信、払い戻し、チャージバックなどの API イベントをリアルタイムで含め、Fraud Protection API を呼び出す方法の例を示します。 サンプル アプリのドキュメントは、そのようなリンクが可能な場合は常に実際のサンプル コードにリンクされます。 それ以外の場合、コード サンプルはドキュメントに直接存在します。

使用するサンプル サイトを構成する方法のガイダンスについては、「サンプル サイトの構成」を参照してください。