通过

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

  • 项目

本文解答有关 API 驱动的入站预配的常见问题 (FAQ)。

新的入站预配 /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 用户配置文件上执行创建/更新/删除操作。
    • 发送到预配 /bulkUpload API 的请求数据由 Microsoft Entra 预配服务异步处理。 预配作业应用由 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. 能够批量异步处理记录（例如，处理 5 万多条记录）
  2. 能够在有效负载中包含任何标识属性（例如 costCenter、pay grade、badgeId）
  3. 支持不知道操作语义的 API 客户端。 这些客户端是非 SCIM API 客户端，仅有权访问原始源数据（例如，CSV 文件、SQL 表或 HR 记录中的记录）。 这些客户端不具备读取每条记录和确定标识存储上 Create/Update/Delete 的操作语义的处理能力。

MS Graph入站预配 /bulk Upload API 的主要目标是使客户能够从任何标识数据源（例如 CSV/SQL/HR）发送任意标识数据（例如，costCenter、pay grade、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），并使用它来检查 Microsoft Entra ID 中是否有与 employeeId 值匹配的用户。
  5. 如果作业找不到匹配的用户，则该作业将应用同步规则并在目标目录中创建新用户。

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

如何为 UPN 生成唯一值？

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

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

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

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

  1. 如果要预配到本地 Active Directory，可以使用 SelectUniqueValue 函数并将 apply mapping 参数设置为 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），并使用它来检查 Microsoft Entra ID 中是否有与 employeeId 值匹配的用户。
  4. 如果作业找到匹配的用户，则会应用同步规则并比较源配置文件和目标配置文件。
  5. 如果作业确定某些值已更改，则会更新目录中的相应用户记录。

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

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

可以。 下面是可能需要多个预配应用的一些场景：

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

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

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

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

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

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

如何使用 /bulkUpload API 终结点处理终止？

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

默认情况下，与 SCIM 核心用户架构属性 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 终结点仅支持 POST HTTP 操作。

如果想要更新用户，是否需要发送 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 服务）。

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

后续步骤