Интеграция API защиты покупок

В этой статье объясняется, как интегрировать интерфейсы программирования приложений в режиме реального времени в Microsoft Dynamics 365 с защитой от мошенничества.

Чтобы воспользоваться полным набором функций защиты от мошенничества, необходимо отправить данные транзакции в API защиты от мошенничества в режиме реального времени. В ходе оценки отправка данных транзакции позволяет анализировать результаты использования защиты от мошенничества. В интерфейсе защиты вы также можете принимать решения в соответствии с настроенными правилами.

В зависимости от того, как вы используете защиту от мошенничества, можно использовать различные наборы следующих API защиты покупок:

• Покупка
• PurchaseStatus
• BankEvent
• Средства за использование
• Возврат денежных средств
• UpdateAccount
• Этикетка

Этапы интеграции API

Интеграция API защиты покупок выполняется на трех этапах:

1. Создание приложений Microsoft Entra с помощью защиты от мошенничества.
2. Создайте маркер доступа.
3. Вызов API.

Вход

Посетите следующие порталы для каждой среды, которую вы планируете использовать. Войдите и примите условия, если вам будет предложено сделать это.

• Среда песочницы
• Рабочая среда (возможно, вы уже выполнили этот шаг в рабочей среде во время первоначальной регистрации.)

Создание приложений Microsoft Entra

Чтобы получить маркеры, необходимые для вызова API, необходимо настроить и использовать приложения Microsoft Entra, как описано в этом разделе.

Настройка приложений Microsoft Entra

Чтобы настроить приложения Microsoft Entra, выполните следующие действия.

1. На портале защиты от мошенничества в области навигации слева выберите "Интеграция > создания приложений Microsoft Entra" > теперь.

2. Заполните страницу, чтобы создать приложение. Рекомендуется создать одно приложение Microsoft Entra для каждой среды, которую требуется интегрировать с защитой от мошенничества.

3. Введите или выберите значения для следующих обязательных полей:

   • Отображаемое имя приложения— присвойте приложению описательное имя. Максимальная длина — 93 символа.
   • Метод проверки подлинности— выберите, требуется ли пройти проверку подлинности с помощью сертификата или секрета (пароль).

4. Если выбран метод проверки подлинности сертификата, выполните следующие действия.

   1. Выберите "Выбрать файл ", чтобы отправить открытый ключ. (При получении маркеров требуется соответствующий закрытый ключ.)
   2. Выберите секрет , чтобы автоматически создать пароль после создания приложения.

5. После завершения настройки обязательных полей нажмите кнопку "Создать приложение". Страница подтверждения суммирует имя, идентификатор и отпечаток сертификата приложения в зависимости от выбранного метода проверки подлинности.

Создание другого приложения

Чтобы создать другое приложение, нажмите кнопку "Создать другое приложение". Вы можете создавать столько приложений, сколько требуется для выполнения вызовов API в каждой из сред.

Управление существующими приложениями Microsoft Entra

После создания приложений Microsoft Entra их можно управлять с помощью [портал Azure](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Дополнительные сведения см. в статье о том, как и почему приложения добавляются в идентификатор Microsoft Entra.

Создание маркера доступа

Чтобы безопасно интегрировать системы с Защитой от мошенничества, получите токен Microsoft Entra и предоставьте его в заголовке каждого вызова API.

Для получения маркера требуется следующая информация.

Обязательные идентификаторы и сведения

• Универсальный код ресурса (URI среды) — URI песочницы или рабочей среды отображаются на вкладке "Конфигурация" страницы Управление API на портале защиты от мошенничества.
• Идентификатор каталога (клиента) — это глобальный уникальный идентификатор (GUID) домена клиента в Azure. Он отображается на портал Azure и на вкладке "Конфигурация" страницы Управление API на портале защиты от мошенничества.
• Идентификатор приложения (клиента) — этот идентификатор определяет приложение Microsoft Entra, созданное для вызова API. Получите идентификатор на странице подтверждения API в режиме реального времени или найдите его позже в Регистрация приложений в портал Azure. Для каждого созданного приложения будет один идентификатор.
• Отпечаток или секрет сертификата— получение отпечатка или секрета на странице подтверждения API в режиме реального времени.
• Идентификатор экземпляра — это идентификатор GUID среды в службе защиты от мошенничества. Он отображается на плитке интеграции на панели мониторинга защиты от мошенничества.

Примеры кода, демонстрирующие получение маркера с помощью сертификата или секрета

В следующих примерах кода C# приведены примеры получения маркера с помощью сертификата или секрета. Замените заполнители определенными сведениями. Для обоих примеров C# необходимо импортировать пакет NuGet Microsoft.Identity.Client.

Примеры на других языках см. в разделе 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

• Заголовки:

  • Тип контента: application/x-www-form-urlencoded

• Текст (ключ-значение):

  • grant_type: client_credentials
  • client_id: {Идентификатор клиента из предыдущего шага}
  • client_secret: {Ваш секрет из предыдущего шага}
  • ресурс: https://api.dfp.microsoft.com (для int, https://api.dfp.microsoft-int.com)

• Ответ:

  • Используйте значение access_token ответа для следующего шага.

Дополнительные сведения см. в следующей документации по Azure:

• Общие сведения о библиотеке проверки подлинности Майкрософт (MSAL)
• Получение и кэширование маркеров с помощью библиотеки проверки подлинности Майкрософт (MSAL)

Вызов API

Чтобы вызвать API, выполните следующие действия.

1. Передайте следующие необходимые заголовки HTTP для каждого запроса.

   Имя заголовка	Значение заголовка
   Авторизация	Используйте следующий формат для этого заголовка. (Замените accesstoken фактическим значением маркера, возвращаемым идентификатором Microsoft Entra.) Доступ носителя
   x-ms-correlation-id	Отправьте новое значение GUID для каждого набора вызовов API, выполненных вместе.
   x-ms-dfpenvid	Отправьте значение GUID идентификатора экземпляра.

2. Создайте полезные данные на основе событий. Заполните данные события соответствующими сведениями из системы. Документация по всем поддерживаемым событиям см. в разделе API Защиты от мошенничества Dynamics 365.

3. Объедините заголовок (который включает маркер доступа) и полезные данные, а затем отправьте их в конечную точку Защиты от мошенничества.

   • Запрос POST на:

     • <Base URL>/v1.0/merchantservices/events/purchase

   • Заголовки:

     • x-ms-correlation-id: {A GUID, который должен быть уникальным для каждого запроса}
     • content-type: application/json
     • Авторизация: {Токен из предыдущего шага}
     • x-ms-dfpenvid: {Идентификатор среды целевой среды}

   • Текст:

     • Получите пример текста запроса на защиту учетных записей с общей страницы Swagger.

Следующие параметры допустимы для x-ms-dfpenvid в вызове API и поведение идентично.

• Используйте идентификатор среды для вызываемой среды. Идентификатор указан на странице интеграции в поле "Идентификатор среды".
• Используйте полный патт идентификатора API клиента из корня в дочернюю среду, которую вы вызываете с помощью косой черты (/) в качестве разделителя. Например, /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, такие как отправка обновлений учетной записи клиента, возврат средств и возвратных платежей в режиме реального времени. Документация для примера приложения связана с фактическим примером кода всякий раз, когда такие ссылки возможны. В противном случае примеры кода существуют непосредственно в документации.

Инструкции по настройке примера сайта для использования см. в разделе "Настройка примера сайта".