次の方法で共有


外部呼び出し

この記事では、外部呼び出しを使用して Microsoft Dynamics 365 Fraud Protection の API からデータを取り込む方法について説明します。

外部呼び出しを使用すると、Microsoft Dynamics 365 Fraud Protection の外部にある API からデータを取り込み、そのデータを使用して情報に基づいた意思決定をリアルタイムで行うことができます。 たとえば、サードパーティのアドレスおよび電話検証サービス、または独自のカスタム スコアリング モデルでは、一部のイベントのリスク レベルを判断するのに役立つ重要な入力が提供される場合があります。 外部呼び出しを使用すると、任意の API エンドポイントに接続し、必要に応じてルール内からそのエンドポイントに要求を行い、そのエンドポイントからの応答を使用して決定を行うことができます。

Note

すべてのイベントに追加のデータが必要な場合は、評価スキーマの一部として送信することもできます。 API 要求の一部としてカスタム データを送信する方法の詳細については、カスタム データのサンプルを参照してください

外部呼び出しで使用できる API の種類

外部呼び出しを作成する前に、次の制限事項について理解しておく必要があります。

  • 不正アクセス防止では現在、匿名、基本、証明書OAuth (Microsoft Entra ID)、OAuth (汎用)OAuth (カスタム トークン) の認証方法のみがサポートされています。
  • 不正アクセス防止では、現在、GETPOSTHTTP メソッドのみがサポートされています。

Note

Microsoft の外部データ プラクティスの詳細については、「外部データプラクティス」を参照してください

外部呼び出しを作成する

外部呼び出しを作成するには、次の手順に従います。

  1. 不正アクセス防止ポータルの左側のナビゲーションで、[外部通話] を選択し、[新しい外部通話] を選択します。

  2. 必要に応じて、次のフィールドを確認して設定します。

    • [名前] – ルールからの外部呼び出しを参照するために使用する名前を入力します。 名前には、数字、文字、アンダースコアのみを含めることができます。 数値で始めることはできません。

      Note

      ルールで外部呼び出しを使用した後は、外部呼び出しの名前を変更することはできません。

    • 説明 – チームが外部通話をすばやく識別するのに役立つ説明を追加します。

    • パラメーター の追加 – パラメーターを使用して、Fraud Protection から API エンドポイントにデータを渡すことができます。 選択した HTTP メソッドに応じて、これらのパラメーターはクエリ文字列または要求本文の一部としてエンドポイントに送信されます。 この手順で定義したパラメーターは、形式 {parameter.\<parameter name\>}を使用して、要求 URL、ヘッダー、本文に手動で追加できます。 すべてのパラメーター値は文字列として解釈されます。 Fraud Protection がエンドポイントへのサンプル呼び出しを行うために使用する各パラメーターのサンプル値を、作成前または [テスト接続] を選択するたびに追加できます。

      Note

      ルール内の関数を Request.CorrelationId() 使用して、受信イベントの関連付け ID を抽出し、外部呼び出しのパラメーター値として渡すことができます。

    • 構成 の追加 – 外部通話セットアップ ページで固定構成データを指定できます。 機密情報については、構成をシークレットとしてマークし、実際の値ではなく Azure Key Vault からシークレット識別子 URL を指定できます。 Azure Key Vault にシークレットを格納し、Fraud Protection へのアクセスを提供する方法については、「Azure Key Vault にパスワードを格納する」を参照してください

    パラメーターと同様に、この手順で定義した構成は、{configuration という形式 を使用して、要求 URL、ヘッダー、または本文に手動で追加できます。<構成名>}。 ただし、ルールから実際の値が渡されるパラメーターとは異なり、サンプルまたは実際の呼び出しを行うときは、外部呼び出しセットアップ ページで指定された構成値が使用されます。

    • Web 要求 – 適切な HTTP メソッド (GET または POST) を選択し、API エンドポイントを入力します。

      Note

      HTTPS エンドポイントのみがサポートされています。

    • 認証 – 受信要求の認証に使用する方法を選択します。 認証、認証固有のフィールド、承認、および Microsoft Entra トークンの詳細については、「認証と承認について」を参照してください

    • ヘッダー - 必要に応じてヘッダーを指定できます。 Content-Type既定値は "application/json" です。 現在、Fraud Protection では、"application/json" コンテンツ タイプと "application/x-www-form-urlencoded" コンテンツ タイプのみがサポートされています。

    • サンプル要求 – 外部呼び出しに送信された要求の例。 要求には、指定したパラメーターの名前と値が反映されている必要があり、編集することはできません。 要求 URL または本文に構成を追加することもできます。

      Note

      GET メソッドの場合、要求本文は含まれません。

      POST メソッドの場合、要求本文が表示されます。 POST 呼び出しのカスタム要求本文を作成するには、[+ 独自の要求をビルドする] を選択します。 サンプル要求は、作成前または [テスト接続] を選択するたびに、エンドポイントへのサンプル呼び出しを行うために使用されます。

    • 応答 のサンプル – API エンドポイントからの正常な応答で返されるデータの例。 このデータは JavaScript Object Notation (JSON) 形式である必要があり、ルールで参照できます。 指定した応答のサンプルがルール エディターに表示され、応答フィールドのオートコンプリートも有効になります。 このフィールドに API からの実際の応答を自動的に入力するには、[API 応答の取得] を選択{}します。

      Note

      外部呼び出しのセットアップを正常に完了するには、サンプル応答をポップする必要があります。

    • タイムアウト – タイムアウトになるまでに要求を待機する時間 (ミリ秒単位) を指定します。1 ~ 5000 の数値を指定する必要があります。

    • 既定の応答 – 要求が失敗した場合、または指定されたタイムアウトを超えた場合に返される既定の応答を指定します。値は有効な JSON オブジェクトまたは JSON 要素である必要があります。

  3. 省略可能: API エンドポイントにサンプル要求を送信し、応答を表示するには、[接続のテスト] を選択します。 詳細については、「 外部呼び出しをテストする」を参照してください。

  4. 必須フィールドの設定が完了したら、[作成] を選択します

外部呼び出しをテストする

Fraud Protection がエンドポイントに接続できることを確認するには、任意の時点で接続をテストします。

  • 新しい外部呼び出しを作成するとき、または既存の外部呼び出しを編集するときに接続をテストするには、すべての必須フィールドを設定して、[接続のテスト] を選択します。 Fraud Protection では、指定したエンドポイントとパラメーターを使用して、外部呼び出しに要求を送信します。 URL、ヘッダー、または要求本文に構成を手動で追加することもできます。
  • Fraud Protection がターゲット エンドポイントに正常に到達した場合は、接続が成功したことを通知する緑色のメッセージ バーがパネルの上部に表示されます。 完全な応答を表示するには、[詳細を表示] を選択します
  • Fraud Protection がターゲット エンドポイントに到達できない場合、または指定したタイムアウト前に応答を受信しない場合は、パネルの上部に赤いメッセージ バーが表示され、生成されたエラーが表示されます。 エラーの詳細を表示するには、[詳細を表示] を選択します

外部呼び出しを監視する

不正アクセス防止ポータルで外部呼び出しを監視する

Fraud Protection には、定義した外部呼び出しごとに 3 つのメトリックが含まれるタイルが表示されます。

  • 1 秒 あたりの要求数 – 要求の合計数を、選択した期間の合計分数で割った値です。
  • 平均待機時間 – 要求の合計数を、選択した期間の合計分数で割った値です。
  • 成功率 – 成功した要求の合計数を、作成された要求の合計数で割った値です。

このタイルに表示される数値とグラフには、ページの右上隅にあるドロップダウン リストで選択した期間のデータのみが含まれます。

Note

メトリックは、アクティブなルールで外部呼び出しが使用されている場合にのみ表示されます。

  1. 外部呼び出しに関するデータをさらに詳しく調べるには、タイルの右上隅にある [パフォーマンス] を選択します。

    不正アクセス防止では、メトリックをより詳細に表示する新しいページが表示されます。

  2. 過去 3 か月間の任意の期間のメトリックを表示するには、ページの上部にある日付範囲の設定を調整します。

前に説明した 3 つのメトリックに加えて、 エラー グラフが表示されます。 このグラフには、エラーの種類とコード別のエラーの数が表示されます。 時間の経過に伴うエラー数を表示したり、エラーの分布を表示したりするには、[円グラフ] を選択 します

HTTP クライアント エラー (400、401、403) に加えて、次のエラーが表示される場合があります。

  • 無効なアプリケーション ID – 指定されたアプリケーション ID がテナントに存在しないか、無効です。
  • Microsoft Entra エラー – Microsoft Entra トークンを取得できませんでした。
  • 定義が見つかりません – 外部呼び出しは削除されましたが、ルール内で引き続き参照されます。
  • タイムアウト – ターゲットへの要求に、指定されたタイムアウトよりも長い時間がかかりました。
  • 通信エラー – ネットワークの問題またはターゲットが使用できないために、ターゲットへの接続を確立できませんでした。
  • サーキット ブレーカー – 外部呼び出しが繰り返し失敗し、特定のしきい値を超えた場合、それ以降のすべての呼び出しは短い間隔で中断されます。
  • 不明なエラー – Dynamics 365 の内部エラーが発生しました。

イベント トレースを使用して外部呼び出しを監視する

Fraud Protection のイベント トレース機能を使用して、外部呼び出しに関連するイベントを Azure Event Hubs または Azure Blob Storage の独自のインスタンスに転送できます。 Fraud Protection ポータルの [イベント トレース] ページで、外部呼び出しに関連する次の 2 つのイベントをサブスクライブできます。

  • FraudProtection.Monitoring.ExternalCalls
  • FraudProtection.Errors.ExternalCalls

外部呼び出しに対して要求が行われるたびに、イベントが FraudProtection.Monitoring.ExternalCalls 名前空間に送信されます。 イベント ペイロードには、呼び出しの待機時間、要求の状態、および要求がトリガーされたルールと句に関する情報が含まれます。

外部呼び出しが失敗すると、イベントが FraudProtection.Errors.ExternalCalls 名前空間に送信されます。 イベント ペイロードには、外部呼び出しに送信された URI 要求と本文、および受信した応答が含まれます。

イベント トレースの詳細、イベントをサブスクライブする方法、およびイベントで実行できる操作については、「イベント トレース」を参照してください

このデータを組織のワークフローと統合し、カスタムの監視、アラート、レポートを設定する方法については、「Event Hubs を使用した拡張性」を参照してください

外部呼び出しを管理する

  • 既存の外部通話を編集するには、カード ヘッダーの [編集] を選択します。

    Note

    ルールで外部呼び出しを使用した後は、外部呼び出しの名前とパラメーターを変更することはできません。

  • 既存の外部呼び出しを削除するには、省略記号 (...) を選択し、[削除] を選択 します

    Note

    ルールで参照された外部呼び出しは削除できません。

  • 外部呼び出しの詳細なパフォーマンス メトリックを表示するには、[パフォーマンス] を選択します

  • Fraud Protection が外部呼び出しに接続できることをテストするには、省略記号 (...) を選択し、[接続のテスト] を選択します

ルールで外部呼び出しを使用する

外部呼び出しを使用して意思決定を行うには、ルールから参照します。

たとえば、ルールで myCall という名前の外部呼び出しを参照するには、次の構文を使用します。

External.myCall()

myCall に IPaddress などのパラメーターが必要な場合は、次の構文を使用します。

External.myCall(@"device.ipAddress")

ルール内の Diagnostics オブジェクトにアクセスすることもできます。これを使用すると、外部呼び出し応答から重要な診断情報とデバッグ情報を検出できます。 Diagnostics オブジェクトには、要求ペイロード、エンドポイント、HttpStatus コード、エラー メッセージ、待機時間が含まれています。 これらのフィールドは、ルール エクスペリエンスでアクセスでき、Observe Output メソッドと共に使用してカスタム プロパティを作成できます。 ルールでオブジェクトのフィールドを使用するには、対応する拡張メソッド .GetDiagnostics()を使用して Diagnostics オブジェクトを作成する必要があります。

次の例は、Diagnostics オブジェクトを使用したサンプル ルールを示しています。

LET $extResponse = External. myCall(@"device.ipAddress")
LET $extResponseDiagnostics = $extResponse.GetDiagnostics()
OBSERVE Output(Diagnostics = $extResponseDiagnostics ) 
WHEN $extResponseDiagnostics.HttpStatusCode != 200

ルールの言語と、ルールで外部呼び出しを使用する方法については、言語リファレンス ガイド参照してください。

Note

ルールで外部呼び出しを使用すると、ルールの待機時間が長くなる可能性があります。

外部呼び出しは、Functions から呼び出すこともできます。 詳細については、「関数」を参照してください。

認証と承認について

データが安全にアクセスされるようにするために、API は多くの場合、要求の送信者を認証して、データにアクセスするアクセス許可があることを確認します。 Fraud Protection の外部呼び出しでは、次の認証方法がサポートされています。

  • 匿名
  • 基本
  • 証明書
  • OAuth (Microsoft Entra ID) (以前の Azure Active Directory)
  • OAuth (汎用)
  • OAuth (カスタム トークン)

Note

現在、Fraud Protection では、次の HTTP メソッドのみがサポートされています。

  • GET
  • 投稿

匿名

[匿名] を選択した場合、ターゲット エンドポイントへの HTTP 要求の承認ヘッダーは空白になります。 ターゲット エンドポイントに承認ヘッダーが必要ない場合は、このオプションを使用します。 たとえば、エンドポイントで API キーを使用する場合は、Web 要求フィールドに入力する要求 URL の一部としてキーと値のペアを構成します。 その後、ターゲット エンドポイントは、要求 URL の API キーが許可されているかどうかを検証し、アクセス許可を付与するかどうかを決定できます。

基本

認証方法として [基本] を選択した場合は、次の情報を入力して外部呼び出しを設定します。

  • ユーザー名 – 接続先の URL のユーザー名を指定します。
  • パスワード URL – 基本認証用に Azure Key Vault のパスワード識別子 URL を指定します。 Azure Key Vault にパスワードを格納し、Fraud Protection へのアクセスを提供する方法については、「Azure Key Vault にパスワードを格納する」を参照してください

証明書

認証方法として [証明書] を選択した場合は、次の情報を入力して外部呼び出しを設定します。

OAuth (Microsoft Entra ID)

認証方法として OAuth (Microsoft Entra ID) (旧称 Azure Active Directory) を選択した場合は、次の追加情報を指定して外部呼び出しを設定します。

  • 対象ユーザー - 認証方法として OAuth (Microsoft Entra ID) を選択した場合は、対象ユーザーを指定するように求められます。 既存の Azure アプリケーションを対象ユーザーとして使用することも、Fraud Protection ポータル内の統合エクスペリエンスを使用して新しいアプリケーションを作成することもできます。 対象ユーザーが外部の通話/サービスにアクセスするアクセス許可を持っていることを確認します。 Microsoft Entra 認証を構成する方法の詳細については、「Microsoft Entra 認証を構成する」を参照してください
  • アプリケーション ID – Fraud Protection サブスクリプション テナント内の新規または既存の Microsoft Entra アプリケーションのアプリケーション ID を指定する必要があります。 Azure Key Vault で証明書を生成します。 Fraud Protection アプリには、この Azure Key Vault への読み取りアクセス権が必要です。 Azure Key Vault で証明書を生成し、Fraud Protection へのアクセスを提供する方法については、「Azure Key Vault で証明書を作成する」を参照してください。 この Microsoft Entra アプリケーションに証明書を読み込みます。 Microsoft Entra アプリケーションを作成および管理する方法の詳細については、「Microsoft Entra アプリケーションの作成」を参照してください
  • 証明書 URL – Azure Key Vault の証明書識別子 URL を指定します。これは、先ほど Microsoft Entra アプリにアップロードしたのと同じ証明書です。

Microsoft Entra ID を選択すると、ターゲット エンドポイントへの HTTP 要求の承認ヘッダーにベアラー トークンが含まれます。 ベアラー トークンは、Microsoft Entra ID によって発行された JSON Web トークン (JWT) です。 JWT の詳細については、「Microsoft ID プラットフォームアクセス トークン」を参照してください。 Fraud Protection は、次の例に示すように、要求承認ヘッダーの必要な形式でトークン値をテキスト "Bearer" に追加します。

ベアラー <トークン>

トークン要求

次の表に、Fraud Protection で問題が発生するベアラー トークンで期待できる要求の一覧を示します。

名前 要求 説明
テナント ID tid この要求は、Fraud Protection アカウントに関連付けられているサブスクリプションの Azure テナント ID を識別します。 Fraud Protection ポータルでテナント ID を検索する方法については、「必要な ID と情報」を参照してください。 Azure portal でテナント ID を検索する方法については、「Microsoft Entra テナント ID を検索する方法」を参照してください
対象者 aud この要求は、呼び出す外部サービスへのアクセスが承認された Azure アプリケーションを識別します。 Microsoft Entra 認証を構成する方法については、「Microsoft Entra 認証の構成」を参照してください
アプリケーション ID アプリID この要求は、トークンを要求しているユーザーを識別します。 Microsoft Entra 認証を構成する方法の詳細については、「Microsoft Entra 認証を構成する」を参照してください

API がトークンを受け取ったら、トークンを開き、上記の各要求がその説明と一致することを検証する必要があります。

JwtSecurityTokenHandler を使用して受信要求を認証する方法を示す例を次に示します。

string authHeader = "Bearer <token>"; // the Authorization header value
var jwt = new JwtSecurityTokenHandler().ReadJwtToken(token);
string tid = jwt.Claims.Where(c => c.Type == "tid").FirstOrDefault()?.Value;
string aud = jwt.Claims.Where(c => c.Type == "aud").FirstOrDefault()?.Value;
string appid = jwt.Claims.Where(c => c.Type == "appid").FirstOrDefault()?.Value;
if(tid != "<my tenant id>" || aud != "<my audience>" || appid != "<my application id>")
{
    throw new Exception("the token is not authorized.");
}

OAuth (汎用)

認証方法として OAuth (汎用) を選択した場合は、次の追加情報を指定して外部呼び出しを設定します。

  • トークン URL – トークン呼び出しの API エンドポイント。
  • トークン認証 – トークン呼び出しに匿名認証方法または基本認証方法を選択します。
  • クライアント ID/ユーザー名 – 匿名認証のクライアント ID、または基本認証のユーザー名。
  • クライアント シークレット/パスワード URL – 匿名認証用の Azure Key Vault からのクライアント シークレット識別子 URL、または基本認証用のパスワード識別子 URL。 Azure Key Vault にシークレットを格納し、Fraud Protection へのアクセスを提供する方法については、「Azure Key Vault にパスワードを格納する」を参照してください
  • スコープ – スコープの値。
  • リソース – リソース値 (必要な場合)。

OAuth (カスタム トークン)

認証方法として OAuth (カスタム トークン) を選択した場合は、[+ トークン要求の作成] を選択し、次の情報を指定することで、カスタム OAuth トークン呼び出しを構成できます。

  • 構成 – トークン呼び出しで渡す構成値。 構成の詳細については、「外部呼び出しの作成」を参照してください
  • トークン URL – トークン呼び出しの API エンドポイント。
  • トークン認証 – トークン呼び出しの匿名認証方法または基本認証方法を選択します。
  • ユーザー名 – 基本認証のユーザー名。
  • パスワード URL – 基本認証用の Azure Key Vault のパスワード識別子 URL。 Azure Key Vault にパスワードを格納し、Fraud Protection へのアクセスを提供する方法については、「Azure Key Vault にパスワードを格納する」を参照してください
  • ヘッダー – ヘッダー値。
  • サンプル要求 – トークン エンドポイントに送信される要求の例:
    • サンプル要求 URL – サンプル呼び出しの実行に使用される要求 URL を示す読み取り専用フィールド。
    • 要求本文のサンプル – [+ 独自の要求をビルドする] を選択して、トークン呼び出しのカスタム要求本文を作成できます。 サンプル要求 URL と本文は、作成前または [テスト接続] を選択するたびに、トークン エンドポイントへのサンプル呼び出しを行うために使用されます。
  • タイムアウト – 1 から 5000 までのタイムアウト期間を指定します。

Azure Key Vault を使用する

お客様のデータ セキュリティに対する Microsoft のコミットメントに従って、Fraud Protection では、シークレット、パスワード、証明書の外部呼び出しセットアップ ページで Azure Key Vault の URL のみを提供できます。

Azure Key Vault にパスワードを格納する

シークレットまたはパスワードを Azure Key Vault にアップロードし、Fraud Protection へのアクセス許可を付与するには、次の手順に従います。

  1. テナントの資格情報を 使用して Azure portal にサインインします。
  2. 既存のキー コンテナーを使用するか、「クイック スタート: Azure portal を使用してキー コンテナーを作成する」の手順に従って、新しいキー コンテナーを作成できます。 シークレットの アクセス許可で [取得 ] と [一覧 ] が選択されていることを確認します。
  3. 左側のナビゲーション ウィンドウで、[シークレット] を選択し、[生成/インポート] を選択します
  4. [シークレットの作成] ページで、シークレット の名前を入力します。 シークレット値は、外部呼び出しを使用して接続する Web URL のパスワードである必要があります。
  5. 必須フィールドに情報を入力し、[作成] を選択します。 後で Fraud Protection ポータルで外部呼び出しを設定するときに使用するシークレット識別子をコピーして保存します。
  6. 左側のナビゲーション ウィンドウの設定、[アクセス ポリシー] を選択し、[新しいアクセス ポリシーの追加] を選択します。
  7. [シークレットのアクセス許可] セクションで、[取得] ボックスと [リスト] チェックボックスを選択します。
  8. [プリンシパル] フィールドと [承認済みアプリケーション] フィールドで、Dynamics 365 Fraud Protection を検索し、[選択] を選択します
  9. [追加] を選択し、[保存] を選択します

Azure Key Vault に証明書を作成する

Azure Key Vault に証明書を作成するには、次の手順に従います。

  1. テナントの資格情報を 使用して Azure portal にサインインします。
  2. 既存のキー コンテナーを使用するか、「クイック スタート: Azure portal を使用してキー コンテナーを作成する」の手順に従って、新しいキー コンテナーを作成できます。 シークレットの アクセス許可で [取得 ] と [リスト] が選択されていることを確認します。
  3. 左側のウィンドウで [証明書] を選択し、[生成/インポート] をクリックします
  4. [証明書の作成] ページで、証明書 の名前を入力します。 [サブジェクト] に、証明書のサブジェクトを入力します。
  5. 必須フィールドに情報を入力し、[作成] を選択します
  6. 左側のナビゲーション ウィンドウで、[アクセス ポリシー] を選択し、[作成] を選択します
  7. [証明書のアクセス許可] セクションで、[取得] ボックスと [リスト] チェックボックスを選択します。
  8. [プリンシパル] フィールドと [承認済みアプリケーション] フィールドで、Dynamics 365 Fraud Protection を検索し、[選択] を選択します
  9. [追加] を選択し、[保存] を選択します

Azure Key Vault で証明書を生成する方法の詳細については、「Azure Key Vault での証明書署名要求の作成とマージ」を参照してください

外部データプラクティス

お客様は、不正アクセス防止の外部通話機能を通じて Microsoft に提供するデータ セットに関連するデータ保護法、契約上の制限、ポリシーを含め、適用されるすべての法律および規制を遵守する責任があることを認識します。 さらに、お客様による不正アクセス防止の使用は、Microsoft 顧客契約に記載されている使用制限の対象となることを認めます。これは、支払いトランザクションを続行するかどうかを決定する唯一の要因として、Fraud Protection (i) を使用しないことを示しています。(ii) 個人の財務状態、財務履歴、信用力、または保険、住宅、雇用の資格を決定する要因として、(iii) 法的効果を生み出す、または人に重大な影響を与える意思決定を行う。 また、不正アクセス防止の外部呼び出し機能の使用に関連する機密または高度に規制されたデータ型を提供または使用することも禁止されています。 Fraud Protection の外部呼び出し機能でデータ セットまたはデータ型を使用して、このプロビジョニングに準拠していることを確認する前に、時間をかけて確認してください。 Microsoft は、お客様がこのプロビジョニングに準拠していることを確認する権利も留保します。

その他のリソース