整合購買保護 API
本文說明如何在 Microsoft Dynamics 365 Fraud Protection 中整合即時應用程式開發介面（API）。
若要利用完整的詐騙保護功能，您必須將事務數據傳送至實時詐騙保護 API。 在評估體驗中，傳送您的事務數據可讓您分析使用詐騙保護的結果。 在保護體驗中，您也可以根據您已設定的規則來接受決策。
根據您使用詐騙保護的方式，您可以使用下列購買保護 API 的不同集合：
- 購買
- PurchaseStatus
- BankEvent
- 退款
- 退款
- UpdateAccount
- 標籤
API 整合階段
購買保護 API 的整合會在三個階段進行：
登入
重要
您必須是 Azure 租使用者中的全域管理員，才能完成初始登入。
請流覽下列入口網站，以取得您想要使用的每個環境。 如果系統提示您登入，請接受條款及條件。
建立 Microsoft Entra 應用程式
重要
您必須是 Azure 租使用者中的應用程式管理員、雲端應用程式管理員或全域管理員，才能完成此步驟。
若要取得呼叫 API 所需的令牌，您必須設定及使用 Microsoft Entra 應用程式，如本節所述。
設定 Microsoft Entra 應用程式
若要設定 Microsoft Entra 應用程式，請遵循下列步驟。
在 [詐騙保護] 入口網站的左側瀏覽窗格中，選取 [立即整合>建立 Microsoft Entra 應用程式>設定]。
完成頁面以建立您的應用程式。 建議您為每個想要與詐騙保護整合的環境建立一個 Microsoft Entra 應用程式。
輸入或選取下列必要欄位的值：
- 應用程式顯示名稱 – 為應用程式提供描述性名稱。 最大長度為93個字元。
- 驗證方法 – 選取您是否要透過憑證或密碼進行驗證（密碼）。
如果您選取憑證驗證方法，請遵循下列步驟：
- 選取 [ 選擇檔案 ] 以上傳公鑰。 （當您取得令牌時，需要相符的私鑰。
- 選取 [ 秘密 ] 以在建立應用程式之後自動產生密碼。
當您完成設定所需的欄位時，請選取 [ 建立應用程式]。 確認頁面會根據您選取的驗證方法，摘要說明應用程式的名稱、標識碼和憑證指紋或密碼。
重要
儲存您的秘密或憑證指紋資訊，以供日後參考。 密碼只會顯示一次。
建立另一個應用程式
若要建立另一個應用程式，請選取 [建立另一個應用程式]。 您可以視需要在每個環境中執行 API 呼叫，建立盡可能多的應用程式。
管理現有的 Microsoft Entra 應用程式
建立 Microsoft Entra 應用程式之後，您可以透過 [Azure 入口網站]（https://portal.azure.com/#blade/Microsoft_MicrosoftEntra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps 來管理它們）。 如需詳細資訊，請參閱 如何將應用程式新增至 Microsoft Entra ID 和原因。
產生存取權杖
若要安全地整合您的系統與詐騙保護，請取得 Microsoft Entra 令牌，並在每個 API 呼叫的標頭中提供它。
注意
存取令牌的壽命限製為60分鐘。 建議您快取並重複使用令牌，直到令牌即將到期為止。 然後，您可以取得新的存取令牌。
需要下列資訊才能取得令牌。
必要標識碼和資訊
- 環境 URI – 沙箱或生產環境的 URI 會出現在詐騙保護入口網站中 [API 管理] 頁面的 [設定] 索引標籤上。
- 目錄（租使用者）標識碼 – 此標識符是 Azure 中租使用者網域的全域唯一標識碼（GUID）。 它會出現在 [Azure 入口網站] 和 [詐騙保護] 入口網站中 [API 管理] 頁面的 [組態] 索引卷標上。
- 應用程式 （用戶端） 識別碼 – 此識別符會識別您已建立以呼叫 API 的 Microsoft Entra 應用程式。 從 [即時 API 確認] 頁面取得標識符，或稍後在 [Azure 入口網站] 底 應用程式註冊 下找到標識符。 您建立的每個應用程式都會有一個識別碼。
- 憑證指紋或秘密 – 從即時 API 確認頁面取得指紋或秘密。
- 實例識別碼 – 此標識符是詐騙保護中您環境的 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： {上一個步驟中的秘密}
- resource：
https://api.dfp.microsoft.com（for int，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： {A GUID，每個要求都必須是唯一的}
- content-type: application/json
- 授權： {上一個步驟中的令牌}
- x-ms-dfpenvid： {目標環境的環境標識符}
本文：
注意
如果您建立新的環境，請在整合期間在 API 標頭中包含環境識別碼，以便正確地路由傳送交易。
在 API 呼叫中，x-ms-dfpenvid 可以接受下列選項，而且行為完全相同。
- 針對您要呼叫的環境使用環境標識碼。 標識子會列在 [環境標識符] 字段中的 [整合] 頁面上。
- 使用客戶 API 識別碼的完整 pat，從根目錄到您使用正斜線 （/） 作為分隔符呼叫的子環境。 例如， /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 事件。 只要有這類連結，範例應用程式的檔就會連結到實際的範例程序代碼。 否則，程式代碼範例會直接存在於檔中。
如需如何設定範例月臺以供您使用的指引，請參閱 設定範例月臺。