platform-sandbox-configure

Sandbox のライフサイクル管理

Connect REST API を通じて Salesforce sandbox 環境を管理します。インベントリの一覧表示、完了した更新の有効化または破棄、sandbox の作成と更新、sandbox の完全削除を行います。

このスキルを使用するタスク

次の作業には platform-sandbox-configure を使用してください。

• すべての sandbox を一覧表示または取得する（GET /sandbox/reports）
• sandbox の名前または ID（07E で始まる）を指定して、詳細またはステータスを取得する
• ライセンスの使用状況と、ライセンスの種類ごとの残りの容量を確認する（GET /sandbox/licenses）
• 更新完了後に sandbox を有効化する（更新を適用する）
• 完了した更新を破棄する（既存の sandbox データは変更せず維持する）
• ライセンスを解放するために sandbox を完全に削除する
• 有効化または削除が完了したことを確認する
• 新しい sandbox を作成する（Developer、Developer Pro、Partial Copy、Full）
• 最新の本番データで既存の sandbox を更新する

ユーザーが次の作業を行う場合は、別のスキルに委任してください。

• sandbox のクローン作成 → Tooling API（SandboxInfo sObject）
• SOP からコピー後の自動化用 JSON 設定を生成する → automation-sandbox-post-copy-config-generate
• コピー後の自動化用 JSON 設定を sandbox に適用または実行する → automation-sandbox-post-copy-configure

---

ヘルプ（対話型メニュー）

ユーザーが sandbox -help または sandbox help と入力した場合は、以下の番号付き操作一覧だけをテキストメッセージで返してください。API やツールは呼び出さず、メニューを表示して、ユーザーが番号で返信するのを待ってください。

エージェントは、次の Markdown をそのまま返す必要があります（コードブロックに入れず、箇条書きリストとして直接表示してください）。

Sandbox のライフサイクル管理

1. インベントリと詳細

• a. すべての sandbox を一覧表示 — 名前、種類、ステータス、ID
• b. 詳細を取得（名前で指定） — ステータス、ライセンス、設定
• c. 詳細を取得（ID で指定） — 07E ID を直接指定
• d. ライセンス使用状況を確認 — ライセンスの種類ごとの利用可能数と使用数

2. 作成と更新

• a. 新しい sandbox を作成 — Dev、Dev Pro、Partial、Full
• b. sandbox を更新 — 最新の本番データ

3. 有効化、破棄、削除

• a. sandbox を有効化 — 完了した更新を適用
• b. 更新を破棄 — 更新を取り消し、既存データを維持
• c. sandbox を削除 — 完全に削除

4. 確認と監視

• a. 有効化のステータスを確認 — 有効化が完了したか確認
• b. 削除のステータスを確認 — 削除が完了したか確認

5. コピー後の自動化

• a. コピー後の自動化用 JSON 設定を作成 — SOP から設定を生成
• b. コピー後の自動化を実行 — JSON 設定を sandbox に適用

コード（例：「3a」）で返信するか、必要な作業を説明してください。

ユーザーの返信後、必要な入力を尋ねてください。

選択	追加の質問
1a	入力は不要です — すぐに実行します
1b	「sandbox の名前は何ですか？」
1c	「sandbox の ID は何ですか？（07E で始まります）」
1d	入力は不要です — すぐに実行します
2a	まず GET /sandbox/licenses（セクション 9）を呼び出し、利用可能数と使用数を表示します。その後、名前とライセンスの種類（Developer、Developer_Pro、Partial_Copy、Full）を尋ねてください
2b	まず GET /sandbox/reports（セクション 1）を呼び出し、更新可能な sandbox（isPendingActivation: false）を一覧表示します。その後、更新する sandbox を尋ねてください
3a	「どの sandbox ですか？名前または 07E ID を指定してください。」
3b	「どの sandbox ですか？名前または 07E ID を指定してください。」
3c	「どの sandbox ですか？名前または 07E ID を指定してください。」
4a	「どの sandbox を有効化しましたか？名前または 07E ID を指定してください。」
4b	「どの sandbox を削除しましたか？名前または 07E ID を指定してください。」
5a	「コピー後の設定ジェネレーターに委任します。SOP（ファイル、テキスト、またはスクリーンショット）を共有してください。」
5b	「コピー後の設定ランナーに委任します。設定 JSON ファイルと対象の sandbox を共有してください。」

以下の該当する操作を実行してください。例外： 5a と 5b は委任します。5a → automation-sandbox-post-copy-config-generate、5b → automation-sandbox-post-copy-configure。このスキルではコピー後の自動化を実行できません。設定を直接生成または適用しないでください。

---

API ベース

重要： このスキルでサンドボックスを操作する場合は、Connect REST API を使用してください。探索方法は 2 つあります。

• 名前で検索： GET /sandbox/reports を呼び出してすべてのサンドボックスを一覧表示し、sandboxName が一致するものを探します。
• ID（07E プレフィックス）で検索： GET /sandbox/sandboxes/{sandboxId} を直接呼び出します。/sandbox/reports は呼び出さないでください。

どちらの方法でも、すべてのライフサイクル変更操作に必要な sandboxId（プレフィックスは 07E）を含むサンドボックスレコードが返されます。

sf api request rest "/services/data/v66.0/sandbox/reports" --method GET

レスポンスの完全な形式については、references/api-response-shapes.md を参照してください。

重要： 検索に Tooling API（SandboxInfo／SandboxProcess）を使用しないでください。変更エンドポイントには Connect REST API の sandboxId（07E）が必要であり、SandboxInfo.Id（0GQ）や SandboxProcess.Id（0GR）ではありません。

ライフサイクルに関する読み取り（ステータス、インベントリ、詳細、ライセンス、アクティベーション待ち）には、SOQL／run_soql_query／sf data query を絶対に使用しないでください。 このデータは Connect REST API にのみ存在し、返す SObject はありません。（SandboxInfo に対する sf data query --use-tooling-api は、作成／更新の変更には引き続き有効ですが、ライフサイクルの読み取りには使用できません。）

API の結果は、返されたとおりに正確に報告してください。エラーや原因を決してでっち上げないでください。 count: 0 は成功した結果（サンドボックスが存在しない）です。not_found と記録し、失敗と解釈したり、SOQL で再試行したりしないでください。API がエラーを返した場合は、エラー本文をそのまま記録してください。理由を推測してはいけません（例：「スクラッチ組織に違いない」）。このエンドポイントは組織のエディション／種類を報告しないため、そのような推測はすべて捏造です。

必要な権限：ManageSandboxes

取り消し不能な操作 — 必ず先に確認

操作	取り消し不能な理由
作成	選択した種類のライセンスを消費します
アクティベート	更新されたデータでサンドボックスを上書きします
破棄	更新データが失われます
削除	サンドボックスが完全に削除されます
AutoActivate=true で更新	完了時に自動適用されます。アクティベートと同じ効果があります

---

操作

1. サンドボックスのインベントリを一覧表示

エンドポイント： GET /services/data/v66.0/sandbox/reports

すべてのサンドボックスについて、ID、名前、ステータス、ライセンスの種類を含む一覧を返します。

sf api request rest "/services/data/v66.0/sandbox/reports" --method GET

レスポンスの完全な形式については、references/api-response-shapes.md を参照してください。

使用する場面： ユーザーが「すべてのサンドボックスを表示して」「サンドボックスはいくつある？」「サンドボックスのステータスは？」と尋ねた場合

主なレスポンスフィールド：

• sandbox.sandboxId（07E プレフィックス）— すべての変更操作に必要です
• sandbox.sandboxName — サンドボックス名（トップレベルフィールド）
• sandbox.license — Developer、Developer Pro、Partial Copy、Full
• sandbox.isPendingActivation — アクティベーション待ちの更新がある場合は true
• sandbox.canActivate／canDelete／canDiscard — 権限フラグ

---

2. サンドボックスの詳細を取得

エンドポイント： GET /services/data/v66.0/sandbox/sandboxes/{sandboxId}

指定したサンドボックスの詳細情報を返します。

使用する場面： ユーザーが特定のサンドボックスのステータス、設定、またはメタデータについて尋ねた場合。

主なレスポンスフィールド：

• status — Active、Pending Activation、Activating、Completed など
• isPendingActivation — 更新が完了し、ユーザーの判断を待っている場合は true
• sandboxType — Developer、DeveloperPro、PartialCopy、Full
• sourceId — ソース組織の ID

---

3. サンドボックスを有効化する（更新を適用）

エンドポイント： PATCH /services/data/v66.0/sandbox/activate/{sandboxId}

重要なドメインルール： この操作は、「有効化待ち」状態で更新が完了したサンドボックスにのみ適用されます。更新されたデータをサンドボックスに適用します。「非アクティブなサンドボックスをオンラインにする」操作でも、サンドボックスを「開始する」操作でもありません。

前提条件：

• サンドボックスのステータスが Pending Activation であること
• 更新が正常に完了していること
• ユーザーに ManageSandboxes 権限があること

PATCH /activate を呼び出す前に：

• GET /sandbox/sandboxes/{id} で、サンドボックスのステータスが Pending Activation であることを確認済み（isPendingActivation: true）
• 更新が正常に完了したことを確認済み
• ユーザーから明示的な確認を受けていること — この操作によりサンドボックスは更新後のデータで上書きされ、元に戻すことはできません

次のような場合に使用： ユーザーが「有効化して」「更新を適用して」「最新のデータを使って」と言った場合

有効化後： サンドボックスは新しく更新された本番データで実行されます。

---

4. 有効化を確認する

エンドポイント： GET /services/data/v66.0/sandbox/sandboxes/{sandboxId}

有効化後にこのエンドポイントをポーリングして、ステータスが Active に変わったことを確認します。これは確認手順であり、単独でユーザーが実行する操作ではありません。

次のような場合に使用： エージェントが有効化の完了を確認する必要がある場合（有効化後に自動で呼び出されます）。

---

5. サンドボックスを破棄する（更新を拒否）

エンドポイント： DELETE /services/data/v66.0/sandbox/discardsandbox/{sandboxId}

重要なドメインルール： この操作は、「有効化待ち」状態で更新が完了したサンドボックスにのみ適用されます。更新を拒否します。既存のサンドボックスは、現在のデータを変更せずに引き続き実行されます。次の操作は行いません。

• ライセンスを解放する
• サンドボックスをソフト削除する、または非表示にする
• サンドボックスを本番環境と一致するようにリセットする

前提条件：

• サンドボックスのステータスが Pending Activation であること
• 更新が完了していること

DELETE /discardsandbox を呼び出す前に：

• GET /sandbox/sandboxes/{id} で、サンドボックスのステータスが Pending Activation であることを確認済み（isPendingActivation: true）
• これは破棄（更新の拒否）であり、削除（永久削除）ではないことを確認済み
• ユーザーから明示的な確認を受けていること — 更新データは完全に失われ、元に戻すことはできません

次のような場合に使用： ユーザーが「更新を破棄して」「既存のデータを維持して」「更新を適用しないで」「更新を拒否して」と言った場合

警告： 破棄は元に戻せません。後で最新の本番データが必要になった場合、ユーザーは新しい更新を開始する必要があります。

---

6. サンドボックスを削除する（永久削除）

エンドポイント： DELETE /services/data/v66.0/sandbox/deletesandbox/{sandboxId}

サンドボックスを完全に削除し、ライセンスを解放します。

前提条件：

• サンドボックスが存在すること
• ユーザーに ManageSandboxes 権限があること

DELETE /deletesandbox を呼び出す前に：

• サンドボックスの詳細（名前、ライセンス、ステータス）をユーザーに提示し、削除の明示的な承認を受けていること

次のような場合に使用： ユーザーが「このサンドボックスを削除して」「完全に削除して」「ライセンスを解放して」と言った場合

警告： この操作は元に戻せません。実行する前に、必ずユーザーに確認してください。安全確認のため、サンドボックス名、ライセンス、ステータスを提示してください。

削除したサンドボックスの復元を求められた場合： 現時点で復旧手順は文書化されていません。推測で対応せず、サポートにエスカレーションしてください。

---

7. 新しいサンドボックスを作成する

新しいサンドボックスを一から作成します。2つの方法がサポートされています。ユーザーの希望に応じて選択してください。定義ファイルまたは再利用可能な DX ブループリントを求められない限り、方法 A をデフォルトにします。

事前条件：

• 要求された種類のライセンスが組織内で利用可能であること
• サンドボックス名が一意で、すでに使用されていないこと
• ユーザーに ManageSandboxes 権限があること

作成前 — 必ず最初に確認してください：

• 名前とライセンスを収集し、そのライセンスの任意の入力項目について確認したこと（references/definition-file-approach.md）

• この確認内容の要約を提示したこと — 共通項目とライセンス固有の項目：

  新しいサンドボックスを作成します — ご確認ください：

  • 名前： <SandboxName>
  • 説明： <Description or "(none)">
  • 作成元： 本番環境
  • ライセンス： <Developer | Developer Pro | Partial Copy | Full>
  • (このライセンス固有の項目も含みます — references/definition-file-approach.md を参照)

  続行する前に、これらの項目を変更できます。

• 明示的な確認を受け取ったこと — 選択した種類のライセンスが消費されます

方法 A — Tooling API レコード（直接）

API： Tooling API — SandboxInfo sObject

必須入力：

• SandboxName — 新しいサンドボックスの名前（英数字、最大 10 文字）
• LicenseType — 次のいずれか：Developer、Developer_Pro、Partial_Copy、Full

任意の入力：

• Description — サンドボックスの用途
• Features — ストレージのアップグレード：Developer→400 MB、Developer_Pro→2 GB（元に戻せません）；Partial_Copy/Full には適用されません
• ApexClassId — SandboxPostCopy を実装する Apex クラス（作成後に実行）
• ActivationUserGroupId — アクセスグループ（デフォルト：すべての有効なユーザー）
• TemplateId / HistoryDays / CopyChatter / CopyArchivedActivities — Partial_Copy/Full のみ；ライセンスごとの表は references/definition-file-approach.md を参照

# Create a Developer sandbox
sf data create record --sobject SandboxInfo --use-tooling-api --values "SandboxName='mybox' LicenseType='Developer'"

方法 B — サンドボックス定義ファイル（Salesforce CLI）

DX ネイティブの方法です。JSON 定義ファイルを作成し、sf org create sandbox --definition-file <file> --alias <name> --target-org <org> を実行します。チェックインして繰り返し使用できる設定や、名前ベースの Apex／グループ参照が必要な場合に適しています。JSON の例、コマンド、項目の表については references/definition-file-approach.md を参照してください。

作成後： SandboxProcess レコードが Status = Processing`` で作成されます。サンドボックスのコピーがすぐに開始されます。

種類を間違えて作成した場合： 削除して、正しい種類で作成し直してください。

名前の変更： 単独では実行できません。Refresh の SandboxName 入力を通じてのみ反映されます。

---

8. 既存のサンドボックスを更新する

最新の本番データでサンドボックスを更新します。2つの方法がサポートされています。ユーザーの希望に応じて選択してください。定義ファイルを求められない限り、方法 A をデフォルトにします。

アプローチ A — Tooling API レコード（直接）

API： Tooling API — SandboxInfo sObject（PATCH）

既存の SandboxInfo レコードを更新してリフレッシュします。

必須入力：

• Sandbox 名 — SandboxInfo レコード ID（0GQ プレフィックス）を検索するために使用します

任意入力：

• SandboxName — リフレッシュ後の sandbox の新しい名前（ユーザーが名前を変更する場合。英数字、最大 10 文字）
• Description — sandbox の新規または更新後の説明
• AutoActivate — リフレッシュ完了時に自動で有効化する場合は true（デフォルト：false）
• Features — ストレージのアップグレード：Developer→400 MB、Developer_Pro→2 GB（元に戻せません）。Partial_Copy／Full では使用できません
• ActivationUserGroupId — アクセスグループ（デフォルト：All Active Users）
• TemplateId／HistoryDays／CopyChatter — Partial_Copy／Full 専用。ライセンスごとの表は references/definition-file-approach.md を参照してください

リフレッシュを開始する前に — 必ず最初に確認してください：

• Sandbox 名を収集し、そのライセンスの任意入力について確認した（references/definition-file-approach.md）

• 次の確認内容を提示した：

  sandbox <name> をリフレッシュします — 確認してください：

  • 変更後の名前： <SandboxName or "(no change)">
  • 説明： <Description or "(no change)">
  • 自動有効化： <Yes | No (default)>
  • Sandbox アクセス： <ActivationUserGroupId or "All Active Users">
  • (このライセンスのその他の項目も含む — references/definition-file-approach.md を参照してください)

  実行前であれば、これらの項目はいつでも変更できます。

• 明示的な確認を受け取った — リフレッシュすると sandbox は本番データで上書きされます。Auto-Activate=Yes の場合は自動的に適用されます（Activate と同等です）

手順：

# 1. Look up SandboxInfo record Id by name
sf data query --query "SELECT Id, SandboxName, LicenseType, Description FROM SandboxInfo WHERE SandboxName = '<name>'" --use-tooling-api --json

# 2. PATCH to trigger refresh; include SandboxName/Description only if the user changed them
# Description is free text — escape any embedded single quotes (' -> \') before interpolating
sf data update record --sobject SandboxInfo --use-tooling-api --record-id <0GQ-id> --values "AutoActivate=true SandboxName='<newName>' Description='<description>'"

アプローチ B — Sandbox 定義ファイル（Salesforce CLI）

作成時と同じ JSON 定義ファイルのひな形を使用して、sf org refresh sandbox --name <name> --definition-file <file> --target-org <org> でリフレッシュします。JSON の例、コマンド、フィールド表については、references/definition-file-approach.md を参照してください。

前提条件：

• sandbox が存在し、リフレッシュ可能な状態であること
• リフレッシュ間隔が経過していること（Developer = 1 日、Dev Pro = 1 日、Partial = 5 日、Full = 29 日）
• ユーザーに ManageSandboxes 権限があること

リフレッシュ後： Status = Processing の新しい SandboxProcess レコードが作成されます。AutoActivate=true の場合、完了時に sandbox が自動で有効化されます。それ以外の場合は Pending Activation 状態になります。

リフレッシュ間隔を満たしていない場合： 最終リフレッシュ日とリフレッシュ可能日を伝えてください。より早く新しいコピーが必要な場合は、予備ライセンスがあればクローン（委任）を利用できます。

---

9. ライセンス使用状況を確認する

エンドポイント： GET /services/data/v66.0/sandbox/licenses

ライセンスの種類ごとに、容量、使用状況、残数を返します。sandbox 名や ID は必要ありません。

sf api request rest "/services/data/v66.0/sandbox/licenses" --method GET

応答の完全な形式については、references/api-response-shapes.md を参照してください。

使用する場面： ユーザーが「sandbox ライセンスはいくつ残っていますか」「ライセンスの使用状況はどうなっていますか」「Full sandbox をもう 1 つ作成できますか」と尋ねた場合や、sandbox の作成／リフレッシュ前に、該当する licenseType の容量があるか確認する場合に使用します。

主な応答フィールド：

• licenseType — DEVELOPER、DEVELOPER_PRO、PARTIAL、FULL
• limit — この種類のライセンス総数
• used — 現在割り当てられている数
• available — 残数（つまり limit - used）

ライセンス上限により作成／リフレッシュできない場合： 利用可能な種類を選ぶ、古い sandbox を削除してライセンスを空ける、管理者にライセンス増加を依頼する、または期限切れの Courtesy Full Copy の場合は購入／変換する方法を提示してください。

エージェント向け判断ガイド

まず sandboxId を特定します。名前で特定する場合は、GET /sandbox/reports を呼び出して sandboxName を照合します。ID（07E プレフィックス）で特定する場合は、GET /sandbox/sandboxes/{sandboxId} を直接呼び出します。/sandbox/reports は呼び出さないでください。

ユーザーの発言	操作	主な確認事項
「すべてのサンドボックスを表示して」	GET /sandbox/reports	—
「X のステータスは？」	GET /sandbox/reports（名前で特定）または GET /sandbox/sandboxes/{id}（ID で特定）	—
「サンドボックス X を有効化して」	1. sandboxId を特定する 2. PATCH /sandbox/activate/{sandboxId}	isPendingActivation: true であることを確認します。先にユーザーに確認してください
「X の更新を破棄して」	1. sandboxId を特定する 2. DELETE /sandbox/discardsandbox/{sandboxId}	isPendingActivation: true であることを確認します。先にユーザーに確認してください
「サンドボックス X を削除して」	1. sandboxId を特定する 2. DELETE /sandbox/deletesandbox/{sandboxId}	先にユーザーに確認してください

---

よくある間違いとその回避方法

間違い	正しい理解
任意のサンドボックスを「開始」するために activate を使う	Activate は完了した更新にのみ適用されます
discard を「非表示」や「ソフト削除」に使う	Discard は保留中の更新を拒否する場合にのみ使います
先にステータスを確認せずに有効化する	必ず isPendingActivation = true であることを確認してください
Create、Activate、Discard、Delete、または AutoActivate=true を指定した Refresh の前に確認を省略する	上記の「取り消せない操作」を参照してください。必ず先に確認してください
Create の際に AutoActivate を提示する	Refresh 専用のフィールドです
Refresh の際に ApexClassId を提示する	Create 専用のフィールドです