外部呼び出し
外部呼び出しを使用すると、Microsoft Dynamics 365 Fraud Protection の外部にある API からデータを取り込み、そのデータを使用して情報に基づいた意思決定をリアルタイムで行うことができます。 たとえば、サードパーティのアドレスおよび電話検証サービス、または独自のカスタム スコアリング モデルでは、一部のイベントのリスク レベルを判断するのに役立つ重要な入力が提供される場合があります。 外部呼び出しを使用すると、任意の API エンドポイントに接続し、必要に応じてルール内からそのエンドポイントに要求を行い、そのエンドポイントからの応答を使用して決定を行うことができます。
Note
すべてのイベントにこの追加データが必要な場合は、評価スキーマの一部として送信することもできます。 API 要求の一部としてカスタム データを送信する方法の詳細については、カスタム データのサンプルを参照してください。
外部呼び出しで使用できる API の種類
外部呼び出しを作成する前に、次の制限事項について理解しておく必要があります。
- 不正アクセス防止では、現在、匿名と AAD の認証方法のみがサポートされています。
- 不正アクセス防止では、現在、GET と POST の HTTP メソッドのみがサポートされています。
外部呼び出しを作成する
不正アクセス防止ポータルの左側のナビゲーションで、[外部通話] を選択し、[新しい外部通話] を選択します。
必要に応じて、次のフィールドを確認して設定します。
[名前] – ルールからの外部呼び出しを参照するために使用する名前を入力します。 名前には、数字、文字、アンダースコアのみを含めることができます。 数値で始めることはできません。
Note
ルールで外部呼び出しを使用した後は、外部呼び出しの名前を変更することはできません。
説明 – チームが外部通話をすばやく識別するのに役立つ説明を追加します。
Web 要求 – 適切な HTTP メソッド (GET または POST) を選択し、API エンドポイントを入力します。
Note
HTTPS エンドポイントのみがサポートされています。
定期的なウォームアップ呼び出しを有効にする - 外部呼び出 しエンドポイントへのトラフィックが少なすぎると、接続がコールドになり、外部サービスからの応答の待機時間が長くなる可能性があります。 この問題を軽減するには、[外部通話のセットアップ] ページからウォームアップ呼び出しを有効にします。 トグルを使用してウォームアップ呼び出しを有効にします。 有効な GET Keep-alive URL を指定する必要があります。 プライマリ エンドポイントと同様に、キープアライブ エンドポイントもテスト接続に合格する必要があります。 ウォームアップ呼び出しを有効にして外部呼び出しを構成した場合、トラフィック量が少なすぎると、Fraud Protection は GET メソッドのみを使用してキープアライブ エンドポイントへの匿名ウォームアップ呼び出しを自動的に行います。
Note
ウォームアップ呼び出しでは、パラメーター、構成、または構成可能なヘッダーを使用できません。
認証 – 受信要求の認証に使用する方法を選択します。
- [匿名] を選択した場合、承認ヘッダーは送信されません。
- AAD を選択すると、テナントに Azure Active Directory (Azure AD) トークンが生成され、Bearer <トークン>が承認ヘッダーとして使用されます。
認証、承認、および Azure AD トークンの詳細については、この記事の後半の「認証と承認について」セクションを参照してください。
対象ユーザー - 認証方法として AAD を選択した場合は、対象ユーザーを指定するように求められます。 既存の Azure アプリケーションを対象ユーザーとして使用することも、Fraud Protection ポータル内の統合エクスペリエンスを使用して新しいアプリケーションを作成することもできます。 対象ユーザーが外部通話/サービスにアクセスするアクセス許可を持っていることを確認します。 Azure Active Directory (Azure AD) 認証を構成する方法の詳細については、「Azure AD 認証の構成」を参照してください。
アプリケーション ID – Fraud Protection サブスクリプション テナント内の新規または既存の Azure AD アプリケーションのアプリケーション ID も指定する必要があります。 Azure Key Vault で証明書を生成します。 Fraud Protection アプリには、この Azure Key Vault への読み取りアクセス権が必要です。 この Azure AD アプリケーションに証明書を読み込みます。 Azure AD アプリケーションを作成および管理する方法の詳細については、「Azure Active Directory アプリケーションの作成」を参照してください。
証明書 URL – Azure Key Vault から証明書識別子の URL を指定します。 これは、前の手順で Azure AD アプリに読み込んだのと同じ証明書です。 Azure Key Vault で証明書を生成する方法の詳細については、「Azure Key Vault での証明書署名要求の作成とマージ」を参照してください 。
パラメーター の追加 – パラメーターを使用して、Fraud Protection から API エンドポイントにデータを渡すことができます。 選択した HTTP メソッドに応じて、これらのパラメーターはクエリ文字列または要求本文の一部としてエンドポイントに送信されます。
各パラメーターのサンプル値を追加できます。 Fraud Protection では、これらのパラメーター値を使用して、作成前または [テスト] を選択するたびに、エンドポイントへのサンプル呼び出しを行います。
Note
すべてのパラメーター値は文字列として解釈されます。
サンプル要求 – 外部呼び出しに送信される要求の例を指定します。 要求には、指定したパラメーターの名前と値が反映されている必要があり、編集することはできません。
GET メソッドの場合、要求 URL が表示されます。 POST メソッドの場合、要求本文が表示されます。
サンプル要求は、作成前または [テスト] を選択するたびに、エンドポイントへのサンプル呼び出しを行うために使用されます。
応答 のサンプル – API エンドポイントからの正常な応答で返されるデータの例を提供します。 このデータは JavaScript Object Notation (JSON) 形式である必要があり、ルールで参照できます。 ここで指定するサンプルは、ルールを作成するときに表示されます。
このフィールドに API からの実際の応答を自動的に入力するには、[テスト] を選択します。
タイムアウト – タイムアウトになるまでに要求を待機する時間 (ミリ秒単位) を指定します。1 ~ 1000 の数値を指定する必要があります。
既定の応答 – 要求が失敗した場合、または指定されたタイムアウトを超えた場合に返される既定の応答を指定します。値は有効な JSON オブジェクトまたは JSON 要素である必要があります。
省略可能: API エンドポイントにサンプル要求を送信し、応答を表示するには、[テスト] を選択します。 詳細については、次のセクション 「外部呼び出しをテストする」を参照してください。
必須フィールドの設定が完了したら、[作成] を選択します。
外部呼び出しをテストする
Fraud Protection がエンドポイントに接続できることを確認するには、任意の時点で接続をテストします。
新しい外部呼び出しの作成中または既存の外部呼び出しの編集中に接続をテストするには、すべての必須フィールドを設定して、[テスト] を選択します。
Fraud Protection では、指定したエンドポイントとパラメーターを使用して、外部呼び出しに要求を送信します。
- Fraud Protection がターゲット エンドポイントに正常に到達した場合は、接続が成功したことを通知する緑色のメッセージ バーがパネルの上部に表示されます。 完全な応答を表示するには、[応答の詳細を表示] を選択します。
- Fraud Protection がターゲット エンドポイントに到達できない場合、または指定されたタイムアウト前に応答を受信しない場合は、パネルの上部に赤いメッセージ バーが表示され、発生したエラーが表示されます。 エラーの詳細を表示するには、[エラーの詳細を表示] を選択 します。
外部呼び出しを監視する
不正アクセス防止ポータルで外部呼び出しを監視する
Fraud Protection には、定義した外部呼び出しごとに 3 つのメトリックが含まれるタイルが表示されます。
- 1 秒 あたりの要求数 – 要求の合計数を、選択した期間の合計分数で割った値です。
- 平均待機時間 – 要求の合計数を、選択した期間の合計分数で割った値です。
- 成功率 – 成功した要求の合計数を、作成された要求の合計数で割った値です。
このタイルに表示される数値とグラフには、ページの右上隅にあるドロップダウン リストで選択した期間のデータのみが含まれます。
Note
メトリックは、アクティブなルールで外部呼び出しが使用されている場合にのみ表示されます。
外部呼び出しに関するデータをさらに詳しく調べるには、タイルの右上隅にある [パフォーマンス] を選択します。
不正アクセス防止では、メトリックをより詳細に表示する新しいページが表示されます。
過去 3 か月間の任意の期間のメトリックを表示するには、ページの上部にある日付範囲の設定を調整します。
前に説明した 3 つのメトリックに加えて、 エラー グラフが表示されます。 このグラフには、エラーの種類とコード別のエラーの数が表示されます。 時間の経過に伴うエラー数を表示したり、エラーの分布を表示したりするには、[円グラフ] を選択 します。
HTTP クライアント エラー (400、401、403) に加えて、次のエラーが表示される場合があります。
- 無効なアプリケーション ID – 指定されたアプリケーション ID がテナントに存在しないか、無効です。
- AAD エラー – Azure AD トークンを取得できませんでした。
- 定義が見つかりません – 外部呼び出しは削除されましたが、ルール内で引き続き参照されます。
- タイムアウト – ターゲットへの要求に、指定されたタイムアウトよりも長い時間がかかりました。
- 通信エラー – ネットワークの問題またはターゲットが使用できないために、ターゲットへの接続を確立できませんでした。
- サーキット ブレーカー – 外部呼び出しが継続的に失敗し、特定のしきい値を超えた場合、それ以降のすべての呼び出しは短い間隔で中断されます。
- 不明なエラー – 内部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")
ルールの言語と、ルールで外部呼び出しを使用する方法については、言語リファレンス ガイドを参照してください。
Note
ルールで外部呼び出しを使用すると、ルールの待機時間が長くなる可能性があります。
認証と承認について
データが安全にアクセスされるようにするために、API は多くの場合、要求の送信者を認証して、データにアクセスするアクセス許可があることを確認します。 Fraud Protection の外部呼び出しでは、匿名と AAD の 2 つの認証方法がサポートされています。
[匿名] を選択した場合、ターゲット エンドポイントへの HTTP 要求の承認ヘッダーは空白のままです。 ターゲット エンドポイントに承認ヘッダーが必要ない場合は、このオプションを使用します。 たとえば、エンドポイントで API キーを使用する場合は、Web 要求フィールドに入力する要求 URL の一部としてキーと値のペアを構成します。 その後、ターゲット エンドポイントは、要求 URL の API キーが許可されているかどうかを検証し、アクセス許可を付与するかどうかを決定できます。
AAD を選択すると、ターゲット エンドポイントへの HTTP 要求の承認ヘッダーにベアラー トークンが含まれます。 ベアラー トークンは、Azure AD によって発行される JSON Web トークン (JWT) です。 JWT の詳細については、「Microsoft ID プラットフォームアクセス トークン」を参照してください。 Fraud Protection は、次に示すように、要求承認ヘッダーの必要な形式でトークン値をテキスト "Bearer" に追加します。
ベアラー <トークン>
トークン要求
次の表に、Fraud Protection によって発行されるベアラー トークンで期待できる要求の一覧を示します。
| Name | 要求 | 説明 |
|---|---|---|
| テナント ID | tid | この要求は、Fraud Protection アカウントに関連付けられているサブスクリプションの Azure テナント ID を識別します。 Fraud Protection ポータルでテナント ID を検索する方法については、「必要な ID と情報」を参照してください。 Azure portal でテナント ID を検索する方法については、「Azure Active Directory テナント ID を検索する方法」を参照してください。 |
| 対象者 | aud | この要求は、トークンの目的の受信者を識別します。 この値は、Fraud Protection ポータルで外部呼び出しを構成したときに指定したアプリケーション ID を正確に反映します。 |
| アプリケーション ID | アプリID | この要求は、Fraud Protection のアプリケーション ID * bf04bdab-e06f-44f3-9821-d3af64fc93a9* です。 この ID は Fraud Protection によってのみ所有され、Microsoft のみがその代わりにトークンを要求できます。 |
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 application id>" || appid != "bf04bdab-e06f-44f3-9821-d3af64fc93a9")
{
throw new Exception("the token is not authorized.");
}
外部データプラクティス
お客様は、詐欺防止の外部呼び出し機能を通じて Microsoft に提供するデータ セットに関連するデータ保護法、契約上の制限、ポリシーを含め、適用されるすべての法律および規制を遵守する責任があることを確認します。 さらに、お客様は、不正防止の使用が、支払いトランザクションを続行するかどうかを決定する唯一の要因として Fraud Protection (i) を使用しないことを示す、Microsoft 顧客契約で詳しく説明されている制限を使用する対象となることを認めます。(ii) 個人の財務状態、財務履歴、信用力、または保険、住宅、雇用の資格を決定する要因として、(iii) 法的効果を生み出す、または人に重大な影響を与える意思決定を行う。 また、Fraud Protection の外部呼び出し機能の使用に関連して、機密性の高いデータ型または高度に規制されたデータ型を提供または使用することも禁止されています。 Fraud Protection の外部呼び出し機能で使用する前に、データ セットまたはデータ型を確認して、このプロビジョニングに準拠していることを確認してください。 Microsoft は、お客様がこのプロビジョニングに準拠していることを確認する権利も留保します。