Share via

整合帳戶保護 API

  • 文章

若要利用 Microsoft Dynamics 365 Fraud Protection 中的完整功能套件，請將您的事務數據傳送至即時應用程式開發介面（API）。 在評估體驗中，您可以接著分析使用詐騙保護的結果。 在保護體驗中，您也可以接受以您所設定規則為基礎的決策。

根據您選擇使用詐騙保護的方式，您可以使用不同的 帳戶保護 API。 例如，AccountCreation、AccountLogin、AccountCreationStatus、AccountLoginStatus、AccountUpdate 和 Label。

如需所有支援事件的相關信息，請參閱 Dynamics 365 Fraud Protection API。

設定

登入

重要

若要完成初始 API 上線，您必須是 Microsoft Azure 租使用者中的全域 管理員 istrator。

若要登入 Fraud Protection：

  • 如果系統提示您接受條款及條件，請移至 詐騙保護入口網站、登入並接受條款及條件。

    此步驟可確保在 Azure 租用戶中正確設定詐騙保護。 （您可能已在初始註冊期間完成此步驟。

建立 Microsoft Entra 應用程式

重要

若要完成此步驟，您必須是應用程式 管理員 istrator、雲端應用程式 管理員 istrator，或 Azure 租使用者中的全域 管理員 istrator。

若要取得呼叫 API 所需的令牌，您必須使用 Microsoft Entra 應用程式。 您可以使用詐騙保護中的 [即時 API] 頁面來設定這些應用程式。

若要設定 Microsoft Entra 應用程式：

  1. 在左側瀏覽窗格中，選取 [ 組態]，然後選取 [ 即時 API]。

  2. 填寫欄位以建立您的應用程式。 需要下列欄位：

    • 應用程式顯示名稱 – 輸入應用程式的描述性名稱。 最大長度為93個字元。
    • 環境 – 選取生產端點。
    • 驗證方法 – 選取憑證或密碼（密碼）是否用於驗證。 如果您選取 [ 憑證]，請選取 [ 選擇檔案 ] 以上傳公鑰。 當您取得令牌時，您將需要相符的私鑰。 如果您選取 [ 秘密]，則會在建立應用程式之後為您產生密碼。

  3. 當您完成填入欄位時，請選取 [ 建立應用程式]。

    確認頁面會根據您選取的驗證方法，摘要說明應用程式的名稱和標識碼，以及憑證指紋或密碼。

重要

儲存憑證指紋或秘密的相關信息，以供日後參考。 秘密只會顯示一次。

您可以視需要在生產環境中執行 API 呼叫，建立盡可能多的應用程式。

若要建立另一個應用程式：

  1. 選取 [ 建立另一個應用程式]。
  2. 填寫欄位以建立您的應用程式，然後選取 [ 建立應用程式]。

管理現有的 Microsoft Entra 應用程式

建立 Microsoft Entra 應用程式之後，您可以透過 [Azure 入口網站]（https://portal.azure.com/#blade/Microsoft_MicrosoftEntra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps 來管理它們）。 如需詳細資訊，請參閱 Azure 文件網站。

呼叫詐騙保護即時 API

使用本節中的資訊，將系統與詐騙保護整合。

必要標識碼和資訊

  • API 端點 – 您環境的 URI 會出現在 詐騙保護儀錶板上的 [帳戶資訊 ] 圖格上。
  • 目錄（租使用者）標識碼 – 目錄標識符是 Azure 中租使用者網域的全域唯一標識碼 （GUID）。 它會出現在 [Azure 入口網站] 和 [詐騙保護] 儀錶板的 [帳戶資訊] 圖格上。
  • 應用程式 （用戶端） 識別碼 – 應用程式識別符會識別您建立以呼叫 API 的 Microsoft Entra 應用程式。 您可以在 [即時 API] 頁面上選取 [建立應用程式] 之後出現的確認頁面上找到此識別碼。 您也可以稍後在 Azure 入口網站 的 [應用程式註冊] 底下找到它。 您建立的每個應用程式都會有一個識別碼。
  • 憑證指紋或秘密 – 您可以在 [即時 API] 頁面上選取 [建立應用程式] 之後，於確認頁面上找到憑證指紋或密碼。
  • 實例識別碼 - 實例標識符是詐騙保護中您環境的全域唯一標識碼 （GUID）。 它會出現在 [詐騙保護] 儀錶板的 [整合 ] 圖格中。

產生存取權杖

您必須產生此令牌，並提供每個 API 呼叫。 請注意，存取令牌的壽命有限。 建議您快取並重複使用每個存取令牌，直到取得新的存取令牌為止。

下列 C# 程式代碼範例提供範例，示範如何使用您的憑證或秘密來取得令牌。 使用您自己的資訊取代佔位元。

憑證指紋

public async Task<string> AcquireTokenWithCertificateAsync()
{
    var x509Cert = CertificateUtility.GetByThumbprint("<Certificate thumbprint>");
    var clientAssertion = new ClientAssertionCertificate("<Client ID>", x509Cert);
    var context = new AuthenticationContext("<Authority URL. Typically https://login.microsoftonline.com/[Directory_ID]>");
    var authenticationResult = await context.AcquireTokenAsync("<API endpoint>", clientAssertion);

    return authenticationResult.AccessToken;
}

祕密

public async Task<string> AcquireTokenWithSecretAsync()
{
    var clientAssertion = new ClientCredential("<Client ID>", "<Client secret>");
    var context = new AuthenticationContext("<Authority URL. Typically https://login.microsoftonline.com/[Directory_ID]>");
    var authenticationResult = await context.AcquireTokenAsync("<API endpoint>", clientAssertion);

    return authenticationResult.AccessToken;
}

回應

在幕後，上述程式代碼會產生 HTTP 要求，並接收類似下列範例的回應。

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: <date>
Content-Length: <content length>

{
    "token_type":"Bearer",
    "expires_in":"3599",
    "ext_expires_in":"3599",
    "expires_on":"<date timestamp>",
    "not_before":"<date timestamp>",
    "resource":"https://api.dfp.dynamics.com",
    "access_token":"<your access token; e.g.: eyJ0eXA...NFLCQ>"
}

如需詳細資訊，請參閱 Azure 檔：

呼叫 API

若要呼叫 API，請遵循下列步驟。

  1. 在每個要求上傳遞下列必要的 HTTP 標頭。

    標頭名稱 標頭值
    授權 針對此標頭使用下列格式：Bearer accesstoken，其中 accesstoken 是 Microsoft Entra ID 所傳回的令牌。
    x-ms-correlation-id 在每個一組一起進行的 API 呼叫上傳送新的 GUID 值。
    x-ms-dfpenvid 傳送實例標識碼的 GUID 值。

  2. 產生事件型承載。 以系統的相關信息填入事件數據。 如需所有支援事件的相關信息，請參閱 Dynamics 365 Fraud Protection API。

  3. 結合標頭（包括存取令牌）和承載，然後將它們傳送至您的詐騙保護端點。

注意

如果您建立新的環境，請在整合期間在 API 標頭中包含環境識別碼，以便正確地路由傳送交易。

檢視範例應用程式

如需其他參考，請檢視 範例商家應用程式 ，並查看隨附的開發人員檔。 範例應用程式提供範例，示範如何即時呼叫 Fraud Protection API。 每當有連結時，範例應用程式的檔會連結至實際的範例程序代碼。 否則，程式代碼範例會直接包含在檔中。

如需如何設定範例月臺以便使用它的詳細資訊，請參閱 設定範例月臺。