キュー アイテムの保持ポリシー

概要

キュー アイテムを処理すると大量のトランザクションが生成され、Orchestrator のデータベースに急速にデータが溜まる可能性があります。保持ポリシーを使用すると、秩序立った方法でデータベースを解放できます。

保持ポリシーとは、一定期間後にデータベースからデータを削除するアクションを設定することで、データをオフロードする組み込み機能を確実に使用することに合意する契約です。保持ポリシーを利用することでデータベースが軽くなり、Cloud Orchestrator のパフォーマンスが向上します。

キュー アイテムの条件

指定したキューに対して設定した保持ポリシーは、以下の条件を同時に満たすすべてのキュー アイテムに適用されます。

• 完了したキュー アイテムの場合:
  • 最終ステータス (失敗、成功、破棄済み、リトライ済み、削除済み) にあること。
  • 保持期間である X 日間にわたって変更されていないこと。
• 未完了のキュー アイテムの場合
  • [新規] ステータスであること。
  • 保持期間である X 日間にわたって変更されていないこと。

延期されたキュー アイテム

処理中で延期されたキュー アイテムの保持期間は、延期日までの日数 + 保持期間に設定された日数で計算されます。

例

• キュー A に対して 30 日間の保持期間を持つ削除アクションを設定します。
• キュー A に属するキュー アイテム B が 10 日延期されます。

この場合、キュー アイテム B は 40 日後に削除されます。

中断されたジョブ

カスタム保持ポリシーは、中断されたジョブにリンクされているキュー アイテムには、そのジョブが完了ステートに移行するか削除またはアーカイブされるまで適用されません。

例

• キュー A に対して 30 日間の保持期間を持つ削除アクションを設定します。
• キュー A は、中断されたジョブ B にリンクされています。
• ジョブ B は、キュー A の保持期間を設定してから 10 日以内に再び有効化され、完了します。

この場合、キュー A に属するキュー アイテムは 40 日後に削除されます。

キュー アイテムが最後に変更された日時を特定する

キュー アイテムの検証アルゴリズムはすべてのキューを検索し、以下の 4 つのプロパティを上から順に検証して、条件に合致するキュー アイテムを決定します。

• 1 - 最終変更時刻
• 2 - 処理終了時刻
• 3 - 処理開始時刻
• 4 - 作成時刻

キュー アイテムに最終変更時刻の値 (1) がない、または値が null の場合は、アルゴリズムは処理終了時刻の値 (2) を調べます。処理終了時刻の値が null の場合、アルゴリズムは処理開始時刻の値 (3) を調べます。処理開始時刻の値が null の場合、アルゴリズムは作成時刻の値 (4) を検索し、最初に見つかった非 null 値に基づいてポリシーを適用します。

キュー アイテムが削除されるタイミングを特定する

保持期間はカレンダー日に基づいて計算されます。したがって、条件を満たしたキュー アイテムは X+1 カレンダー日に削除されます。ここでの X は保持期間、+1 はその直後のカレンダー日に削除ジョブが実行されることを示します。

ジョブは直後のカレンダー日の最初、つまり保持期間が終了した時点の数時間後に実行される可能性がありますのでご注意ください。

たとえば、保持期間を 1 日に設定するとします。

キュー アイテムの最終変更時刻が 10-06-2022 00:01:00 (カレンダー日の最初の 1 分) でも、10-06-2022 23:59:00 (カレンダー日の最後の 1 分) である場合でも、削除ジョブは 6 月 12 日 (6 月 10 日 + 1 日の保持期間 + 1 日後 = 6 月 12 日) に実行されます。

つまり、以下のことが分かります。

• 直後のカレンダー日にアーカイブを行うことで、少なくとも 1 カレンダー日 (保持期間) はキュー アイテムのデータが確実に保持されます。
• アイテムのアーカイブは、直後のカレンダー日の終わりまでに確実に完了することが目指されます。

ポリシーの種類

保持ポリシーの種類は以下のとおりです。

• The default policy for newly created queues - all transactions that are part of new queues are kept indefinetely in your configured database. This is the built-in option.
  重要:

  キュー アイテムをアーカイブまたは削除することを強くお勧めします。これにより、データベースのサイズが増加してパフォーマンスが低下するのを防ぐことができます。

• The default policy for existing queues - all existing transactions are are kept indefinetely in your configured database.
• The custom policy - all transactions are deleted or archived after a retention duration of your choosing, which is maximum 180 days, or kept indefinetely in your configured database. This option can be configured as instructed in the Configuring a custom retention policy section.
  • 完了したキュー アイテム:
    • 既定の期間は 30 日です。
    • 最長期間は 180 日です。
  • 未完了のキュー アイテム:
    • 既定の期間は 180 日です。
    • 最長期間は 540 日です。

重要: 既定の保持ポリシーは、テナント内のすべてのキューに適用されます。

ポリシーの結果

カスタム保持ポリシーのもたらす結果は次のとおりです。

• 有効なキュー アイテムが、ユーザーの構成したデータベース内に保持されます。
• 指定した期間より古い、有効なキュー アイテムが削除されます。
• 指定した期間より古い、有効なキュー アイテムが削除されますが、そのデータは既存のストレージ バケットにアーカイブされ、あとで参照できます。これにより、情報を失うことなく Orchestrator のデータベースをオフロードできます。
• キュー アイテムの一意の参照が保持されるので、ポリシーの適用後に検証が実行されたことが保証されます。
  注: 削除されたキュー アイテムの情報を含む Insights のダッシュボードでは、引き続き正しいデータが表示されます。

[キュー] ページ

保持ポリシーは [キュー] ページに即時で反映されません。

データの再計算は、キュー アイテムの作成、編集、削除、ステータス、リトライなどといったイベントによってトリガーされます。再計算後のリストには削除済みのキュー アイテムが含まれなくなります。

オフロードのメカニズム

サーバーがビジーでない時間帯にバックグラウンド ジョブが毎日実行され、すべての保持ポリシーに必要なアクションを実行します。

最初は大量のデータを処理する必要があります。運用パフォーマンスへの影響を回避するため、ジョブがデータのバックログを解析し正確なタイミングで処理を行えるようになるまでに 1 か月程度かかる可能性があります。

そのためポリシーが即時で適用されない可能性がありますが、処理は 1 か月程度で追い付きます。

たとえば、キューに 45 日の削除ポリシーを設定するとします。ポリシーはフェーズ 1 の終了時にアクティブ化されますが、45 日が経過したキュー アイテムがすべて確実に削除されるまでには約 1 か月かかります。これは、ジョブにデータのバックログを処理させるための初回例外です。

カスタム保持ポリシーを設定する

カスタム保持ポリシーを設定する手順は次のとおりです。

1. Orchestrator でテナント内の目的のフォルダーに移動します。
2. [キュー] ページを開きます。
3. 新しいキューを追加するには [キューを追加] をクリックします。既存のキューを編集するには、対象のキューのそれぞれで [その他のアクション] > [編集] をクリックします。[キューを作成/更新] ページが開きます。
4. [保持ポリシー] セクションで、[アクション] ドロップダウン メニューからポリシーの結果を選択します。

   完了したキュー アイテムと未完了のキュー アイテムに対して、ポリシーの結果と保持期間を別々に設定できます。

   キュー アイテムを削除して情報を保持するには、「キュー アイテムをアーカイブする」の手順をご覧ください。

   キュー アイテムを完全に削除するには、「キュー アイテムを削除する」の手順をご覧ください。

   キュー アイテムをデータベース内に無期限に保持するには、「キュー アイテムを保持する」の手順をご覧ください。

キュー アイテムをアーカイブする

キュー アイテムのデータを失わずに Orchestrator のデータベースから情報をオフロードする必要がある場合は、キュー アイテムをアーカイブします。

前提条件: アーカイブされるキュー アイテムを保存するストレージ バケットが必要です。

1. [アクション] ドロップダウン メニューから [アーカイブ] を選択します。
2. 完了したキュー アイテムと未完了のキュー アイテムの両方の保持期間を選択します。

   完了したキュー アイテムには、1 から 180 の間で値を選択できます。既定値は 30 です。

   未完了のキュー アイテムには、30 から 540 の間で値を選択できます。既定値は 180 です。

   この期間の終了時には、それまでの間に更新されていないキュー アイテム (キュー アイテム イベントやコメントを含む) はすべて削除され、それらの情報は対象のバケットに保存されます。

3. アーカイブされるアイテムを保存する対象のバケットを選択します。

アーカイブされた情報を取得するには、関連するストレージ バケットのアーカイブ ファイルにアクセスします。

注:

注 1: Orchestrator のストレージ バケット、外部のストレージ バケットへのリンク、またはマシン上の FileSystem バケットを使用できます。

注 2: アーカイブによってストレージ バケットにアイテムを追加できるよう、使用するバケットは読み取り専用にしないでください。

注 3: 同じストレージ バケットを使用して異なるキューのキュー アイテムをアーカイブできます。

注 4: このフィールドは [アーカイブ] オプションでのみ使用できます。

注 5: 暗号化されたキュー アイテムの固有データと出力データはストレージ バケット内では閲覧可能な状態になります。アーカイブ操作ではデータの取得時にデータを復号して対象のストレージにエクスポートするからです。

注 6: 正常に完了したアーカイブ操作は [テナント] > [監査] ページに記録され、[アクション] の種類が [アーカイブ] であることで識別できます。

注 7: エラーによってアーカイブ操作が中断された場合、エラーを修正するためにアラートで通知されます。アーカイブ操作は、削除ジョブの次回実行時 (次のカレンダー日) にリトライされます。アーカイブのリトライが成功するまで、影響を受けるキュー アイテムを表示またはアクセスすることはできません。

出力をアーカイブする

.zip ファイル

キュー アイテムをアーカイブすると、保持期間が終わった時点で .zip ファイルが作成されます。パスは次のとおりです。

「Archive/Queues/Queue-{queue_key}/{archiving_operation_date}-{archiving_operation_timestamp}.zip」それぞれ、次の値が使用されます。

• {queue_key} - キュー アイテムを含むキューの一意の識別子です。
• {archiving_operation_date} - アーカイブが生成された UTC 日付 (yyyy-MM-dd の形式) です。
• {archiving_operation_timestamp} - アーカイブが生成された UTC 時刻 (HH-mm-ss-fff の形式) です。
  たとえば、アーカイブ ファイルの名前は Archive/Queues/Queue-1d1ad84a-a06c-437e-974d-696ae66e47c2/2022-05-26-03-00-08-496.zip のようになります。

.csv ファイル

ファイルを展開すると、.zip ファイルは同じ名前構文を持つ .csv ファイルを表示します。ファイル名は次のとおりです。

「Queue-{queue_key}-{archiving_operation_date}-{archiving_operation_timestamp}.csv」

.csv ファイル内のアーカイブされたキュー アイテムに関する情報について詳しくは、以下の画像でご確認ください。

図 1. CSV ファイル

Metadata.json ファイル

.json ファイルには、コンテナー キューに関する詳細が含まれており、コンテナー キューを容易に特定できます。

データ ボリュームが大きい場合

キューが多数のトランザクションを処理していた場合、キュー アイテムはバッチでアーカイブされます。この場合、各バッチの .zip ファイル名の {archiving-operation-timestamp} の値はバッチ アーカイブの作成時刻に応じて異なります。

キュー アイテムを削除する

処理済みのキュー アイテムのデータを不要と判断した場合は、すべての情報を Orchestrator のデータベースから削除できます。

1. [アクション] ドロップダウン メニューから [削除] を選択します。
2. 完了したキュー アイテムと未完了のキュー アイテムの両方の保持期間を選択します。

   完了したキュー アイテムには、1 から 180 の間で値を選択できます。既定値は 30 です。

   未完了のキュー アイテムには、30 から 540 の間で値を選択できます。既定値は 180 です。

   この期間の終了時には、それまでの間に更新されていないキュー アイテム (キュー アイテム イベントやコメントを含む) が完全に削除されます。

キュー アイテムを保持する

If you want to keep processed queue items data for an indefinite time, select Keep from the Action dropdown menu.

All queue items, be they in a final or in a non-final status, are kept indefinitely in your configured database. This includes queue item events and comments.

キューの保持ポリシーの API

保持ポリシーをクライアントに組み込むには、Swagger ファイルで QueueRetention API の専用のエンドポイントを使用します。エンドポイントは以下のとおりです。

• GET /odata/QueueRetention - すべてのアクティブなポリシーのリストを返します。ポリシーのアクション、保持期間 (日)、ポリシーが適用されるキューの ID などの情報が含まれます。
• GET /odata/QueueRetention({key}) - 指定したキューのポリシーの情報を返します。
• PUT /odata/QueueRetention({key}) - 指定したキューのポリシーの情報を更新します。
• DELETE /odata/QueueRetention({key}) - 指定したキュー ポリシーを、既定のポリシー (30 日間の保持 + 削除) にリセットします。

注: 保持ポリシー機能の導入前に作成されたキューに対して DELETE エンドポイントを呼び出した場合、組み込み保持ポリシー (30 日間の保持 + 削除) が適用されます。詳しくは、『UiPath Orchestrator API ガイド』をご覧ください。

ポリシーの追跡列と監査

カスタム保持ポリシーが設定されているキューを簡単に特定するには、[キュー] ページの [列] ドロップダウン リストで [保持期間後のアクション] と [保持期間 (日)] 列のチェックボックスをオンにし、これらの列を有効化します。

[保持期間後のアクション] 列にはポリシーの結果が表示され、[保持期間 (日)] 列にはポリシーが適用されるまでの残り時間が表示されます。

図 2. [保持期間後のアクション] 列

前述のとおり、新しく作成されるキューには 30 日間の保持ポリシーが適用されます。ただし、既定のポリシーが設定されているキューを識別する際には、保持期間の値を識別基準として常に信頼することはできません。たとえば、カスタム保持期間を 55 日間に設定し、その後期間を 30 日間に更新した場合、更新後のポリシーは既定のポリシーではありません。各シナリオに既定のポリシーが設定されているかどうかを確認するには、[監査] ページをご覧ください。