using-salesforce-archive

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 の構築、アーカイブデータに対する Flow の生成（ArchiveActivity は Flow からクエリできません。Gotchas を参照）、アドオンと無関係な汎用バックアップ／エクスポートツール。

---

必要な入力

操作を行う前に、次の情報を収集するか推測してください。

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

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

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

---

権限

すべてのオペレーションでは、まず組織で Salesforce Archive が有効になっている必要があります（hasTrustedServicesArchive = OrgPermissions.TrustedServicesArchive || TrustedServicesArchiveBt）。この組織レベルの条件に加えて、各機能はそれぞれ異なるユーザー権限によって制限されます。ユーザーに許可されていない呼び出しは「not permitted」エラーで失敗します。エラーに対応する不足権限を以下で確認してください。

オペレーション	必要なユーザー権限
search-archived-records、get-search-archived-records-next-page	ViewSearchPage（Archive Search）— Connect の検索エンドポイントはグローバル検索の経路を実行します。この経路は Archive Search によって制限され、ViewArchivedRecords ではありません
search-archived-records-with-sharing-rules（Agentforce）	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）

信頼できる情報源: trusted-services-archive-connect-impl 内の Connect API リソースクラス → TrustedServicesArchiveSdkImpl のガード → TrustedServicesArchive.accessChecks.xml。search-archived-records は performArchiverGlobalSearch（canRunArchiveSearch = ViewSearchPage によって制限される）を経由します。別の Apex-SDK の searchArchivedRecords() メソッドは ViewArchivedRecords によって制限されますが、Connect API の検索エンドポイントでは使用されません。

---

ワークフロー

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

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

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

3. 呼び出しを構築して送信する — 契約に厳密に従ってください。検索では sobjectName と1つ以上のフィルターを指定します。日付でフィルタリングする場合は、完全な ISO-8601 日時を含む {field, from, to} の配列 dateRanges（複数形）を使います。

4. 適切なシグナルに基づいて分岐する — 操作によっては HTTP 201 と、本文レベルの成功フラグ（body.statusCode、body.isSuccess）が返されます。操作ごとにどのシグナルを判断基準にするかは 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 が一致しない場合、ログは返されません。
非推奨の検索機能は使用しないでください	global-search-by-id、get-global-search-results、view-archived-records は後継機能がないまま非推奨となっており、現在は 500 エラーを返します。代わりに search-archived-records（および next-page）を使ってください。
除外されたオブジェクトは取得できません	Feed、History、Relation、Share は検索できません。また、この API では Files／Attachments を取得できないため、取得できると案内しないでください。
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（Agentforce）のフィルターを配列として扱う	filtersJson は JSON でエンコードされたオブジェクトマップ {"Field":"Value"} である必要があります。{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 があると期待する	ArchiveActivity は Flow に対応していません（isProcessEnabled=false）。SOQL／Connect／Reports を使用してください。
アンアーカイブの上限に達する	アンアーカイブ処理では、1 リクエストあたり最大 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	エンドツーエンドの監視フローに従う場合。失敗中／処理中のジョブを見つけ、そのログをダウンロードします