排查入站预配 API 问题
简介
本文档介绍入站预配 API 中常见的错误和问题，以及如何对其进行故障排除。
故障排除方案
数据格式无效
问题说明
- 你收到错误消息
Invalid Data Format，其中包含 HTTP 400（请求错误）响应代码。
可能的原因
- 你根据预配 /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 响应。 避免这种情况的一种方法是在客户端请求提交逻辑中使用延迟来加快请求提交速度。
24 小时内 6000 次 API 调用 - 如果调用数超出此限制，则客户端将收到 429 响应。 防止出现此情况的一种方法是确保对 SCIM 批量有效负载进行优化，以使用每个 API 调用的最大 50 条记录。 使用此方法，可以每 24 小时发送 30 万条记录。
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 接受的 UPN 值来解决此问题。