platform-trust-archive-manage

Salesforce Archive

Connect API とジョブメタデータオブジェクト ArchiveActivity を通じて、Salesforce Archive（Trusted Services Archive とも呼ばれます）を操作します。このスキルでは、アーカイブ済みレコードの検索と復元、アナライザーの実行、RTBF による消去と PII のマスキング、ストレージの確認、そして特に見落とされがちな、ArchiveActivity からアーカイブジョブのステータスを読み取り、ジョブの Id と Type を使ってログをダウンロードする方法を扱います。

範囲

• 対象範囲：/platform/data-resilience/archive/ 配下の Archive Connect API 操作の呼び出し、SOQL／Connect による ArchiveActivity オブジェクトへのクエリ、ジョブの ArchiveActivity レコードとログのダウンロードエンドポイントとの関連付け、各非同期操作後の検証パターン。
• 対象外：アーカイブポリシー／ArchivePolicyDefinition メタデータの定義、UI の構築、アーカイブデータに対するフローの生成（ArchiveActivity はフローからクエリできません。注意事項を参照）、アドオンとは無関係な汎用バックアップ／エクスポートツール。

---

必須入力

操作を行う前に、以下を収集または推定してください。

• 操作の目的：検索（アーカイブ済みレコードの表示にも使用）、アーカイブ解除、分析、マスキング、RTBF、ストレージ確認、またはジョブのステータス／ログの検索。
• 対象の sObject（sobjectName）：検索とアーカイブ解除に必要です。
• フィルター：検索とアーカイブ解除には、sobjectName と少なくとも 1 つのフィルターが必要です。
• ログのダウンロードの場合：完了済みでログを生成するジョブの requestId（ArchiveActivity Id。8qv… プレフィックス）と、reportType ＝そのアクティビティの Type。

前提条件（呼び出しで許可されていない旨のエラーが返された場合は、確認するかユーザーに伝えてください）：

• 組織で Salesforce Archive が有効になっている必要があります。すべての操作は、まずこの条件によって制限されます。
• 組織の条件に加えて、各操作には特定のユーザー権限が必要です。以下の「権限」表を参照してください。「アーカイブ管理者」という単一のロールはなく、アクセス権は機能ごとに設定されます。

---

権限

すべての操作では、まず組織で Salesforce Archive が有効になっている必要があります。この組織の条件に加えて、各機能はそれぞれ異なるユーザー権限によって制限されます。ユーザーに権限がない呼び出しは「許可されていません」というエラーで失敗します。エラーと以下の不足している権限を照合してください。

操作	必要なユーザー権限
search-archived-records、get-search-archived-records-next-page	ViewSearchPage（Archive Search）— ViewArchivedRecords ではありません
search-archived-records-with-sharing-rules	ViewArchivedRecords
unarchive-records	UnarchiveSdk
forget-archived-records（RTBF）+ get-rtbf-status	Rtbf
mask-archived-records + get-masking-status	Rtbf（マスキングにも同じ Rtbf 権限が適用されます。別の権限ではありません）
run-analyzer、get-analyzer-report、get-archive-storage-used	ArchiveAnalyzer
get-execution-details-stream-url、get-failed-records-stream-url	ViewActivitiesPage（Archive Activities）

---

ワークフロー

各タスク内の手順は順番に実行します。該当する領域に初めて取り組むときは、参照ファイルを読み込んでください。

1. 操作を特定し、仕様を読む — Archive API についての一般知識に頼らないでください。仕様には分かりにくい点があります。各 Archive Connect API 操作の正確なリクエスト／レスポンス形式、必須入力、操作ごとの注意点を確認するため、呼び出しを組み立てる前に references/connect-api-operations.md を読み込んでください（例：dateRanges は複数形であること、isSuccess フラグと HTTP ステータスの違い、url: null はログがないことを意味する点）。

2. ジョブのステータス／監視の場合は、データモデルを読む — タスクにアーカイブジョブ、失敗、進捗、件数、ログが関係する場合は、ArchiveActivity のフィールドリファレンスと Connect API との連携方法を確認するため、references/archive-activity-entity.md を読み込んでください。ArchiveActivity は SOQL または Connect 経由でクエリしてください。Flow は使わないでください。失敗中／進行中のジョブを見つけてから実行詳細ログと失敗レコードログを取得する、最初から最後までの例については、examples/monitor-failed-jobs.md を読み込んでください。

3. 呼び出しを組み立てて送信する — すべての操作は {method, path, body} 形式の REST 呼び出しです。環境で利用できる Connect／REST API ツール（Connect／REST API を呼び出す MCP サーバー、sf CLI、または任意の REST クライアント）で送信してください。重要なパス規則が 2 つあります（各操作の詳細な仕様は references/connect-api-operations.md を参照してください）。

   • このスキルに記載されている操作名は URL パスではありません。 search-archived-records、unarchive-records などはラベルです。パスには絶対に使用しないでください。以下に記載する短い固定パス（それぞれベースパス /platform/data-resilience/archive からの相対パス）を使用します。操作名をパスのセグメントとして送信すると（例：/…/archive/search-archived-records）、404 が返されます。
   • パスは /platform/data-resilience/archive/… までです。/connect セグメントはありません。Connect API であっても同様です。ここで 404／NOT_FOUND が返された場合、パスが間違っているのであり、Archive が無効という意味ではありません。アドオンが存在しないと判断する前に、パスを修正してください。

   操作	メソッド + パス	備考
   search-archived-records	POST /search	sobjectName と 1 つ以上のフィルターが必要です
   次の検索ページ	GET /search/next/{scrollId}	scroll_id == "-1" になったら終了します
   共有ルールを適用した検索	POST /search/with-sharing-rules	filtersJson オブジェクトマップを使用します
   unarchive-records	POST /unarchive	sobjectName とフィルターが必要です
   アナライザーの実行／レポート	POST /analyzer/run · GET /analyzer/report
   忘却／RTBF + ステータス	POST /rtbf · GET /rtbf/{requestId}
   マスキング + ステータス	POST /mask · GET /mask/{requestId}
   使用済みストレージ	GET /storage/archive-used
   実行詳細／失敗レコードのログ	GET /log/execution-details-stream-url · GET /log/failed-records-stream-url	クエリパラメーター requestId、reportType

   sf CLI を使用する場合は、パスの先頭に /services/data/v67.0 を付けてください。一部の MCP／REST ツールはパスのバージョンを自動で付加するため、ベースパスのみを受け付けます（ツールによって異なります。リファレンスを参照してください）。続いて仕様に従ってください。検索では sobjectName と 1 つ以上のフィルターを指定し、日付で絞り込む場合は、完全な ISO-8601 形式の日時を指定した {field, from, to} の配列を複数形の dateRanges として渡します。

4. 適切なシグナルに基づいて判断する — 一部の操作は、本文レベルの成功フラグ（body.statusCode、body.isSuccess）とともに HTTP 201 を返します。操作ごとにどのシグナルを信頼すべきかは references/connect-api-operations.md を読んで確認してください。HTTP ステータスだけで成功と判断しないでください。

5. 書き込みのたびに検証する — 状態を再読み込みし、変更が反映されたことを確認してください（下記の「書き込み後の検証」表を参照）。非同期操作（アナライザー、RTBF、マスキング）はリクエスト ID を返すため、ポーリングが必要です。

---

書き込み後の検証

この操作の後	確認方法
run-analyzer	レポートが生成されるまで get-analyzer-report をポーリングします
unarchive-records	search-archived-records を再実行し、レコードがアーカイブから移動したことを確認します
forget-archived-records（RTBF）	返された request_id を使って get-rtbf-status をポーリングします
mask-archived-records	返された request_id を使って get-masking-status をポーリングします

---

ルール／制約

制約	理由
検索とアーカイブ解除には sobjectName と少なくとも1つのフィルターが必要です	フィルターのないリクエストは「Search must be based on at least 1 field」で拒否されます。オブジェクト全体を対象とする操作は許可されません。
日付フィルターには完全な ISO-8601 形式の日時（2020-01-01T00:00:00Z）を指定する必要があります	日付のみの値（2020-01-01）は、フィールドの型が xsd:dateTime のため、400 JSON_PARSER_ERROR を返します。
検索では dateRanges（複数形の配列）を使い、アーカイブ解除では dateRange（単数形）を使います	これらは2つのエンドポイントで実際に異なるフィールドです。誤った形式を使うと、フィルターが黙って無視されるか、400エラーになります。
scroll_id == "-1" になったらページネーションを停止します	"-1" を指定して get-search-archived-records-next-page を呼び出すと、500エラーが返されます。
ログのダウンロードでは、requestId に実在する ArchiveActivity の Id を、reportType にそのアクティビティの Type を指定する必要があります	バックエンドはアクティビティレコードを使ってログを解決します。一致しない reportType を指定すると、ログは返されません。
除外されたオブジェクトは取得できません	Feed、History、Relation、Share は検索できません。また、Files／Attachments はこの API では取得できません。これらを取得できると約束しないでください。
ArchiveActivity は Flow ではなく、SOQL／Connect 経由でクエリします	ArchiveActivity は isProcessEnabled=false のため、そのオブジェクトを対象とする Flow の「Get Records」要素は「You can't get ArchiveActivity records in a flow.」で失敗します。

---

注意点

問題	解決方法
HTTP 201 を成功として扱う	いくつかの操作は、本文レベルの結果とともに201を返します。HTTPコードではなく、body.statusCode（検索）または body.isSuccess（with-sharing-rules）に基づいて分岐してください。
run-analyzer.isRunning を判定シグナルとして使う	これは常に null です。このエンドポイントが設定するのは message のみです。代わりに get-analyzer-report をポーリングして完了を確認してください。
search-archived-records-with-sharing-rules のフィルターを配列として扱う	filtersJson は、{field,value} の配列ではなく、JSON でエンコードしたオブジェクトマップ {"Field":"Value"} にする必要があります。配列形式では isSuccess:false "No valid filters provided" が返されます。
ステータスが201なのでログの url が存在すると判断する	get-*-stream-url は {url} を返します。url: null はログが解決されなかったことを意味します。必ず url != null を確認してください。
get-archive-storage-used の読み違い	usedStorage[]／availableStorage[] は、インデックスが対応する並列配列です。インデックス0＝組織の DATA、1＝組織の FILE、2＝アーカイブの RECORDS、3＝アーカイブの FILE です。availableStorage[2]／[3] は常に0（アーカイブ層は使用量の計測対象外）です。これは「未追跡」を意味し、「容量不足」ではありません。
Flow に ArchiveActivity があると想定する	Flow は有効になっていません（isProcessEnabled=false）。SOQL／Connect／Reports を使ってください。
アーカイブ解除の上限に達する	アーカイブ解除では、リクエストごとに一致するレコードを最大1000件、組織ごとに1時間あたり最大50件のリクエストを処理します。また、一致した各レコードのアーカイブ済み階層全体が復元されます。
RTBF／マスキングの上限	criteria は最大10エントリ（オブジェクトごとに1つ）、ルートレコードは1日あたり最大10,000件（RTBF とマスキングで共有）です。マスキングは取り消せません。RTBF とマスキングは、どちらも同じ Rtbf ユーザー権限によって制限されます。

---

出力に関する想定

これはナレッジ／API スキルです。API 呼び出しとその解釈結果、および ArchiveActivity に対する SOQL を生成します。デプロイ可能なメタデータは生成しません。タスクごとの成果物は、正しい操作の呼び出し、適切な成功シグナルに基づく分岐、書き込み後の検証による確認です。

---

リファレンスファイル一覧

ファイル	読むタイミング
references/connect-api-operations.md	Archive Connect API の呼び出しを構築する前にお読みください。操作ごとの契約、成功を示すシグナル、制限事項をすべて記載しています
references/archive-activity-entity.md	ジョブのステータス／失敗／進捗／ログに関するタスクでお読みください。ArchiveActivity のフィールドリファレンスと、ログダウンロードエンドポイントとの関連を記載しています
examples/monitor-failed-jobs.md	エンドツーエンドの監視フローを確認する際にお読みください。失敗中または進行中のジョブを見つけ、そのログをダウンロードします