外部呼叫

發行項
12/11/2024

外部呼叫可讓您從 Microsoft Dynamics 365 Fraud Protection 外部的 API 內嵌數據，然後使用該數據即時做出明智的決策。例如，第三方位址和電話驗證服務，或您自己的自定義評分模型，可能會提供重要輸入，以協助判斷某些事件的風險等級。藉由使用外部呼叫，您可以連線到任何 API 端點、視需要在規則內向該端點提出要求，並使用該端點的回應來做出決策。

注意

如果所有事件都需要此額外數據，您也可以將其傳送為評量架構的一部分。如需如何在 API 要求中傳送自定義數據的詳細資訊，請參閱自定義數據範例。

可用於外部呼叫的 API 類型

建立外部呼叫之前，您應該先瞭解下列限制：

詐騙保護目前僅支援下列驗證方法：匿名和 AAD。
詐騙保護目前僅支援下列 HTTP 方法： GET 和 POST。

建立外部呼叫

在 [詐騙保護] 入口網站的左側導覽中，選取 [外部通話]，然後選取 [ 新增外部通話]。
視需要檢閱並設定下列欄位。
- 名稱 – 輸入您將用來從規則參考外部呼叫的名稱。名稱只能包含數位、字母和底線。它不能以數字開頭。
  
  注意
  
  在規則中使用外部呼叫之後，您無法變更其名稱。
- 描述 – 新增描述，以協助小組快速識別外部通話。
- Web 要求 – 選取適當的 HTTP 方法（GET 或 POST），然後輸入 API 端點。
  
  注意
  
  僅支援 HTTPS 端點。
- 啟用定期熱身呼叫 - 如果連往外部呼叫端點的流量太低，連線可能會變冷，而且可能會增加來自外部服務的響應延遲。若要減輕此問題，請從 [外部通話設定 ] 頁面啟用熱身通話。使用切換來啟用熱身呼叫。您必須提供有效的 GET Keep-alive URL。如同主要端點，Keep-alive 端點也必須通過 測試連線。如果您使用已啟用熱身呼叫來設定外部呼叫，當您的流量下降太低時，詐騙保護會自動使用 GET 方法對保持運作端點進行匿名熱身呼叫。
  
  注意
  
  熱身呼叫中不能使用任何參數、組態或可設定的標頭。
- 驗證 – 選取應該用來驗證傳入要求的方法。
  - 如果您選取 [ 匿名]，則不會傳送授權標頭。
  - 如果您選取 AAD，就會在租用戶中產生 Azure Active Directory （Azure AD）令牌，而 持有人 <令牌> 會當做授權標頭使用。
  如需驗證、授權和 Azure AD 令牌的詳細資訊，請參閱本文稍後的瞭解驗證和授權一節。
- 物件 - 如果您選取 AAD 作為驗證方法，系統會要求您提供物件。您可以使用現有的 Azure 應用程式作為物件，或透過詐騙保護入口網站內的整合體驗建立新的應用程式。請確定物件具有存取外部呼叫/服務的許可權。若要深入瞭解如何設定 Azure Active Directory （Azure AD）驗證，請參閱設定 Azure AD 驗證。
- 應用程式識別碼 – 您也必須在詐騙保護訂用帳戶租使用者內提供新或現有 Azure AD 應用程式的應用程式識別碼。在 Azure 金鑰保存庫中產生憑證。詐騙保護應用程式應該具有此 Azure 金鑰保存庫的讀取許可權。將憑證載入此 Azure AD 應用程式。如需如何建立和管理 Azure AD 應用程式的詳細資訊，請參閱建立 Azure Active Directory 應用程式。
- 憑證 URL – 從 Azure 金鑰保存庫提供憑證標識碼 URL。這是您在上一個步驟中載入至 Azure AD 應用程式的相同憑證。如需如何在 Azure 金鑰保存庫中產生憑證的詳細資訊，請參閱在 Azure 中建立和合併憑證簽署要求金鑰保存庫
- 新增參數 – 您可以使用參數，將數據從 Fraud Protection 傳遞至 API 端點。根據您選取的 HTTP 方法，這些參數會傳送至查詢字串中的端點，或作為要求主體的一部分。
  
  您可以為每個參數新增範例值。詐騙保護會使用這些參數值，在建立之前或每當您選取 [測試] 時，對端點進行範例呼叫。
  
  注意
  
  所有參數值都會解譯為字串。
- 範例要求 – 提供傳送至外部呼叫的要求範例。要求應該反映您指定的參數名稱和值，而且無法編輯。
  
  針對 GET 方法，會顯示要求 URL。針對 POST 方法，會顯示要求本文。
  
  範例要求可用來在建立之前或每當您選取 [測試] 時，對端點進行範例呼叫。
- 範例回應 – 提供從 API 端點成功回應中傳回的數據範例。此數據應為 JavaScript 物件表示法（JSON）格式，而且可在您的規則中參考。您在此處提供的範例會顯示為您建立規則。
  
  選取 [ 測試 ] 以在此欄位中自動輸入 API 的實際回應。
- 請求超時 – 指定請求等待超時的時間長度，單位為毫秒。您必須指定介於 1 到 5000 之間的數字。
- 默認回應 – 指定如果您的要求失敗或超過指定的逾時，應該傳回的默認回應。此值必須是有效的 JSON 物件或 JSON 元素。
選擇性：若要將範例要求傳送至 API 端點並檢視回應，請選取 [ 測試]。如需詳細資訊，請參閱下一節測試外部呼叫。
當您完成必要的欄位設定時，請選取 [ 建立]。

測試外部呼叫

若要確保詐騙保護可以連線到您的端點，請隨時測試連線。

若要在建立新的外部呼叫或編輯現有的外部呼叫時測試連線，請設定所有必要的欄位，然後選取 [ 測試]。

詐騙保護會使用您提供的端點和參數，將要求傳送至外部呼叫。
- 如果詐騙保護成功到達目標端點，面板頂端會出現綠色消息列，通知您連線成功。若要檢視完整的回應，請選取 [ 查看回應詳細數據]。
- 如果詐騙保護無法到達目標端點，或未在指定的逾時之前收到回應，則面板頂端會出現紅色消息列，並顯示所遇到的錯誤。若要檢視錯誤的詳細資訊，請選取 [查看錯誤詳細數據]。

監視外部呼叫

在詐騙保護入口網站中監視外部呼叫

詐騙保護會顯示圖格，其中包含您定義之每個外部呼叫的三個計量：

每秒要求數 – 要求總數除以所選時間範圍內的總分鐘數。
平均延遲 – 要求延遲總數除以所選時間範圍內的總分鐘數。
成功率 – 成功的要求總數除以提出的要求總數。

此圖格上顯示的數字和圖表只包含您在頁面右上角下拉式清單中選取的時間範圍數據。

注意

只有在使用中的規則中使用外部呼叫時，才會顯示計量。

若要深入瞭解外部呼叫的相關數據，請選取 磚右上角的 [效能 ]。

詐騙保護會顯示新頁面，其中包含更詳細的計量檢視。
若要檢視過去三個月中任何時間範圍的計量，請調整 頁面頂端的 [日期範圍 ] 設定。

除了稍早所述的三個 計量之外，也會顯示錯誤 圖表。此圖表依錯誤類型和程式代碼顯示錯誤數目。若要檢視一段時間的錯誤計數，或檢視錯誤的分佈，請選取餅圖。

除了 HTTP 用戶端錯誤（400、401 和 403），您可能會看到下列錯誤：

無效的應用程式識別碼 – 所提供的應用程式標識碼不存在於您的租使用者中，或無效。
AAD 失敗 – 無法擷取 Azure AD 令牌。
找不到 定義 – 已刪除外部呼叫，但仍會在規則中參考。
逾時 – 對目標的要求花費的時間超過指定的逾時時間。
通訊失敗 – 因為網路問題或目標無法使用，無法連線到目標。
斷路器 – 如果外部呼叫連續失敗，且已超過特定閾值，則所有進一步的呼叫都會暫停短暫的間隔。
未知失敗 – 發生內部 Dynamics 365 失敗。

使用事件追蹤來監視外部呼叫

您可以使用 Fraud Protection 的事件追蹤功能，將與您外部呼叫相關的事件轉送至您自己的 Azure 事件中樞或 Azure Blob 儲存體實例。在 [詐騙保護] 入口網站的 [事件追蹤 ] 頁面上，您可以訂閱下列兩個與外部呼叫相關的事件：

FraudProtection.Monitoring.ExternalCalls
FraudProtection.Errors.ExternalCalls

每當對外部呼叫提出要求時，就會將事件傳送至 FraudProtection.Monitoring.ExternalCalls 命名空間。事件承載包含呼叫延遲、要求狀態，以及觸發要求的規則和子句的相關信息。

當外部呼叫失敗時，事件會傳送至 FraudProtection.Errors.ExternalCalls 命名空間。事件承載包含傳送至外部呼叫的 URI 要求和本文，以及已接收的回應。

如需事件追蹤、如何訂閱事件，以及您可以如何處理事件的詳細資訊，請參閱事件追蹤。

如需如何將此數據與您自己的組織工作流程整合，以及設定自定義監視、警示和報告的相關信息，請參閱透過事件中樞的擴充性。

管理外部呼叫

若要編輯現有的外部呼叫，請選取卡片標頭上的 [ 編輯 ]。

注意

在規則中使用外部呼叫之後，您無法變更外部呼叫的名稱和參數。
若要刪除現有的外部呼叫，請選取省略號（...），然後選取 [ 刪除]。

注意

在規則中參考外部呼叫之後，您無法刪除它。
若要檢視外部呼叫的詳細效能計量，請選取 [ 效能]。
若要測試詐騙保護仍然可以連線到您的外部呼叫，請選取省略號（...），然後選取 [ 測試連線]。

在規則中使用外部呼叫

若要使用外部呼叫來做出決策，請從規則中參考它們。

例如，若要參考規則中名為 myCall 的外部呼叫，請使用下列語法：

External.myCall（）

如果 myCall 需要參數，例如 IPaddress，請使用下列語法：

External.myCall（@“device.ipAddress”）

如需規則語言以及如何在規則中使用外部呼叫的資訊，請參閱語言參考指南。

注意

如果在規則中使用外部呼叫，規則的延遲可能會增加。

瞭解驗證和授權

為了確保能夠安全地存取數據，API 通常會驗證要求的傳送者，以確認他們有權存取數據。詐騙保護中的外部呼叫支援兩種驗證方法：匿名和 AAD。

如果您選取 [ 匿名]，則目標端點的 HTTP 要求中的授權標頭會保留空白。當目標端點不需要授權標頭時，請使用此選項。例如，如果您的端點使用 API 金鑰，請將金鑰/值組設定為您在 [Web 要求 ] 欄位中輸入的要求 URL 的一部分。然後，目標端點可以驗證是否允許來自要求URL的API金鑰，然後決定是否應授與許可權。

如果您選取 AAD，則目標端點 HTTP 要求中的授權標頭會包含持有人令牌。持有人令牌是 Azure AD 所發行的 JSON Web 令牌（JWT）。如需 JWT 的相關信息，請參閱 Microsoft 身分識別平台存取令牌。 Fraud Protection 會將令牌值附加至要求授權標頭中所需格式的文字 “Bearer”，如下所示：

<持有人令牌>

令牌宣告

下表列出您可以在詐騙保護所簽發的持有人令牌中預期的宣告。

名稱	索賠	描述
租用戶識別碼	tid	此宣告會識別與您的詐騙保護帳戶相關聯的訂用帳戶 Azure 租使用者標識碼。如需如何在詐騙保護入口網站中尋找租使用者標識符的資訊，請參閱必要的標識碼和資訊。如需如何在 Azure 入口網站中尋找租使用者標識符的資訊，請參閱如何尋找您的 Azure Active Directory 租使用者識別碼。
對象	aud	此宣告會識別令牌的預定收件者。此值完全符合您在詐騙保護入口網站中設定外部呼叫時所提供的應用程式識別碼。
應用程式識別碼	appid	此宣告是 Fraud Protection 的應用程式識別碼：* bf04bdab-e06f-44f3-9821-d3af64fc93a9*。此標識碼只由詐騙保護所擁有，且只有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數據集相關的數據保護法、合約限制和/或原則。此外，您承認使用詐騙保護受限於 Microsoft 客戶合約中詳述的限制，其中指出您不得使用詐騙保護（i）作為決定是否繼續進行付款交易的唯一因素：（二）作為確定任何人財務狀況、財務記錄、信用或保險資格、住房或就業資格的一個因素：或者（三）作出產生法律影響或嚴重影響某人的決定。您也禁止提供或使用敏感性或高管制數據類型，以使用詐騙保護的外部呼叫功能。請花點時間檢閱任何數據集或數據類型，再將其與詐騙保護的外部呼叫功能搭配使用，以確保您符合這項布建規範。 Microsoft也會保留確認您符合此布建規範的權利。

共用方式為