介绍
本文档介绍入站预配 API 的常见错误和问题，以及如何对其进行故障排除。
故障排除方案
数据格式无效
问题说明
- 收到 HTTP 400（错误请求）响应代码的错误消息
Invalid Data Format。
可能的原因
- 根据预配 /bulkUpload API 规范发送有效的批量请求，但尚未将 HTTP 请求标头“Content-Type”
application/scim+json设置为。 - 你正在发送不符合预配 /bulkUpload API 规范的批量请求。
解决方法：
- 确保 HTTP 请求的
Content-Type标头设置为值application/scim+json。 - 确保批量请求有效负载符合预配 /bulkUpload API 规范。
预配日志中没有任何内容
问题说明
- 你向预配 /bulkUpload API 终结点发送了请求，并且收到了 HTTP 202 响应代码，但预配日志中没有对应于你的请求的数据。
可能的原因
- API 驱动的预配应用已暂停。
- 预配服务尚未使用批量请求处理详细信息更新预配日志。
- 本地预配代理状态未激活（如果您正在运行 通过 API 驱动的入站用户预配到本地 Active Directory）。
解决方法：
- 验证预配应用是否正在运行。 如果未运行，请选择菜单选项 “开始预配 ”以处理数据。
- 通过重启本地代理，将本地预配代理状态设置为活动状态。
- 处理请求和写入预配日志之间需要 5 分钟到 10 分钟的延迟。 如果 API 客户端将数据发送到预配 /bulkUpload API 终结点，则引入请求调用和预配日志查询之间的时间延迟。
禁止 403 响应代码
问题说明
- 你向预配 /bulkUpload API 终结点发送了请求，并获得了 HTTP 403（禁止）响应代码。
可能的原因
- 未将 Graph 权限
SynchronizationData-User.Upload分配给 API 客户端。
解决方法：
- 为 API 客户端分配 Graph 权限
SynchronizationData-User.Upload，然后重试该操作。
请求过多 429 响应代码
bulkUpload API 终结点强制实施以下限制，如果违反这些限制，则返回 429 响应代码。
每 5 秒 40 个 API 调用 - 如果调用数超出 5 秒范围内的此限制，则客户端将获得 429 响应。 避免这种情况的一种方法是，使用客户端请求提交逻辑中的延迟 来加快 请求提交速度。
6,000 个 API 调用在 24 小时内 - 如果调用数超出此限制，则客户端将获得 429 响应。 防止这种情况的一种方法是确保 SCIM 批量有效负载经过优化，以使用每个 API 调用的最大 50 条记录。 使用此方法，可以每隔 24 小时发送 30 万条记录。
Bucket 已满 500 响应代码
问题说明
- SCIM 客户端收到 HTTP 500（内部服务器错误）消息：“存储引入数据的存储桶已满，请等待同步服务处理引入的数据并重试此请求。
- 将大型 HR 数据集发送到预配
/bulkUpload终结点时，可能会在初始同步或完全同步周期期间看到此错误。
出现此错误的原因
- “bucket”是预配服务使用的临时摄取队列，用于在处理传入的
/bulkUpload有效负载之前对其进行缓冲。 - 每个 API 驱动的预配作业都有一个专用的引入队列。
- 预配服务持续处理队列中的负载数据，然后删除已处理的数据。 如果这一处理和删除周期跟不上或停止，队列中的数据就可能不断积压，直到存储桶被占满。
可能的原因和解决方法
| 原因 | 解决方案 |
|---|---|
| 由于映射不正确（例如，尝试更新由本地 Active Directory 管理的 Microsoft Entra ID 属性）或数据无效，有效负载处理会失败。 失败的负载会保留在队列中，最终可能会将桶填满。 | 查看预配日志以识别失败的请求处理、修复映射或数据问题、重启预配作业并重新发送请求。 |
| API 驱动的预配作业处于 “已暂停 ”或 “已停止 ”状态。 请求仍在排队，但处理不会启动。 | 恢复预配作业，使其能够处理并清除队列中的请求。 |
| API 驱动的预配作业长期处于 隔离 状态。 请求仍在排队，但处理不会启动。 | 重启预配作业以解除隔离。 重启期间，将清除现有的排队数据，这可能需要一些时间。 等待大约 40 分钟，然后重新发送 SCIM /bulkUpload 请求。 |
| 源系统发送 SCIM 数据的速度快于预配作业处理这些数据的速度。 | Pace 请求提交。 每次批量上传后，检查 HTTP 状态代码。 如果收到带有“bucket 已满”消息的 HTTP 500 错误，请先暂停客户端（例如 5 到 10 分钟），然后再重试。 |
未经授权的 401 响应代码
问题说明
- 你向预配 /bulkUpload API 终结点发送了请求，并获得了 HTTP 401（未授权）响应代码。 错误代码显示“InvalidAuthenticationToken”，其中包含“访问令牌已过期或尚无效”的消息。
可能的原因
- 访问令牌已过期。
解决方法：
- 为 API 客户端生成新的访问令牌。
作业进入隔离状态
问题说明
- 你刚刚启动了配置应用程序，而且它处于隔离状态。
可能的原因
- 在启动作业之前，你尚未设置通知电子邮件。
分辨率： 转到 “编辑预配 ”菜单项。 在 “设置” 下，在 发生故障时发送电子邮件通知 以及输入 通知电子邮件的字段旁边有一个复选框。 请确保选中该框，提供电子邮件并保存更改。 单击“ 重启预配 ”，使作业脱离隔离。
用户创建 - UPN 无效
问题说明 用户预配失败。 预配日志显示错误代码： AzureActiveDirectoryInvalidUserPrincipalName
解决方法：
- 访问 “编辑属性映射 ”页。
- 选择
UserPrincipalName映射并将其更新为使用RandomString函数。 - 将此表达式复制并粘贴到表达式框中：
Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())
此表达式通过将随机数追加到Microsoft Entra ID 接受的 UPN 值来修复此问题。
用户创建失败 - 域无效
问题说明 用户预配失败。 预配日志显示一条错误消息，指出 domain does not exist。
解决方法：
- 转到 “编辑属性映射 ”页。
- 选择
UserPrincipalName映射并将此表达式复制并粘贴到表达式输入框中：Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())
此表达式通过将默认域追加到 Microsoft Entra ID 接受的 UPN 值来修复此问题。
已知限制：多值地址、电子邮件和电话号码
问题说明
- API 驱动的预配过程当前不会处理
addresses、emails和phoneNumbers中的 SCIM 多值属性，当type的值为home或任何其他非work值时。 - 此限制适用于表达式，例如
addresses[type eq "home"]，addresses[type eq "any-other-value"]和phoneNumbers[type eq "home"]。
当前行为
- 仅处理
addresses[type eq "work"]、emails[type eq "work"]和phoneNumbers[type eq "work"]的值。
解决方法
- 需要 API 驱动的预配处理属性时，请使用
work类型发送支持的值。