Sandboxed API (SAPI) 是以成熟的 Sandbox2 專案為基礎建構而成。本頁說明 SAPI 的設計架構和重要概念。
總覽
SAPI 旨在為開發人員提供工具，協助他們準備 C/C++ 程式庫以進行沙箱處理，並提供與沙箱版 C/C++ 程式庫通訊所需的 API。
下圖顯示 SAPI 沙箱 C/C++ 程式庫的架構：
SAPI 也提供基元，用於在 SAPI 程式庫和主機程式碼之間，手動和自動 (根據自訂指標屬性) 同步處理記憶體 (陣列、結構)。
最後，高階 Transactions API 可監控 SAPI 程式庫，並在失敗時重新啟動 (例如因安全違規、當機或資源耗盡)。
Sandbox2
開放原始碼專案 Sandbox2 是由 Google 資安工程師開發及維護，也是 SAPI 使用的核心沙箱技術。Sandbox2 包含三個主要元件：沙箱政策、執行工具和沙箱。
沙箱政策
沙箱政策會定義沙箱程式庫的受限執行環境。方法是明確指出可執行的系統呼叫。SAPI 使用與 Sandbox2 相同的機制，請參閱 Sandbox2 的「沙箱政策」一節和「入門指南」頁面，進一步瞭解如何設計及定義沙箱政策。
根據預設，產生的 SAPI 沙箱類別會使用 DefaultConfig (sapi::SandboxConfig::DefaultConfig()) 初始化。DefaultConfig() 會使用下列項目設定沙箱：
- 使用
sapi::Sandbox2Config::DefaultPolicyBuilder()建構的預設 Sandbox2 政策 sapi::Sandbox2Config::DefaultLimits()的預設資源和時間限制- 啟用共用記憶體通訊 (與
DefaultPolicyBuilder()中的共用記憶體權限配對) - 預設指令列旗標 (
sapi::SandboxConfig::DefaultFlags()) 和環境變數 (sapi::SandboxConfig::DefaultEnvironmentVariables())，用於設定沙箱中的基準記錄和執行階段行為
如要自訂沙箱政策或設定，請從 sapi::SandboxConfig::DefaultConfig() 開始，修改傳回的 sapi::SandboxConfig，並將其傳遞至產生的沙箱建構函式 (或在傳遞至 sapi_library 建構規則的 sandbox.h 標頭檔案中定義自訂沙箱子類別)。舉例來說，您可以從 sapi::Sandbox2Config::DefaultPolicyBuilder() 開始建構政策，並鏈結其他規則 (或在需要更嚴格的設定時直接建構 PolicyBuilder)，並在新增旗標或環境變數時，從 sapi::SandboxConfig::DefaultFlags() 或 sapi::SandboxConfig::DefaultEnvironmentVariables() 開始，以便保留基準設定。
Sandboxed Library
這是沙箱化的 C/C++ 程式庫，會在 Sandbox2 提供的受限沙箱環境中執行。最終，沙箱化程式庫會公開必要功能，供主機程式碼取用。
沙箱化程式庫是使用 sapi_library 建構規則建構而成，您可以在其中指定自訂沙箱政策，定義受限制的執行環境。視程式庫而定，您可能需要編寫包裝函式或虛設常式程式碼 (請參閱 libcurl)，但在準備 SAPI 版本時，您不需要變更 C/C++ 程式庫的原始碼。
SAPI 物件和 RPC 存根
SAPI 物件是 C++ 物件，可公開 Sandboxed Library 的 API。它會將主機程式碼的呼叫轉送至 RPC 虛設常式，後者與沙箱化程式庫一起嵌入 SAPI 程式庫。
這兩個元素是由建構系統使用 sapi_library() 建構規則自動產生。SAPI 支援兩種建構系統：Google 的 Bazel 和 CMake。
主辦方代碼
主機程式碼會實作 SAPI 程式庫提供的邏輯。否則，這會耗用 C/C++ 程式庫的非沙箱版本。因此，主機程式碼會呼叫 SAPI 程式庫匯出的函式，將資料傳遞至沙箱，並從沙箱接收資料。
主機程式碼必須經過調整，才能使用 SAPI 程式庫。最明顯的例子是，由於程式庫位於獨立的沙箱程序中，因此無法呼叫程式庫的函式。因此，SAPI 提供相關工具，可建立 SAPI 物件，將呼叫作業 Proxy 至 SAPI 程式庫。
概念
Bazel 建構規則
SAPI 專案提供兩項 Bazel 建構規則，用於對 C/C++ 程式庫進行沙箱處理：
sapi_library()：建立所有必要輸出內容，將 C/C++ 程式庫沙箱化為 Sandbox2 Sandboxee。建構輸出內容可做為cc_binary()規則的依附元件，用於建構主機程式碼二進位檔。sapi_interface()：自動生成可納入主機程式碼二進位檔的標頭。
如要進一步瞭解建構規則，請參閱「建構規則」。
變數
SAPI 提供多種特殊型別 (稱為「SAPI 型別」)，建議您在主機程式碼中使用。需要 SAPI 型別的主要原因是，主機程式碼和沙箱化程式庫之間的程序 (因此記憶體) 會隔離。
如需更詳盡的說明，以及常用 SAPI 類型的總覽，請參閱「變數」。
交易
如上所述，對沙箱化程式庫發出的任何 API 呼叫都會透過 RPC 層傳遞。如要在這個層級處理失敗情形，您需要實作適當的錯誤處理機制。SAPI 交易模組提供必要機制，確保對沙箱程式庫的所有呼叫都能完成，不會發生任何 RPC 層級問題，或傳回相關錯誤。
如要進一步瞭解這個主題，請參閱「交易」。
開始使用
請參閱「入門」頁面，設定第一個 Sandboxed API 專案。