這很重要
自 2025 年 2 月 3 日起，Dynamics 365 詐騙保護已不再可供購買。 對詐騙保護的支援將於 2026 年 2 月 3 日結束。 如需詳細資訊，請參閱 Dynamics 365 Fraud Protection 終止支援一文。
本文說明如何在 Microsoft Dynamics 365 Fraud Protection 中整合即時應用程式開發介面 (API)。
若要利用完整的詐騙保護功能，您必須將事務數據傳送至實時詐騙保護 API。 在評估過程中，傳送您的交易數據可以讓您分析使用詐騙保護的效果。 在保護過程中，您也可以根據您已設定的規則來遵守決策。
根據您使用詐騙保護的方式，您可以使用下列購買保護 API 的不同集合：
- 購買
- 購買狀態
- 銀行活動
- 退款
- 退款
- 更新帳號
- 標籤
API 整合階段
購買保護 API 的整合會在三個階段進行：
- 使用詐騙防護功能建立 Microsoft Entra 應用程式。
- 產生存取令牌。
- 呼叫 API。
登錄
這很重要
您必須是 Azure 租使用者中的全域管理員，才能完成初始登入。
請流覽下列入口網站，以取得您想要使用的每個環境。 如果系統提示您登入，請接受條款及條件。
建立Microsoft Entra 應用程式
這很重要
您必須是 Azure 租使用者中的應用程式管理員、雲端應用程式管理員或全域管理員，才能完成此步驟。
若要取得呼叫 API 所需的令牌，您必須設定並使用 Microsoft Entra 應用程式，如本節所述。
設定 Microsoft Entra 應用程式
若要設定Microsoft Entra 應用程式，請遵循下列步驟。
在 [詐騙保護] 入口網站的左側瀏覽窗格中，選取 [ 整合 > 建立Microsoft Entra Application > Setup now]。
完成頁面以建立您的應用程式。 建議您為每個想要與詐騙保護整合的環境建立一個Microsoft Entra 應用程式。
輸入或選取下列必要欄位的值：
- 應用程式顯示名稱 – 為應用程式提供描述性名稱。 最大長度為93個字元。
- 驗證方法 – 選取您是否要透過憑證或密碼進行驗證（密碼）。
如果您選取憑證驗證方法，請遵循下列步驟：
- 選取 [選擇檔案 ] 以上傳公鑰。 （當您取得令牌時，需要相符的私鑰。
- 選取 [ 秘密 ] 以在建立應用程式之後自動產生密碼。
當您完成設定所需的欄位時，請選取 [建立應用程式]。 確認頁面會根據您選取的驗證方法，摘要說明應用程式的名稱、標識碼和憑證指紋或密碼。
這很重要
儲存您的秘密或憑證指紋資訊，以供日後參考。 密碼只會顯示一次。
建立另一個應用程式
若要建立另一個應用程式，請選取 [建立另一個應用程式]。 您可以視需要在每個環境中執行 API 呼叫，建立盡可能多的應用程式。
管理現有的Microsoft Entra 應用程式
建立Microsoft Entra 應用程式之後，您可以透過 [Azure 入口網站]（https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps 來管理它們）。 如需詳細資訊，請參閱將應用程式新增至 Microsoft Entra ID 的方式和原因。
生成存取權限憑證
若要安全地整合您的系統與詐騙保護，請取得Microsoft Entra 令牌，並在每個 API 呼叫的標頭中提供它。
備註
存取令牌的壽命限製為60分鐘。 建議您快取並重複使用令牌，直到令牌即將到期為止。 然後，您可以取得新的存取令牌。
需要下列資訊才能取得令牌。
必要標識碼和資訊
- 環境 URI - 您的沙箱或生產環境的 URI 會出現在詐騙保護入口網站的 API 管理頁面的配置標籤中。
- 目錄（租使用者）標識碼 – 此標識符是 Azure 中租使用者網域的全域唯一標識碼（GUID）。 它會出現在 Azure 入口中，並且在 [防詐騙] 入口的 [API 管理] 頁面的 [組態] 索引標籤上。
- 應用程式 （用戶端） 識別碼 – 此識別符會識別您已建立以呼叫 API 的Microsoft Entra 應用程式。 從 [即時 API 確認] 頁面取得標識符，或稍後在 Azure 入口網站中的 [應用程式註冊 ] 下找到標識符。 您建立的每個應用程式都會有一個識別碼。
- 憑證指紋或秘密 – 從即時 API 確認頁面取得指紋或秘密。
- 實例識別碼 – 此 ID 是您在詐騙保護中環境的 GUID。 它會出現在 [詐騙保護] 儀錶板的 [整合 ] 圖格中。
範例：示範如何使用憑證或秘密取得令牌的程式代碼範例
下列 C# 程式代碼範例提供使用您的憑證或秘密取得令牌的範例。 以您的特定資訊取代佔位符。 針對這兩個 C# 範例，您必須匯入 Microsoft.Identity.Client NuGet 套件。
如需其他語言的範例，請參閱 https://aka.ms/aaddev。
使用應用程式識別碼和私鑰取得存取令牌
/// <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;
}
}
使用應用程式識別碼和秘密取得存取令牌
/// <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
標頭：
- Content-type：application/x-www-form-urlencoded
主體（索引鍵/值）：
- grant_type：client_credentials
- client_id： {上一個步驟中的用戶端標識符}
- client_secret： {上一個步驟中的秘密}
- 資源：
https://api.dfp.microsoft.com（適用於整數，https://api.dfp.microsoft-int.com）
回應：
- 針對下一個步驟，請使用回應 中的 access_token 值。
如需詳細資訊，請參閱下列 Azure 檔：
呼叫 API
若要呼叫 API，請遵循下列步驟。
在每個要求上傳遞下列必要的 HTTP 標頭。
標頭名稱 標頭值 授權 針對此標頭，請使用下列格式。 （將 accesstoken 替換為由 Microsoft Entra ID 返回的真實令牌值。）
Bearer accesstoken
x-ms-correlation-id 在每個一組一起進行的 API 呼叫上傳送新的 GUID 值。 x-ms-dfpenvid 傳送實例標識碼的 GUID 值。 產生事件型承載。 以系統的相關信息填入事件數據。 如需所有支援事件的檔案，請參閱 Dynamics 365 Fraud Protection API。
結合標頭（包括存取令牌）和承載，然後將它們傳送至您的詐騙保護端點。
POST 請求至：
<Base URL>/v1.0/merchantservices/events/purchase
標頭：
- x-ms-correlation-id: {唯一識別碼，每個要求都必須唯一}
- content-type：application/json
- 授權： {上一個步驟中的令牌}
- x-ms-dfpenvid： {目標環境的環境標識符}
身體：
- 從共用 Swagger 頁面取得範例帳戶保護請求主體。
備註
如果您建立新的環境，請在整合期間在 API 標頭中包含環境識別碼，以便正確地路由傳送交易。
在 API 呼叫中，x-ms-dfpenvid 可以接受下列選項，而且行為完全相同。
- 針對您要呼叫的環境使用環境標識碼。 ID 列在 整合 頁面的 環境 ID 欄位中。
- 請使用 客戶 API ID 的完整路徑，從根目錄到子環境，並以正斜線（/）作為分隔符。 例如， /primary/XYZ。
- 使用環境識別碼或客戶 API 識別碼的完整路徑，從根環境到您要呼叫的子環境，並使用正斜線（/）作為分隔符。 例如 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ。
若要在建立環境時指定客戶 API 識別碼，請參閱 管理環境一文。
最佳做法
- 每個Microsoft Entra 令牌仍有效 60 分鐘。 建議您在較短的期間內快取它，並重複使用它。
- 請確定您的 HttpClient 具有保持活躍的連線。
- 一律傳遞 x-ms-dfpenvid 標頭，並確定其指向您想要代表傳送交易的商家環境。
- 將秘密儲存在秘密存放區中。
- 務必傳遞 x-ms-correlation-id 標頭，以便未來使用詐騙保護進行偵錯會話。
- 請確定 x-ms-correlation-id 標頭對於傳送至詐騙保護的每個交易而言都是唯一的。
檢視範例應用程式
如需其他參考，您可以檢視 範例商家應用程式和 隨附的開發人員檔。 範例應用程式提供如何呼叫詐騙保護 API 的範例，包括即時傳送客戶帳戶更新、退款和退款等 API 事件。 只要有這類連結，範例應用程式的檔就會連結到實際的範例程序代碼。 否則，程式代碼範例會直接存在於檔中。
如需如何設定範例月臺以供您使用的指引，請參閱 設定範例月臺。