通过

有关 API 驱动的入站预配的常见问题

本文解答了有关 API 驱动的入站预配的常见问题（常见问题解答）。

新的入站预配 /bulkUpload API 与 MS Graph 用户 API 有何不同？

预配 /bulkUpload API 与 MS Graph 用户 API 终结点之间存在显著差异。

  • 有效负载格式：MS Graph 用户 API 终结点需要 OData 格式的数据。 新入站预配 /bulkUpload API 的请求有效负载格式使用 SCIM 架构构造。 调用此 API 时，请将“Content-Type”标头设置为 application/scim+json。
  • 操作结果：
    • 将标识数据发送到 MS Graph 用户 API 终结点时，将立即处理该数据，并在 Microsoft Entra 用户配置文件上执行创建/更新/删除作。
    • Microsoft Entra 预配服务 以异步 方式处理发送到预配 /bulkUpload API 的请求数据。 预置任务应用 IT 管理员配置的范围规则、属性映射和转换。这将启动对 Microsoft Entra 用户配置文件或本地 AD 用户配置文件的 Create/Update/Delete 操作。
  • IT 管理员保留控制权：使用 API 驱动的入站预配，IT 管理员可以更控制传入标识数据的处理方式，并将其映射到Microsoft Entra 属性。 他们可以定义范围规则，以排除某些类型的标识数据（例如承包商数据），并使用转换函数在设置用户配置文件上的属性值之前派生新值。

入站预配 /bulkUpload API 是否为标准 SCIM 终结点？

MS Graph 入站预配 /bulkUpload API 在请求有效负载中使用 SCIM 架构，但它 不是 标准化的 SCIM API 终结点。 原因如下。

通常，SCIM 服务终结点使用 SCIM 有效负载来处理 HTTP 请求（POST、PUT、GET），并将其转换为在身份存储上的相应操作（创建、更新、查找）。 SCIM 服务终结点将确定操作语义（创建/更新/删除标识）的责任放在 SCIM API 客户端上。 此机制适用于 API 客户端知道希望为身份存储中的用户执行哪些操作的情况。

MS Graph 入站预配 /bulkUpload 旨在处理由三个独特要求塑造的不同企业标识集成场景：

  1. 能够以异步方式批量处理记录（例如，处理 50K+ 条记录）
  2. 能够在有效负载中包含任何标识属性（例如 costCenter、pay grade、badgeId）
  3. 支持不知道操作语义的 API 客户端。 这些客户端是仅有权访问原始 源数据的 非 SCIM API 客户端（例如 CSV 文件、SQL 表或 HR 记录中的记录）。 这些客户端不具备读取每条记录和确定标识存储上 Create/Update/Delete 的操作语义的处理能力。

MS Graph 入站预配 /bulkUpload API 的主要目标是让客户从 任何 标识数据源（例如 CSV/SQL/HR）发送 任何 标识数据（例如，costCenter、付费等级、badgeId），以便通过 Microsoft Entra 预配服务最终处理。 Microsoft Entra 预配服务会处理在此终结点接收到的批量有效负载数据，使用由 IT 管理员配置的属性映射规则，确定这些数据是否会导致在目标身份存储（Microsoft Entra ID 或本地 AD）中进行创建、更新、启用或禁用操作。

预配 /bulkUpload API 是否支持本地 Active Directory 域作为目标？

是的，预配 API 支持本地 AD 域作为目标。

如何获取预配应用的 /bulkUpload API 终结点？

/bulkUpload API 仅适用于以下类型的应用：“API 驱动的 Microsoft Entra ID 入站预配”和“API 驱动的本地 Active Directory 入站预配”。 可以从“预配”边栏选项卡主页检索每个预配应用的唯一 API 终结点。 在截至目前的统计信息>查看技术信息中，复制“预配 API 终结点”URL。

它具有以下格式：

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

如何使用预配 /bulkUpload API 执行完全同步？

若要执行完全同步，请使用 API 客户端以批量请求的形式将所有用户的数据从受信任的源发送到 API 终结点。 将所有数据发送到 API 终结点后，下一个同步周期将处理所有用户记录，并允许使用预配日志 API 终结点跟踪进度。

如何使用预配 /bulkUpload API 执行增量同步？

若要执行增量同步，请使用 API 客户端仅发送有关其数据在受信任源中已更改的用户的信息。 将所有数据发送到 API 终结点后，下一个同步周期将处理所有用户记录，并允许使用预配日志 API 终结点跟踪进度。

重启预配的工作原理是什么？

仅在需要时使用 “重启预配 ”选项。 以下是其工作原理：

方案 1： 单击“ 重启预配 ”按钮且作业当前正在运行时，该作业将继续处理已暂存的现有数据。 重启预配作不会中断现有周期。 在后续周期中，预配服务会清除任何托管项，并选取要处理的新批量请求。

方案 2： 单击“ 重启预配 ”按钮且作业 未 运行，然后在运行后续周期之前，预配引擎将清除在重启之前上传的数据，清除任何托管项，并且仅处理新的传入数据。

如何使用配置/bulkUpload API 端点创建用户？

下面是与 /bulkUpload API 终结点关联的预配作业处理传入用户有效负载的方式：

  1. 该作业检索预配作业的属性映射并记下匹配的属性对（默认情况下 externalId ，API 属性用于在 Microsoft Entra ID 中匹配 employeeId ）。
  2. 可以更改此默认属性匹配对。
  3. 作业提取批量请求有效负载中存在的每个操作。
  4. 该作业检查请求中的值匹配标识符（默认情况下为属性 externalId），并使用它来检查是否存在具有匹配 employeeId 值的 Microsoft Entra ID 中的用户。
  5. 如果作业找不到匹配的用户，则该作业将应用同步规则并在目标目录中创建新用户。

若要确保正确的用户是在 Microsoft Entra ID 中创建的，请在映射中定义正确的匹配属性对，以唯一标识源中的用户并Microsoft Entra ID。

如何为 UPN 生成唯一值？

预配服务不具备检查 userPrincipalName（UPN）重复性和处理冲突的功能。 如果 UPN 属性的默认同步规则生成现有的 UPN 值，则用户创建操作将失败。

下面是可用于生成唯一 UPN 的一些选项：

  1. 在 API 客户端中添加用于唯一 UPN 生成的逻辑。
  2. 更新 UPN 属性的同步规则以使用 RandomString 函数并将应用映射参数设置为 On object creation only。 示例：

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

  1. 如果要预配到本地 Active Directory，则可以使用 SelectUniqueValue 函数并将应用映射参数 On object creation only设置为 。

如何向预配 /bulkUpload API 终结点发送更多 HR 属性？

默认情况下，API 终结点支持处理属于 SCIM 核心用户和企业用户架构的任何属性。 如果要发送更多属性，可以扩展预配应用架构，将新属性映射到 Microsoft Entra 属性，并更新批量请求以发送这些属性。 请参阅本教程 扩展 API 驱动的预配以同步自定义属性。

如何从预配流中排除某些用户？

你可能想要将所有用户发送到 API 终结点，但仅在预配流中包含特定用户并排除其余用户的情况。

可以使用 范围筛选器实现此目的。 在预配应用配置中，可以定义源对象范围，并使用“包含规则”（例如，仅处理部门等于“销售”的用户）或“排除规则”（例如，排除属于“销售”、部门不等于“销售”的用户）将某些用户排除在处理之外。

请参阅使用范围筛选器确定要预配的用户或组的范围。

如何使用预配 /bulkUpload API 终结点更新用户？

下面是与 /bulkUpload API 终结点关联的预配作业处理传入用户有效负载的方式：

  1. 预配作业检索预配作业的属性映射，并记下匹配的属性对（默认情况下，externalId API 属性用于在 Microsoft Entra ID 中与 employeeId 匹配）。 可以更改此默认属性匹配对。
  2. 作业从批量请求有效负载中提取操作。
  3. 该作业检查 SCIM 请求（默认情况下：API 属性 externalId）中的值匹配标识符，并使用它来检查是否存在具有匹配 employeeId 值的 Microsoft Entra ID 中的用户。
  4. 如果作业找到匹配的用户，则会应用同步规则并比较源和目标配置文件。
  5. 如果作业确定某些值已更改，则会更新目录中的相应用户记录。

若要确保在 Microsoft Entra ID 中更新正确的用户，请确保在映射中定义正确的匹配属性对，以唯一标识源和 Microsoft Entra ID 中的用户。

是否可以创建支持 API 驱动的入站预配的多个应用？

是的，可以。 下面是可能需要多个预配应用的一些方案：

方案 1： 假设你有三个受信任的数据源：一个用于员工，一个用于承包商，一个用于供应商。 可以创建三个单独的预配应用 - 每个标识类型都有其自己的不同属性映射。 每个预配应用都有一个唯一的 API 终结点，可以将相应的有效负载发送到每个终结点。

可以从“预配”边栏选项卡主页检索每个作业的唯一 API 终结点。 导航到 截止目前的统计信息>查看技术信息，然后复制 配置 API 终结点 URL。

方案 2： 假设你有多个事实来源，每个来源都有其自己的属性集。 例如，HR 提供职位信息属性（例如 jobTitle、employeeType），而徽章系统提供徽章信息属性（例如 badgeId，使用扩展属性表示）。 在此方案中，可以配置两个预配应用：

  • 预配应用 #1 ，用于从 HR 源接收属性并创建用户。

  • 预配应用 #2 ，用于从 Badging 系统接收属性，并且仅更新用户属性。 此应用中的属性映射仅限于徽章信息属性，并且仅在“目标对象操作”下启用更新。

  • 这两个应用使用相同的匹配标识符对 （externalId<->employeeId）

如何使用 /bulkUpload API 端点处理终止请求？

若要处理终止，请在源中标识一个属性，该属性将用于在 Microsoft Entra ID 中设置 accountEnabled 标志。 如果要预配到本地 Active Directory，请将该源属性映射到该 accountDisabled 属性。

默认情况下，与 SCIM Core User 架构属性 active 关联的值确定目标目录中用户帐户的状态。

如果属性设置为 true，则默认映射规则将启用帐户。 如果属性设置为 false，则默认映射规则将禁用该帐户。

如何防止意外禁用/删除用户？

若要防止和恢复意外删除，建议在预配应用中 配置意外删除阈值 并 启用本地 Active Directory 回收站。 在预配应用“属性映射”边栏选项卡的“目标对象操作”下禁用“删除”操作。

恢复已删除的帐户

  • 如果操作的目标目录为 Microsoft Entra ID，则会软删除匹配的用户。 用户可以在接下来的 30 天内在 Microsoft Entra 管理中心 的“已删除用户 ”页面上看到，并且可以在此期间还原。
  • 如果作的目标目录是本地 Active Directory，则会硬删除匹配的用户。 如果 启用了 Active Directory 回收站 ，则可以还原已删除的本地 AD 用户对象。

是否需要在每个请求中从 HR 系统发送所有用户？

否，不需要在每个请求中从 HR 系统发送所有用户/“事实来源”。 只需发送您想要创建或更新的用户信息。

API 是否支持所有的 HTTP 操作（GET/POST/PUT/PATCH）？

否，/bulkUpload 预配 API 终结点仅支持 HTTP POST 操作。

如果想要更新用户，是否需要发送 PUT/PATCH 请求？

否，API 终结点不支持 PUT/PATCH 请求。 若要更新用户，请在 POST 批量请求有效负载中发送与用户关联的数据。

处理 API 终结点接收的数据的预配置作业会根据配置的同步规则自动检测在 POST 请求有效负载中收到的用户是否需要被创建、更新、启用或禁用。 作为 API 客户端，如果希望更新用户配置文件，则无需再执行任何步骤。

写回功能是如何被支持的？

当前 API 仅支持入站数据。 下面是在实现 Microsoft Entra ID 生成的电子邮件/用户名/电话等属性写回时要考虑的一些选项，这些属性可以流回 HR 系统：

  • 选项 1 - SCIM 与 HR 终结点/代理服务的连接，后者反过来更新 HR 源

    • 如果记录系统为用户更新提供 SCIM 终结点，则可以在企业应用库中创建自定义 SCIM 应用程序，并按照文档所述配置预配置。
    • 如果记录系统不提供 SCIM 终结点，请探索设置代理 SCIM 服务的可能性，该服务接收更新并将更改传播到 HR 系统。

  • 选项 2 – 对写回方案使用 Microsoft Entra ECMA 连接器

    • 根据客户要求，了解是否可以使用其中一个 ECMA 连接器（PowerShell/SQL/Web Services）。

  • 选项 3 - 在联接器工作流中使用生命周期工作流自定义扩展任务

后续步骤