次の方法で共有

アカウント保護 API を統合する

  • [アーティクル]

Microsoft Dynamics 365 Fraud Protection の完全な機能スイートを利用するには、トランザクション データをリアルタイム アプリケーション プログラミング インターフェイス (API) に送信します。 評価エクスペリエンスでは、不正アクセス防止を使用した結果を分析できます。 保護エクスペリエンスでは、構成した規則に基づく決定を受け入れることもできます。

不正アクセス防止の使用方法に応じて、さまざまな アカウント保護 API を使用できます。 たとえば、AccountCreation、AccountLogin、AccountCreationStatus、AccountLoginStatus、AccountUpdate、Label などです。

サポートされているすべてのイベントの詳細については、「Dynamics 365 Fraud Protection API」を参照してください。

設定

サインイン

重要

初期 API のオンボードを完了するには、Microsoft Azure テナントのグローバル 管理リストである必要があります。

Fraud Protection にサインインするには:

  • Fraud Protection ポータルに移動し、サインインし、同意するように求められたら使用条件に同意します。

    この手順により、Azure テナントで Fraud Protection が正しく構成されます。 (最初のサインアップ中に既にこの手順を完了している可能性があります)。

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

重要

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

API を呼び出すために必要なトークンを取得するには、Microsoft Entra アプリケーションを使用する必要があります。 これらのアプリは、Fraud Protection の [リアルタイム API] ページを使用して構成できます。

Microsoft Entra アプリを構成するには:

  1. 左側のナビゲーション ウィンドウで、[構成] を選択し、[リアルタイム API] を選択します。

  2. フィールドに入力してアプリを作成します。 次のフィールドが必要です。

    • アプリケーションの表示名 – アプリのわかりやすい名前を入力します。 最大長は 93 文字です。
    • 環境 – 運用エンドポイントを選択します。
    • 認証方法 – 認証に証明書またはシークレット (パスワード) を使用するかどうかを選択します。 [証明書] を選択した場合は、[ファイルの選択] を選択して公開キーをアップロードします。 トークンを取得するときは、一致する秘密キーが必要です。 [シークレット] を選択すると、アプリの作成後にパスワードが生成されます。

  3. フィールドの入力が完了したら、[アプリケーションの作成] を選択します。

    確認ページには、選択した認証方法に応じて、アプリの名前と ID、および証明書の拇印またはシークレットが要約されます。

重要

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

運用環境で API 呼び出しを実行するために必要な数のアプリを作成できます。

別のアプリを作成するには:

  1. [別のアプリケーションの作成] を選択します。
  2. フィールドに入力してアプリを作成し、[アプリケーションの作成] を選択します。

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

Microsoft Entra アプリを作成したら、[Azure portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps) を使用して管理できます。 詳細については、Azure のドキュメント サイトを参照してください。

不正アクセス防止のリアルタイム API を呼び出す

このセクションの情報を使用して、システムを Fraud Protection と統合します。

必要な ID と情報

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

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

このトークンを生成し、各 API 呼び出しで提供する必要があります。 アクセス トークンの有効期間が制限されていることに注意してください。 新しいアクセス トークンを取得するまで、各アクセス トークンをキャッシュして再利用することをお勧めします。

次の C# コード サンプルでは、証明書またはシークレットを使用してトークンを取得する方法を示す例を示します。 プレースホルダーは、独自の情報を使用して置き換えます。

証明書の拇印

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

シークレット

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

回答

上記のコードはバックグラウンドで HTTP 要求を生成し、次の例のような応答を受け取ります。

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>"
}

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

API を呼び出す

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

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

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

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

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

Note

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

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

その他のリファレンスについては、サンプルのマーチャント アプリを参照し、付属の開発者向けドキュメントを参照してください。 このサンプル アプリでは、Fraud Protection API をリアルタイムで呼び出す方法を示す例を示します。 サンプル アプリのドキュメントは、リンクが可能な場合は常に実際のサンプル コードにリンクされます。 それ以外の場合は、コード サンプルがドキュメントに直接含まれます。

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