インバウンド プロビジョニング API の問題のトラブルシューティング

概要

このドキュメントでは、インバウンド プロビジョニング API で発生する一般的なエラーや問題とそのトラブルシューティング方法について説明します。

トラブルシューティングのシナリオ

データ形式が無効です

問題の説明

• HTTP 400 (Bad Request) 応答コードで Invalid Data Format エラー メッセージを受信しました。

考えられる原因

1. プロビジョニング /bulkUpload API 仕様に従って有効な一括要求が送信されていますが、HTTP 要求ヘッダー 'Content-Type' が application/scim+json に設定されていません。
2. プロビジョニング /bulkUpload API 仕様に準拠していない一括要求が送信されています。

解決方法:

1. HTTP 要求のヘッダー Content-Type の値が application/scim+json に設定されていることを確認します。
2. 一括要求ペイロードがプロビジョニング /bulkUpload API 仕様に準拠していることを確認します。

プロビジョニング ログが空である

問題の説明

• プロビジョニング /bulkUpload API エンドポイントに要求を送信し、HTTP 202 応答コードを取得しましたが、要求に対応するデータがプロビジョニング ログにありません。

考えられる原因

1. API 駆動型プロビジョニング アプリが一時停止しています。
2. プロビジョニング サービスは、プロビジョニング ログに対して一括要求処理の詳細での更新をまだ行っていません。
3. オンプレミス プロビジョニング エージェントの状態は非アクティブです ( /API 駆動型のオンプレミス Active Directory への受信ユーザー プロビジョニングを実行している場合)。

解決方法:

1. プロビジョニング アプリが実行されていることを確認します。 実行されていない場合は、メニュー オプション [プロビジョニングの開始] を選択してデータを処理します。
2. オンプレミス エージェントを再起動して、オンプレミス プロビジョニング エージェントの状態をアクティブにします。
3. 要求の処理とプロビジョニング ログへの書き込みの間に 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 応答を受け取ります。 これを回避する 1 つの方法は、クライアント要求の送信ロジックで遅延を使用して要求の送信の "ペースを調整する" ことです。 

• 24 時間にわたって 6,000 回の API 呼び出し - 呼び出しの数がこの制限を超えた場合、クライアントは 429 応答を受け取ります。 これを防ぐ 1 つの方法は、SCIM バルク ペイロードが API 呼び出しごとに最大 50 件のレコードを使用するように最適化されていることを確認することです。 この方法では、24 時間ごとに 300,000 件のレコードを送信できます。

バケット満杯の 500 応答コード

問題の説明

• SCIM クライアントは、HTTP 500 (内部サーバー エラー) を受け取り、"取り込まれたデータを格納するバケットがいっぱいです。同期サービスが取り込まれたデータを処理するのを待ってから、この要求を再試行してください"というメッセージが表示されます。
• このエラーは、大規模な HR データセットがプロビジョニング /bulkUpload エンドポイントに送信されるときに、初期同期または完全同期サイクル中に発生する可能性があります。

このエラーが表示される理由

• "バケット" は、プロビジョニング サービスが処理する前に受信 /bulkUpload ペイロードをバッファーするために使用される一時的なインジェスト キューです。
• 各 API 駆動型プロビジョニング ジョブには、専用のインジェスト キューがあります。
• プロビジョニング サービスは、キューに登録されたペイロードを継続的に処理し、処理されたデータを削除します。 このプロセスと削除のサイクルが遅れたり停止したりする場合、キューに置かれたデータはバケットがいっぱいになるまで蓄積される可能性があります。

考えられる原因と解決策

未承認 401 の応答コード

問題の説明

• プロビジョニング /bulkUpload API エンドポイントに要求を送信し、HTTP 401 (未承認) 応答コードを受信しました。 エラー コードには、「InvalidAuthenticationToken」と表示され、「アクセス トークンの有効期限が切れているか、まだ有効ではありません」というメッセージが表示されます。

考えられる原因

• アクセス トークンの有効期限が切れています。

解決方法:

• API クライアントの新しいアクセス トークンを生成します。

ジョブが検疫状態になる

問題の説明

• プロビジョニング アプリを開始したばかりで、アプリが検疫状態です。

考えられる原因

• ジョブを開始する前に、通知用メールの設定が行われていません。

解決策:[プロビジョニングの編集] メニュー項目に移動します。 [設定] の [エラーが発生したときにメール通知を送信します] の横にチェックボックスがあり、通知用メールを入力するフィールドがあります。 チェック ボックスをオンにして、メール アドレスを入力し、変更を保存してください。 [プロビジョニングの再開] をクリックして、ジョブを検疫から除外します。

ユーザーの作成 - 無効な UPN

問題の説明 ユーザー プロビジョニング エラーが発生しました。 プロビジョニング ログには、エラー コード AzureActiveDirectoryInvalidUserPrincipalName が表示されます。

解決方法:

1. [属性マッピングの編集] ページに移動します。
2. UserPrincipalName マッピングを選択し、RandomString 関数を使用するように更新します。
3. 次の式をコピーして式ボックスに貼り付けます。Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

この式は、Microsoft Entra ID で受け入れられる UPN 値に乱数を追加することで問題を修正します。

ユーザーの作成に失敗しました - 無効なドメイン

問題の説明 ユーザー プロビジョニング エラーが発生しました。 プロビジョニング ログには、domain does not exist というエラー メッセージが表示されます。

解決方法:

1. [属性マッピングの編集] ページに移動します。
2. UserPrincipalName マッピングを選択し、次の式をコピーして式の入力ボックスに貼り付けます。Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

この式は、Microsoft Entra ID で受け入れられる UPN 値に既定のドメインを追加することで問題を修正します。

既知の制限事項: 複数値アドレス、電子メール、電話番号

問題の説明

• 現在、API 駆動型のプロビジョニングでは、addresses値がemailsまたは他のphoneNumbers以外の値である場合、type、home、およびworkで SCIM の複数値属性は処理されません。
• この制限は、 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"]の値のみが処理されます。

Workaround

• API 駆動型のプロビジョニングで属性を処理する必要がある場合は、 work 型を使用してサポートされている値を送信します。

次のステップ

• インバウンド プロビジョニング API について詳細を確認する