Внешние вызовы

Внешние вызовы позволяют принимать данные из API за пределами Microsoft Dynamics 365 Fraud Protection, а затем использовать эти данные для принятия обоснованных решений в режиме реального времени. Например, сторонние службы проверки адресов и телефонов или собственные пользовательские модели оценки могут предоставлять критически важные входные данные, которые помогают определить уровень риска для некоторых событий. Используя внешние вызовы, вы можете подключиться к любой конечной точке API, отправить запрос к этой конечной точке из правила в соответствии с требованиями и использовать ответ от этой конечной точки для принятия решения.

Типы API, которые можно использовать во внешнем вызове

Перед созданием внешнего вызова необходимо знать о следующих ограничениях:

• Защита от мошенничества в настоящее время поддерживает только следующие методы проверки подлинности: Анонимные и AAD.
• Защита от мошенничества в настоящее время поддерживает только следующие методы HTTP: GET и POST.

Создание внешнего вызова

1. На портале защиты от мошенничества в области навигации слева выберите внешние вызовы и нажмите кнопку "Создать внешний звонок".

2. Проверьте и задайте следующие поля по мере необходимости.

   • Имя — введите имя, которое будет использоваться для ссылки на внешний вызов из правил. Имя может содержать только цифры, буквы и подчеркивания. Он не может начинаться с числа.

     Примечание.

     Вы не можете изменить имя внешнего вызова после его использования в правиле.

   • Описание . Добавьте описание, чтобы помочь вашей команде быстро определить внешний вызов.

   • Веб-запрос — выберите соответствующий метод HTTP (GET или POST), а затем введите конечную точку API.

     Примечание.

     Поддерживаются только конечные точки HTTPS.

   • Включите периодические вызовы прогреения. Если трафик к конечной точке внешнего вызова слишком низкий, подключение может быть холодным и может увеличить задержку ответа от внешней службы. Чтобы устранить эту проблему, включите вызовы на странице настройки внешнего вызова. Используйте переключатель для включения вызовов прогрева. Необходимо указать допустимый URL-адрес GET Keep-alive. Как и в случае с первичной конечной точкой, конечная точка хранения также должна пройти тестовое подключение. Если вы настраиваете внешний вызов с включенными вызовами прогрева, когда объем трафика опускается слишком низко, Защита от мошенничества автоматически делает анонимные вызовы прогревание в конечную точку поддержания работоспособности только с помощью метода GET.

     Примечание.

     Параметры, конфигурации или настраиваемые заголовки не могут использоваться в вызовах прогрева.

   • Проверка подлинности — выберите метод, который следует использовать для проверки подлинности входящих запросов.

     • Если выбрать "Анонимный", заголовок авторизации не отправляется.
     • Если выбрать AAD, в клиенте создается маркер Azure Active Directory (Azure AD), а < носителя >используется в качестве заголовка авторизации.

     Дополнительные сведения о проверке подлинности, авторизации и маркерах Azure AD см. в разделе " Общие сведения о проверке подлинности и авторизации " далее в этой статье.

   • Аудитория — если вы выберете AAD в качестве метода проверки подлинности, вам будет предложено предоставить аудиторию. Вы можете использовать существующее приложение Azure в качестве аудитории или создать новое с помощью интеграции на портале защиты от мошенничества. Убедитесь, что аудитория имеет разрешение на доступ к внешнему вызову или службе. Дополнительные сведения о настройке проверки подлинности Azure Active Directory (Azure AD) см. в статье "Настройка проверки подлинности Azure AD".

   • Идентификатор приложения. Кроме того, необходимо указать идентификатор приложения нового или существующего приложения Azure AD в клиенте подписки На защиту от мошенничества. Создайте сертификат в Azure Key Vault. Приложение защиты от мошенничества должно иметь доступ на чтение к этому Хранилищу ключей Azure. Загрузите сертификат в это приложение Azure AD. Дополнительные сведения о создании приложений Azure AD и управлении ими см. в статье "Создание приложений Azure Active Directory".

   • URL-адрес сертификата— укажите URL-адрес идентификатора сертификата из Azure Key Vault. Это тот же сертификат, который вы загружаете в приложение Azure AD на предыдущем шаге. Дополнительные сведения о создании сертификата в Azure Key Vault см. в статье "Создание и объединение запроса на подпись сертификата в Azure Key Vault"

   • Добавление параметра — можно использовать параметры для передачи данных из защиты от мошенничества в конечную точку API. В зависимости от выбранного метода HTTP эти параметры отправляются в конечную точку в строке запроса или в составе текста запроса.

     Вы можете добавить примеры значений для каждого параметра. Защита от мошенничества использует эти значения параметров для выполнения примера вызова конечной точки перед созданием или при выборе теста.

     Примечание.

     Все значения параметров интерпретируются как строки.

   • Пример запроса— укажите пример запроса , который отправляется во внешний вызов. Запрос должен отражать указанные имена и значения параметров, и его невозможно изменить.

     Для методов GET отображается URL-адрес запроса. Для методов POST отображается текст запроса.

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

   • Пример ответа. Укажите пример данных, возвращаемых в успешном ответе из конечной точки API. Эти данные должны быть в формате нотации объектов JavaScript (JSON) и можно ссылаться в правилах. Приведенный здесь пример показан при создании правил.

     Выберите "Тест" , чтобы автоматически ввести реальный ответ из API в этом поле.

   • время ожидания— укажите, сколько времени в миллисекундах запрос должен ждать до истечения времени ожидания. Необходимо указать число от 1 до 5000.

   • Ответ по умолчанию— укажите ответ по умолчанию, который должен быть возвращен, если запрос завершается сбоем или превышает указанное время ожидания. Значение должно быть допустимым объектом JSON или элементом JSON.

3. Необязательно. Чтобы отправить пример запроса в конечную точку API и просмотреть ответ, выберите "Тест". Дополнительные сведения см. в следующем разделе: тестирование внешнего вызова.

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

Тестирование внешнего вызова

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

• Чтобы проверить подключение во время создания нового внешнего вызова или редактирования существующего внешнего вызова, задайте все обязательные поля и нажмите кнопку "Тест".

  Защита от мошенничества использует конечную точку и параметры, предоставленные для отправки запроса во внешний вызов.

  • Если защита от мошенничества успешно достигает целевой конечной точки, в верхней части панели появится зеленая панель сообщений, чтобы сообщить, что подключение выполнено успешно. Чтобы просмотреть полный ответ, выберите "Просмотреть сведения о ответе".
  • Если защита от мошенничества не может достичь целевой конечной точки или если она не получает ответ до указанного времени ожидания, в верхней части панели появится красная панель сообщений и отображает ошибку, обнаруженную. Чтобы просмотреть дополнительные сведения об ошибке, выберите "Просмотреть сведения об ошибке".

Мониторинг внешних вызовов

Мониторинг внешних вызовов на портале защиты от мошенничества

Защита от мошенничества показывает плитку, содержащую три метрики для каждого внешнего вызова, который вы определяете:

• Запросы в секунду — общее количество запросов, разделенных на общее количество минут в выбранном интервале времени.
• средняя задержка — общее количество задержек запросов, разделенных на общее количество минут в выбранном интервале времени.
• Частота успешного выполнения — общее количество успешных запросов, разделенных на общее количество выполненных запросов.

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

1. Чтобы глубже ознакомиться с данными о внешнем вызове, выберите "Производительность " в правом углу плитки.

   Защита от мошенничества показывает новую страницу с более подробным представлением метрик.

2. Чтобы просмотреть метрики для любого интервала времени за последние три месяца, настройте параметр диапазона дат в верхней части страницы.

Помимо трех описанных ранее метрик отображается диаграмма ошибок . На этой диаграмме показано количество ошибок по типу и коду. Чтобы просмотреть количество ошибок с течением времени или просмотреть распределение ошибок, выберите круговую диаграмму.

Помимо ошибок клиента HTTP (400, 401 и 403), могут появиться следующие ошибки:

• Недопустимый идентификатор приложения — идентификатор приложения, предоставленный в клиенте, или он недействителен.
• Сбой AAD— не удалось получить маркер Azure AD.
• Определение не найдено . Внешний вызов был удален, но он по-прежнему ссылается в правиле.
• Время ожидания — запрос к целевому объекту занял больше времени ожидания, чем указанное время ожидания.
• Сбой связи — подключение к целевому объекту невозможно из-за проблемы с сетью или из-за недоступности целевого объекта.
• Разбиитель канала — если внешний вызов не удалось непрерывно и превысил определенный порог, все дальнейшие вызовы приостановлены на короткий интервал.
• Неизвестный сбой — произошла внутренняя ошибка Dynamics 365.

Использование трассировки событий для мониторинга внешних вызовов

Вы можете использовать возможность трассировки событий защиты от мошенничества для пересылки событий, связанных с внешними вызовами к собственным экземплярам Центры событий Azure или Хранилище BLOB-объектов Azure. На портале защиты от мошенничества на странице трассировки событий можно подписаться на следующие два события, связанные с внешними вызовами:

• ЗащитаОтМошенничества.Мониторинг.ВнешниеВызовы
• ФродПротекшн.Ошибки.ВнешниеВызовы

Каждый раз, когда запрос выполняется во внешний вызов, событие отправляется в пространство имен FraudProtection.Monitoring.ExternalCalls. Полезные данные события включают сведения о задержке вызова, состоянии запроса и правиле и предложении, из которого был активирован запрос.

При сбое внешнего вызова событие отправляется в пространство имен FraudProtection.Errors.ExternalCalls. Полезные данные события включают запрос URI и текст, отправленные во внешний вызов, и полученный ответ.

Дополнительные сведения о трассировке событий, подписке на события и о том, что можно сделать с событиями, см. в разделе "Трассировка событий".

Сведения об интеграции этих данных с рабочими процессами вашей организации и настройке пользовательского мониторинга, оповещений и отчетов см. в разделе "Расширяемость через центры событий".

Управление внешними вызовами

• Чтобы изменить существующий внешний вызов, выберите "Изменить " в заголовке карточки.

  Примечание.

  Вы не можете изменить имя и параметры внешнего вызова после его использования в правиле.

• Чтобы удалить существующий внешний вызов, выберите многоточие (...), а затем нажмите кнопку "Удалить".

  Примечание.

  После ссылки на него в правиле нельзя удалить внешний вызов.

• Чтобы просмотреть подробные метрики производительности для внешнего вызова, выберите "Производительность".

• Чтобы проверить, что защита от мошенничества по-прежнему может подключиться к внешнему вызову, выберите многоточие (...), а затем выберите "Проверить подключение".

Использование внешнего вызова в правилах

Чтобы использовать внешние вызовы для принятия решений, обратитесь к ним из правил.

Например, чтобы ссылаться на внешний вызов, который называется myCall в правиле, используйте следующий синтаксис:

External.myCall()

Если для myCall требуется параметр, например IPaddress, используйте следующий синтаксис:

External.myCall(@"device.ipAddress")

Сведения о языке правил и способах использования внешних вызовов в правилах см. в руководстве по языку.

Общие сведения о проверке подлинности и авторизации

Чтобы обеспечить безопасный доступ к данным, API часто проходят проверку подлинности отправителя запроса, чтобы убедиться, что у них есть разрешение на доступ к данным. Внешние вызовы в Службе защиты от мошенничества поддерживают два метода проверки подлинности: Анонимный и AAD.

Если выбрать "Анонимный", заголовок авторизации в HTTP-запросе к целевой конечной точке остается пустым. Используйте этот параметр, если целевая конечная точка не требует заголовка авторизации. Например, если конечная точка использует ключ API, настройте пару "ключ-значение" в качестве части URL-адреса запроса, введенного в поле веб-запроса . Целевая конечная точка может проверить, разрешен ли ключ API из URL-адреса запроса, а затем решить, следует ли предоставить разрешение.

Если выбрать AAD, заголовок авторизации в HTTP-запросе к целевой конечной точке включает маркер носителя. Маркер носителя — это веб-токен JSON (JWT), выданный Azure AD. Сведения о JWTs см. в платформа удостоверений Майкрософт маркерах доступа. Защита от мошенничества добавляет значение маркера к тексту "Носитель" в требуемом формате в заголовке авторизации запроса, как показано ниже:

<Маркер носителя>

Утверждения маркера

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

Когда 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.");
}

Рекомендации по внешним данным

Вы признаете, что несете ответственность за соблюдение всех применимых законов и правил, включая законы о защите данных без ограничений, договорные ограничения и/или политики, связанные с наборами данных, предоставляемыми корпорацией Майкрософт через функцию защиты от мошенничества. Кроме того, вы признаете, что использование защиты от мошенничества подлежит ограничению, подробно описанному в Клиентское соглашение Майкрософт, которое утверждает, что вы не можете использовать защиту от мошенничества (i) в качестве единственного фактора в определении того, следует ли продолжать с оплатой транзакции; (ii) в качестве фактора определения финансового состояния, финансовой истории, кредитоспособности или права на страхование, жилье или трудоустройство любого человека; или (iii) для принятия решений, которые создают юридические последствия или значительно влияют на человека. Вы также запрещены предоставлять или иначе использовать конфиденциальные или строго регулируемые типы данных в связи с использованием функции внешних вызовов защиты от мошенничества. Прочтите все наборы данных или типы данных перед их использованием с функцией внешних вызовов защиты от мошенничества, чтобы убедиться, что вы соответствуете этой подготовке. Корпорация Майкрософт также оставляет за собой право убедиться, что вы соответствуете этой подготовке.

Дополнительные ресурсы

• Видео: сведения о новой функции внешних вызовов в Dynamics 365 Fraud Protection
• Блог. Настройка защиты с помощью новых функций в предварительной версии Dynamics 365 Fraud Protection: принятие обоснованных решений в режиме реального времени с помощью внешних вызовов