Часто задаваемые вопросы о входящего подготовки на основе API

В этой статье приведены ответы на часто задаваемые вопросы о входящего подготовки на основе API.

Как новый API подготовки /bulkUpload для входящего трафика отличается от API пользователей MS Graph?

Существуют значительные различия между API подготовки /bulkUpload и конечной точкой API пользователей MS Graph.

• Формат полезных данных: конечная точка API пользователей MS Graph ожидает данные в формате OData. Формат полезных данных запроса для нового API подготовки входящего трафика /bulkUpload использует конструкции схемы SCIM. При вызове этого API задайте для заголовка application/scim+jsonContent-Type значение .
• Результат выполнения операции:
  • Когда данные удостоверений отправляются в конечную точку API пользователей MS Graph, она немедленно обрабатывается, а операция создания и обновления и удаления выполняется в профиле пользователя Microsoft Entra.
  • Запрос данных, отправленных в API подготовки /bulkUpload, обрабатывается асинхронно службой подготовки Microsoft Entra. Задание подготовки применяет правила области, сопоставление атрибутов и преобразование, настроенные ИТ-администратором. Это инициирует Create/Update/Delete операцию с профилем пользователя Microsoft Entra или локальным профилем пользователей AD.
• ИТ-администратор сохраняет контроль: при подготовке, управляемой API, ИТ-администратор имеет больше контроля над обработкой и сопоставлением входящих данных удостоверения с атрибутами Microsoft Entra. Они могут определять правила области, чтобы исключить определенные типы данных удостоверений (например, данные подрядчика) и использовать функции преобразования для получения новых значений перед настройкой значений атрибутов в профиле пользователя.

Является ли API подготовки /bulkUpload стандартной конечной точкой SCIM?

API подготовки /bulkUpload ms Graph использует схему SCIM в полезных данных запроса, но это не стандартизированная конечная точка API SCIM. Для этого есть следующие причины.

Как правило, конечная точка службы SCIM обрабатывает HTTP-запросы (POST, PUT, GET) с полезными данными SCIM и преобразует их в соответствующие операции (Создание, обновление, поиск) в хранилище удостоверений. Конечная точка службы SCIM помещает на конечную точку службы SCIM указание семантики операций, независимо от того, нужно ли создать или обновить или удалить удостоверение на клиенте API SCIM. Этот механизм хорошо подходит для сценариев, когда клиент API знает, какую операцию он хотел бы выполнить для пользователей в хранилище удостоверений.

Входящий трафик ms Graph /bulkUpload предназначен для обработки другого сценария интеграции корпоративных удостоверений, сформированного тремя уникальными требованиями:

1. Возможность асинхронно обрабатывать записи в массовом режиме (например, обработка записей 50K+ )
2. Возможность включать любой атрибут удостоверения в полезные данные (например, costCenter, pay grade, badgeId)
3. Поддержка клиентов API, не зная о семантике операций. Эти клиенты — это клиенты API, отличные от SCIM, которые имеют доступ только к необработанным исходным данным (например, записям в CSV-файле, таблице SQL или записям кадров). У этих клиентов нет возможности обработки для чтения каждой записи и определения семантики Create/Update/Delete операции в хранилище удостоверений.

Основной целью входящего подготовки /bulkUpload API MS Graph является предоставление клиентам возможности отправлять данные удостоверений (например, costCenter, pay grade, badgeId) из любого источника данных удостоверения (например, CSV/SQL/HR) для конечной обработки службой подготовки Microsoft Entra. Служба подготовки Microsoft Entra использует данные массовой полезных данных, полученные в этой конечной точке, применяет правила сопоставления атрибутов, настроенные ИТ-администратором, и определяет, приводит ли полезные данные к операции (Create, Update, Enable, Disable) в целевом хранилище удостоверений (идентификатор Microsoft Entra ID / on-premises AD).

Поддерживает ли API подготовки /bulkUpload локальная служба Active Directory домены в качестве целевого объекта?

Да, API подготовки поддерживает локальные домены AD в качестве целевого объекта.

Как получить конечную точку API /bulkUpload для нашего приложения подготовки?

API /bulkUpload доступен только для приложений типа: "Подготовка входящих подключений на основе API к идентификатору Microsoft Entra ID" и "подготовка на основе API для локальная служба Active Directory". Вы можете получить уникальную конечную точку API для каждого приложения подготовки из домашней страницы колонки подготовки. В статистике на сегодняшний день>просмотрите технические сведения, скопируйте URL-адрес конечной точки API подготовки.

Он имеет формат:

https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

Как выполнить полную синхронизацию с помощью API подготовки /bulkUpload?

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

Как выполнять разностную синхронизацию с помощью API подготовки /bulkUpload?

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

Как работает подготовка перезапуска?

Используйте параметр подготовки перезапуска, только если это необходимо. Вот как это работает:

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

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

Как создавать пользователей с помощью конечной точки API подготовки /bulkUpload?

Вот как задание подготовки, связанное с конечной точкой API /bulkUpload, обрабатывает входящие полезные данные пользователей:

1. Задание извлекает сопоставление атрибутов для задания подготовки и запишите пару соответствующих атрибутов (по умолчанию externalId атрибут API используется для сопоставления с employeeId идентификатором Microsoft Entra ID).
2. Эту пару атрибутов по умолчанию можно изменить.
3. Задание извлекает каждую операцию, присутствующих в полезных данных массового запроса.
4. Задание проверка идентификатор сопоставления значений в запросе (по умолчанию атрибутexternalId) и использует его для проверка, если у пользователя в идентификаторе Microsoft Entra с соответствующим employeeId значением.
5. Если задание не находит соответствующего пользователя, задание применяет правила синхронизации и создает нового пользователя в целевом каталоге.

Чтобы убедиться, что правильные пользователи создаются в идентификаторе Microsoft Entra ID, определите правильную пару атрибутов сопоставления в сопоставлении, которая однозначно идентифицирует пользователей в исходном коде и идентификаторе Microsoft Entra.

Как создать уникальные значения для имени участника-службы?

Служба подготовки не предоставляет возможность проверка для повторяющихся userPrincipalName (UPN) и обрабатывать конфликты. Если правило синхронизации по умолчанию для атрибута UPN создает существующее значение имени участника-пользователя, то операция создания пользователя завершается ошибкой.

Ниже приведены некоторые варианты, которые можно рассмотреть для создания уникальных имен участника-службы:

1. Добавьте логику для уникального создания имени участника-службы в клиенте API.
2. Обновите правило синхронизации для атрибута имени участника-пользователя, чтобы использовать функцию RandomString и задать для параметра применения сопоставления значение On object creation only. Пример:

Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

3. При подготовке к локальная служба Active Directory можно использовать функцию SelectUniqueValue и задать для параметра применения сопоставления значение On object creation only.

Как отправлять дополнительные атрибуты кадров в конечную точку API подготовки /bulkUpload?

По умолчанию конечная точка API поддерживает обработку любого атрибута, который является частью схемы пользователя SCIM Core и корпоративного пользователя. Если вы хотите отправить дополнительные атрибуты, можно расширить схему приложения подготовки, сопоставить новые атрибуты с атрибутами Microsoft Entra и обновить массовый запрос для отправки этих атрибутов. Ознакомьтесь с руководством по расширению подготовки на основе API для синхронизации пользовательских атрибутов.

Как исключить некоторых пользователей из потока подготовки?

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

Это можно сделать с помощью фильтра области. В конфигурации приложения подготовки можно определить исходный объект область и исключить некоторых пользователей из обработки с помощью "правила включения" (например, только обработать пользователей, где отдел EQUALS Sales) или "правило исключения" (например, исключить пользователей, принадлежащих продажам, отделУ NOT EQUALS Sales).

См. сведения о подготовке пользователей или групп области с помощью фильтров области.

Как обновить пользователей с помощью конечной точки API подготовки /bulkUpload?

Вот как задание подготовки, связанное с конечной точкой API /bulkUpload, обрабатывает входящие полезные данные пользователей:

1. Задание подготовки извлекает сопоставление атрибутов для задания подготовки и заметит пару атрибутов сопоставления (по умолчанию externalId атрибут API используется для сопоставления с employeeId идентификатором Microsoft Entra ID). Эту пару атрибутов по умолчанию можно изменить.
2. Задание извлекает операции из полезных данных массового запроса.
3. Задание проверка идентификатор сопоставления значений в запросе SCIM (по умолчанию: атрибут externalIdAPI) и использует его для проверка, если в Microsoft Entra ID есть пользователь с соответствующим employeeId значением.
4. Если задание находит соответствующего пользователя, оно применяет правила синхронизации и сравнивает исходные и целевые профили.
5. Если задание определяет, что некоторые значения изменились, оно обновляет соответствующую запись пользователя в каталоге.

Чтобы убедиться, что правильные пользователи обновляются в идентификаторе Microsoft Entra ID, убедитесь, что вы определяете правильную пару атрибутов сопоставления в сопоставлении, которая однозначно идентифицирует пользователей в источнике и идентификаторе Microsoft Entra.

Можно ли создать несколько приложений, поддерживающих входящий трафик, управляемый API?

Да, вы можете. Ниже приведены некоторые сценарии, для которых может потребоваться несколько приложений подготовки:

Сценарий 1. Предположим, что у вас есть три надежных источника данных: один для сотрудников, один для подрядчиков и один для поставщиков. Можно создать три отдельных приложения подготовки — по одному для каждого типа удостоверения с собственным сопоставлением отдельных атрибутов. Каждое приложение подготовки имеет уникальную конечную точку API, и вы можете отправлять соответствующие полезные данные в каждую конечную точку.

Вы можете получить уникальную конечную точку API для каждого задания на домашней странице колонки подготовки. Перейдите к статистике на дату>просмотра технических сведений, а затем скопируйте URL-адрес конечной точки API подготовки.

Сценарий 2. Предположим, что у вас есть несколько источников истины, каждый из которых имеет собственный набор атрибутов. Например, HR предоставляет атрибуты сведений о задании (например, jobTitle, employeeType), а система Badging предоставляет атрибуты сведений о значках (например badgeId , представленные с помощью атрибута расширения). В этом сценарии можно настроить два приложения подготовки:

• Подготовка приложения #1 , которое получает атрибуты из источника кадров и создает пользователя.

• Подготовка приложения #2 , которое получает атрибуты из системы Badging и обновляет только атрибуты пользователя. Сопоставление атрибутов в этом приложении ограничено атрибутами сведений о индикаторах событий и в разделе "Действия целевых объектов" включено только обновление.

• Оба приложения используют одну и ту же пару идентификаторов (externalId<->employeeId)

Как обрабатывать завершения с помощью конечной точки API /bulkUpload?

Чтобы обработать завершение работы, определите атрибут в источнике, который будет использоваться для задания флага accountEnabled в идентификаторе Microsoft Entra. При подготовке к локальная служба Active Directory сопоставьте этот исходный атрибут с атрибутомaccountDisabled.

По умолчанию значение, связанное с атрибутом active схемы scIM Core User, определяет состояние учетной записи пользователя в целевом каталоге.

Если атрибут имеет значение true, правило сопоставления по умолчанию включает учетную запись. Если атрибут имеет значение false, то правило сопоставления по умолчанию отключает учетную запись.

Как предотвратить случайное отключение и удаление пользователей?

Чтобы предотвратить и восстановить случайное удаление, рекомендуется настроить порог случайного удаления в приложении подготовки и включить корзину локальная служба Active Directory. В колонке сопоставления атрибутов приложения подготовки в разделе "Действия целевого объекта" отключите операцию Delete.

Восстановление удаленных учетных записей

• Если целевой каталог для операции является идентификатором Microsoft Entra, соответствующий пользователь обратимо удаляется. Пользователь может быть замечен на странице удаленных пользователей Центра администрирования Microsoft Entra в течение следующих 30 дней и может быть восстановлен в течение этого времени.
• Если целевой каталог для операции локальная служба Active Directory, то соответствующий пользователь жестко удаляется. Если корзина Active Directory включена, можно восстановить удаленный локальный объект пользователя AD.

Нужно ли отправлять всех пользователей из системы управления персоналом в каждом запросе?

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

Поддерживает ли API все действия HTTP (GET/POST/PUT/PATCH)?

Нет, конечная точка API подготовки /bulkUpload поддерживает только действие POST HTTP.

Если нужно обновить пользователя, нужно ли отправить запрос PUT/PATCH?

Нет, конечная точка API не поддерживает запрос PUT/PATCH. Чтобы обновить пользователя, отправьте данные, связанные с пользователем, в полезных данных массового запроса POST.

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

Как поддерживается обратная запись?

Текущий API поддерживает только входящие данные. Ниже приведены некоторые варианты для реализации обратной записи атрибутов, таких как электронная почта/ имя пользователя/ телефон, созданный идентификатором Microsoft Entra ID, который можно выполнить обратно в систему кадров:

• Вариант 1. Подключение SCIM к конечной точке или прокси-службе кадров, которая, в свою очередь, обновляет источник кадров

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

• Вариант 2. Использование соединителя MICROSOFT Entra ECMA для сценария обратной записи

  • В зависимости от требования клиента изучите, может ли использоваться один из соединителей ECMA (PowerShell/ SQL/ Веб-службы).

• Вариант 3. Использование настраиваемой задачи расширения рабочих процессов жизненного цикла в рабочем процессе объединения

  • В рабочих процессах жизненного цикла определите рабочий процесс Joiner и определите пользовательскую задачу расширения, которая вызывает процесс Logic Apps, который обновляет систему управления персоналом или создает CSV-файл, используемый системой управления персоналом.

Следующие шаги

• Настройка приложения подготовки на основе API на основе входящего трафика
• Дополнительные сведения о подготовке входящего трафика на основе API см . в концепциях API подготовки входящих пользователей.