ベストプラクティス
Retrieve Candidates APIと連携する際は、次のベストプラクティスに従ってください。
法的注意
このAPIとそのドキュメントを使用して連携を構築すると、APIに関する追加の利用規約およびガイドラインに同意したことになります。
単一プロセスのポーリングを実装する
#fetchAssetsのポーリングプロセスは一度に1つだけ実行します。これにより、別のプロセスがまだ保存していないバッチを確認済みにしてしまうことを防げます。
過去のデータを復旧する
#データ損失の後などにアセットデータを再取得するには、次の方法に従います。
| ベストプラクティス | 説明 |
|---|---|
| 適切なクエリを使用する | 確認済みのアセットを再取得するには、assetsByTimeRangeを呼び出します。新しいアセットを取得するには、fetchAssetsを使用します。 |
| 期間ごとのバッチ処理 | 1日ずつなど、一度に1つの期間だけをリクエストし、復旧が必要な範囲に限定します。開始日または終了日を省略すると、クエリはそれぞれ最も古い確認日または最も新しい確認日を使用します。 |
| カーソルページネーション | 次のページを取得するには、pageInfo.endCursorをafterとして渡します。pageInfo.hasNextPageがfalseになるまで繰り返します。GraphQL Cursor Connections Specification (新しいウィンドウで開きます)をご覧ください。 |
| 進捗の追跡 | 復旧した期間の記録をローカルに保持し、中断後に再開できるようにします。 |
ポーリングパターンを実装する
#新しいアセットを取得するには、次のパターンを使用します。
| ベストプラクティス | 説明 |
|---|---|
| 定期的なポーリング | 5分ごとにfetchAssetsを呼び出して、新しいアセットを確認します。アセットの量が少ない場合は、ポーリングの頻度を下げてもかまいません。 |
| 連続ポーリング | fetchAssetsが空でないトークンを返した場合、ほかにもアセットがある可能性があります。バッチを処理した後、そのトークンを渡してすぐにfetchAssetsを再度呼び出します。トークンがnullまたは空になるまで繰り返します。これらの呼び出しの間は、ポーリング間隔を待つ必要はありません。 |
| サイクルの終了 | トークンがnullまたは空の場合、Indeedが利用可能なすべてのアセットを配信済みであることを意味します。次のポーリングサイクルを開始する前に、ポーリング間隔を待ちます。 |
| 確認の管理 | fetchAssetsにトークンを渡すと、そのバッチが確認済みになり、fetchAssetsは同じバッチを再び返しません。トークンを渡す前に、バッチ内のすべてのアセットを保存するか、再試行用に確実に記録してください。 |
アセットとワークフローを管理する
#- 確認する前に保存する: トークンを渡す前に、バッチ内のすべてのアセットを保存するか、再試行用に確実に記録します。ポーリングパターンを実装するをご覧ください。
- 冪等な処理: 同じアセットを再度受信した場合は、各アセットの
idを使用して重複をスキップします。重複を常に認識できるように、すべてのアセットのidを無期限に保持します。 - アセットタイプを処理する:
AtsSyncCandidateSyncAssetインターフェースでは、既知のタイプに対して... onのインラインフラグメントを使用し、未知のタイプは無視します。1つのバッチに、Smart SourcingとSmart Screeningの両方のアセットが含まれる場合があり、Indeedは今後もアセットタイプを追加します。 - 更新を順番どおりに適用する: Smart Screeningの更新は、更新が発生した時刻を示す
AtsSyncCandidateSyncSmartScreeningUpdate.createdAtで順序付けします。アセットが利用可能になった時刻を示すAtsSyncCandidateSyncAssetMetadata.stagedAtでは順序付けしないでください。更新を順番どおりに適用しないと、古いデータで新しいデータを上書きする可能性があります。
ファイルとファイルのダウンロードを処理する
#- すぐにダウンロードする: ファイルのURLは有効期間の短い署名付きURL (新しいウィンドウで開きます)です。アセットを受信したら、すぐに各ファイルをダウンロードします。
- URLではなくファイルを保存する: 署名付きURLではなく、各ファイルを自社のシステムに保存します。バッチを確認済みにする前にURLの有効期限が切れた場合は、そのバッチのトークンを渡さずに
fetchAssetsを再度呼び出して、アセットを再取得します。すでにバッチを確認済みにしている場合は、assetsByTimeRangeを呼び出すか、アセットのidを指定してnodeクエリを使用します。 - ファイルのメタデータを使用する:
nameフィールドとcontentTypeフィールドを使用して、各ファイルを正しく保存して表示します。 - 並列ダウンロード: 複数のファイルを同時にダウンロードして、処理時間を短縮します。
エラーを処理する
#- 指数バックオフ: 一時的な失敗は、間隔を徐々に長くし、ランダムなジッターを加えて再試行します。再試行に失敗した場合は、ポーリングサイクルを停止し、次の定期的なポーリングで再開します。バッチ内のすべてのアセットを保存または確実に記録していない場合は、そのバッチのトークンを渡さないでください。トークンを渡さずに
fetchAssetsを呼び出して、バッチを再取得します。 - 部分的な失敗の処理: 一部のアセットは保存され、他のアセットは失敗するバッチに備えます。クラッシュや再起動で記録が失われないように、すべてのアセットを保存するか、再試行用に確実に記録するまで、バッチを確認済みにしないでください。バッチを確認済みにした後に、記録したアセットを再試行するには、
assetsByTimeRangeを呼び出すか、アセットのidを指定してnodeクエリを使用します。fetchAssetsは、そのアセットを再び返しません。 - エラーのあるアセットを確認済みにしない: レスポンスにアセットに関するGraphQLエラーが含まれている場合は、ほかのアセットを保存済みであっても、そのバッチのトークンを渡さないでください。次の定期的なポーリングで
fetchAssetsを再度呼び出して、バッチを再取得します。 - 堅牢なエラー処理: すべてのレスポンスで、HTTPエラーとGraphQLエラーの両方を確認します。OAuthエラーのトラブルシューティングとGraphQLエラーのトラブルシューティングをご覧ください。
- 適切なタイムアウトの設定: 接続と読み取りに適切なタイムアウトを設定します。
パフォーマンスを最適化する
#- バッチサイズ: タイムアウトの範囲内でシステムが保存できる件数を
limitに設定します。バッチを小さくすると、失敗後にやり直す作業が減ります。 - キャッシュ: 採用企業の登録IDとその
employerIdentifierの値は、繰り返し検索せずにキャッシュします。値が古くならないように、キャッシュの保持期間は長くても数時間にします。
テストと監視
#- テストアセット:
stageAssetsを呼び出してテストアセットを作成し、fetchAssetsで取得します。metadata.stagedTestフラグを確認して、テストアセットと実際の候補者を区別します。Indeedは14日後にテストアセットを削除します。 - エッジケース: 混在したバッチ、未知のアセットタイプ、任意フィールドの欠落、順序が前後したSmart Screeningの更新をテストします。
- エラーシナリオ: タイムアウト、ネットワーク障害、期限切 れの署名付きURL、バッチの保存から確認までの間に発生する障害をテストします。
- 監視とアラート: エラー率、レスポンス時間、ポーリングサイクルごとのアセット数、最後に成功したポーリングからの経過時間、サーキットブレーカーの状態を追跡します。アラートを設定します。
関連項目
#ガイド
#- IndeedリソースID(IRI) —
nodeクエリでIDからエンティティを検索します。 - Retrieve Candidates APIガイド — アセットタイプ、リクエスト、レスポンスについて説明します。
- Retrieve Candidates API連携ガイド — APIと連携する手順を説明します。
- GraphQLエラーのトラブルシューティング — APIが返すGraphQLエラーを診断します。
- OAuthエラーのトラブルシューティング — Indeed APIにアクセスする前に発生するOAuthエラーをトラブルシューティングします。
リファレンス
#- Download and upload objects with presigned URLs (新しいウィンドウで開きます) — 署名付きURLのしくみについて説明します。
- GraphQL Cursor Connections Specification (新しいウィンドウで開きます) — カーソルベースのクエリのページネーションモデルです。
GraphQL APIリファレンス
#assetsByTimeRange— 指定した時間範囲の確認済みアセットを取得します。AtsSyncCandidateSyncAsset— すべての候補者アセットタイプが実装するインターフェースです。AtsSyncCandidateSyncAssetMetadata— 各アセットのメタデータです。employerIdentifier、stagedAt、stagedTestが含まれます。AtsSyncCandidateSyncSmartScreeningUpdate— Smart Screeningの更新です。createdAtが含まれます。EmployerRegistration— 採用企業の登録とそのIDです。fetchAssets— 未確認のアセットを取得します。前のバッチを確認済みにするには、トークンを渡します。PageInfo— ページネーションの詳細です。endCursorとhasNextPageが含まれます。stageAssets— サンドボックスでのテスト用に、テストアセットを作成します。モックアセットは、ステージングから14日後に削除されます。