本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用工作階段指令碼來管理使用者的串流體驗 WorkSpaces 集區提供執行個體上的工作階段指令碼。當使用者的串流工作階段發生特定事件時，您可以使用這些指令碼來執行您自己的自訂指令碼。例如，您可以在使用者的串流工作階段開始之前，使用自訂指令碼來準備 WorkSpaces 集區環境。在使用者完成其串流工作階段之後，您也可以使用自訂指令碼來清除串流執行個體。 工作階段指令碼是在 WorkSpace 映像中指定。這些指令碼在使用者環境或系統環境之內執行。如果您的工作階段指令碼使用標準輪出來撰寫資訊、錯誤或偵錯訊息，這些都可以選擇性地儲存在您 Amazon Web Services 帳戶內的 Amazon S3 儲存貯體中。 **Topics** + [串流工作階段開始之前執行指令碼](#run-scripts-before-streaming-sessions-begin) + [在串流工作階段結束之後執行指令碼](#run-scripts-after-streaming-sessions-end) + [建立和指定工作階段指令碼](#create-specify-session-scripts) + [工作階段指令碼組態檔案](#session-script-configuration-file) + [使用 Windows PowerShell 檔案](#using-powershell-files-with-session-scripts) + [記錄工作階段指令碼輸出](#logging-session-output) + [搭配工作階段指令碼使用持久性儲存](#use-storage-connectors-with-session-scripts) + [為工作階段指令碼日誌啟用 Amazon S3 儲存貯體儲存](#enable-S3-bucket-storage-session-script-logs) ## 串流工作階段開始之前執行指令碼 您可以設定指令碼來執行最長 60 秒，之後，使用者的應用程式才啟動，他們的串流工作階段才開始。這樣做可讓您在使用者開始串流其應用程式之前自訂 WorkSpaces 集區環境。當工作階段指令碼執行時，使用者會看到載入環。當您的指令碼成功完成或超過最長等待時間後，使用者的串流工作階段就會開始。如果您的指令碼未成功完成，則會顯示錯誤訊息給使用者。但是，不會阻止您的使用者使用其串流工作階段。 當您在 Windows 執行個體上指定檔案名稱時，您必須使用雙反斜線。例如： ``` C:\\Scripts\\Myscript.bat ``` 如果您不使用雙反斜線，則會顯示錯誤，通知您`.json`檔案格式不正確。 **注意** 當您的指令碼成功完成時，必須傳回 0 這個值。如果您的指令碼傳回 0 以外的值，WorkSpaces 會向使用者顯示錯誤訊息。 當您在串流工作階段開始之前執行指令碼時，會發生下列程序： 1. 您的使用者連線到 WorkSpace WorkSpaces。它們使用 SAML 2.0 進行連線。 1. 發生以下其中一項： + 如果已針對使用者啟用應用程式設定持續性，則會下載並掛載應用程式設定虛擬硬碟 (VHD) 檔案，其中存放使用者的自訂項目和 Windows 設定。在這種情況下，需要 Windows 使用者登入。 如需應用程式設定持續性的相關資訊，請參閱[為您的 WorkSpaces 集區使用者啟用應用程式設定持續性](app-settings-persistence.md)。 + 如果應用程式設定持續性未啟用，但 Windows 使用者已登入。 1. 您的工作階段指令碼會開始。如果已針對使用者啟用持久性儲存，則儲存連接器掛載也會開始。如需持久性儲存的相關資訊，請參閱[啟用和管理 WorkSpaces 集區的持久性儲存](persistent-storage.md)。 **注意** 儲存連接器掛載並不需要完成，串流工作階段也會開始。如果工作階段指令碼比儲存連接器掛載更早完成，串流工作階段會開始。 如需有關監控儲存連接器掛載狀態的資訊，請參閱[搭配工作階段指令碼使用持久性儲存](#use-storage-connectors-with-session-scripts)。 1. 您的工作階段指令碼完成或逾時。 1. 使用者的串流工作階段會開始。 ## 在串流工作階段結束之後執行指令碼 您也可以將您的指令碼設定為在使用者的工作階段結束之後執行。例如，當使用者從 WorkSpaces 用戶端工具列選取**結束工作階段**，或當他們達到工作階段允許的持續時間上限時，您可以執行指令碼。您也可以使用這些工作階段指令碼，在串流執行個體終止之前清除 WorkSpaces 環境。例如，您可以使用指令碼來發行檔案鎖定或上傳日誌檔。當您在串流工作階段結束之後執行指令碼時，則處理如下： 1. 使用者的 WorkSpaces 串流工作階段結束。 1. 您的工作階段終止指令碼會開始。 1. 工作階段終止指令碼完成或逾時。 1. 發生 Windows 使用者登出。 1. 以下一項或兩項同時發生 (如果適用)： + 如果已針對使用者啟用應用程式設定持續性，則會卸載應用程式設定 VHD 檔案 (其中存放使用者的自訂項目和 Windows 設定)，並上傳到您帳戶中的 Amazon S3 儲存貯體。 + 如果已針對使用者啟用持久性儲存，則儲存連接器會完成最終同步，然後卸載。 1. WorkSpace 已終止。 ## 建立和指定工作階段指令碼 完成下列程序，為 WorkSpaces 集區中的 WorkSpaces 建立和指定工作階段指令碼。 1. 連線至您要從中建立自訂映像的 Windows WorkSpaces。 1. `/AWSEUC/SessionScripts` 如果目錄尚未存在，請建立目錄。 1. `/AWSEUC/SessionScripts/config.json` 如果組態檔案尚未存在，請使用[工作階段指令碼組態範本](https://docs.aws.amazon.com/workspaces/latest/adminguide/pools-images-session-scripts.html#session-script-configuration-file)建立組態檔案。 1. 導覽至 `C:\AWSEUC\SessionScripts` 並開啟 `config.json` 組態檔案。 如需工作階段指令碼參數的相關資訊，請參閱[工作階段指令碼組態檔案](#session-script-configuration-file)。 1. 完成變更之後，儲存並關閉 `config.json` 檔案。 1. 完成從 WorkSpace 建立映像的步驟。如需詳細資訊，請參閱[建立 WorkSpaces 集區的自訂映像和套件](pools-images-custom-image.md)。 ## 工作階段指令碼組態檔案 若要在 Windows 執行個體中找到工作階段指令碼組態檔案，請導覽至 `C:\AWSEUC\SessionScripts\config.json`。檔案的格式如下所示。 **注意** 組態檔案為 JSON 格式。確認您在此檔案中輸入的任何文字為有效的 JSON 格式。 ``` { "SessionStart": { "executables": [ { "context": "system", "filename": "", "arguments": "", "s3LogEnabled": true }, { "context": "user", "filename": "", "arguments": "", "s3LogEnabled": true } ], "waitingTime": 30 }, "SessionTermination": { "executables": [ { "context": "system", "filename": "", "arguments": "", "s3LogEnabled": true }, { "context": "user", "filename": "", "arguments": "", "s3LogEnabled": true } ], "waitingTime": 30 } } ``` 您可以在工作階段指令碼組態檔案中使用以下參數。 **`SessionStart/SessionTermination `** 在適當的工作階段事件中根據物件名稱執行的工作階段指令碼。 **類型：**字串 **必要**：否 **允許的值：****SessionStart**、**SessionTermination** **`WaitingTime`** 工作階段指令碼的最長持續時間 (以秒為單位)。 **類型**：整數 **必要**：否 **限制：**最長持續時間為 60 秒。如果工作階段指令碼在此期間內未完成，則會停下。如果需要讓指令碼繼續執行，請以單獨程序的形式來加以啟動。 **`Executables`** 要執行的指令碼工作階段的詳細資訊。 **類型：**字串 **必要**：是 **限制：**針對每個工作階段事件可執行的指令碼數量上限為 2 (一個用於使用者環境，另一個用於系統環境)。 **`Context`** 用來執行工作階段指令碼的環境。 **類型：**字串 **必要**：是 **允許的值：****user**、**system** **`Filename`** 要執行的工作階段指令碼的完整路徑。如果未指定此參數，則工作階段指令碼不會執行。 **類型：**字串 **必要**：否 **限制：**檔案名稱和完整路徑的最大長度為 1,000 個字元。 **允許的值：****.bat**、**.exe**、 **.sh** 您也可以使用 Windows PowerShell 檔案。如需詳細資訊，請參閱[使用 Windows PowerShell 檔案](#using-powershell-files-with-session-scripts)。 **`Arguments`** 工作階段指令碼或可執行檔的引數。 **類型：**字串 **必要**：否 **長度限制：**長度上限為 1,000 個字元。 **`S3LogEnabled`** 當此參數的值設為 **True** 時，您的 Amazon Web Services 帳戶內會建立 S3 儲存貯體，以存放工作階段指令碼所建立的日誌。依預設，此值是設為 **True**。如需詳細資訊，請參閱本主題稍後的*記錄工作階段指令碼輸出*一節。 **類型**：布林值 **必要**：否 **允許的值：****True**、**False** ## 使用 Windows PowerShell 檔案 若要使用 Windows PowerShell 檔案，請在 `filename` 參數中指定 PowerShell 檔案的完整路徑： ``` "filename": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", ``` 然後，在 **arguments** 參數中指定您的工作階段指令碼： ``` "arguments": "-File \"C:\\path\\to\\session\\script.ps1\"", ``` 最後，確認 PowerShell 執行政策允許您的 PowerShell 檔案執行。 ## 記錄工作階段指令碼輸出 在組態檔案中啟用此選項時，WorkSpaces 集區會自動從寫入標準輸出的工作階段指令碼擷取輸出。此輸出會上傳到您帳戶中的 Amazon S3 儲存貯體。您可以檢閱日誌檔以進行故障排除或偵錯。 **注意** 當工作階段指令碼傳回一個值，或 **WaitingTime** 中設定值已超過時 (以先到者為準)，就會上傳日誌檔。 ## 搭配工作階段指令碼使用持久性儲存 當 WorkSpaces 持久性儲存啟用時，儲存會在工作階段啟動指令碼執行時開始掛載。如果您的指令碼依賴掛載的持久性儲存，您可以等待連接器可用。WorkSpaces 會在 Windows WorkSpaces 的 Windows 登錄檔中維護儲存連接器的掛載狀態，金鑰如下： ``` HKEY_LOCAL_MACHINE\SOFTWARE\Amazon\AWSEUC\Storage\\ ``` 登錄機碼值如下： + 提供的使用者名稱：透過存取模式提供的使用者 ID。每個模式的存取模式和值如下： + 使用者集區：使用者的電子郵件地址 + 串流 URL：UserID + SAML：NameID。如果使用者名稱包含斜線 (例如，網域使用者的 SAMAccountName)，斜線會換成 "-" 字元。 + 儲存連接器：為使用者啟用的持久性儲存選項的連接器。儲存連接器值如下： + HomeFolder 每個儲存連接器登錄機碼都會包含 **MountStatus** DWORD 值。下表列出可能的 **MountStatus** 值。 **注意** 若要檢視這些登錄機碼，您的映像必須安裝 Microsoft .NET Framework 4.7.2 版或更新版本。 | Value | Description | | --- | --- | | 0 | 未針對此使用者啟用儲存連接器 | | 1 | 儲存連接器掛載正在進行中 | | 2 | 儲存連接器掛載成功 | | 3 | 儲存連接器掛載失敗 | | 4 | 儲存連接器掛載已啟用，但尚未掛載 | ## 為工作階段指令碼日誌啟用 Amazon S3 儲存貯體儲存 當您在工作階段指令碼組態中啟用 Amazon S3 記錄時，WorkSpaces 集區會從工作階段指令碼擷取標準輸出。此輸出會定期上傳到您的 Amazon Web Services 帳戶內的 S3 儲存貯體。對於每個 AWS 區域，WorkSpaces 集區會在您的帳戶中建立專屬於您的帳戶和區域的儲存貯體。 您不需要執行任何設定任務來管理這些 S3 儲存貯體。它們完全由 WorkSpaces 服務管理。存放在每個儲存貯體中的日誌檔在傳輸中會使用 Amazon S3 的 SSL 端點加密，靜態時則使用 Amazon S3 的受管加密金鑰加密。儲存貯體使用特定格式命名，如下所示： ``` wspool-logs---random-identifier ``` **``** 這是在工作階段指令碼日誌中啟用 Amazon S3 儲存貯體儲存的情況下建立 WorkSpaces 集區的 AWS 區域代碼。 **``** 您的 Amazon Web Services 帳戶識別符。隨機 ID 可確保與該區域中的其他儲存貯體不發生衝突。儲存貯體名稱的第一部分 `wspool-logs`，不會因為跨帳戶或區域而變更。 例如，如果您在美國西部 （奧勒岡） 區域 (`us-west-2`) 中於帳戶號碼 的映像中指定工作階段指令碼`123456789012`，WorkSpaces 集區會在帳戶中建立 Amazon S3 儲存貯體，並顯示名稱。只有具備足夠許可的管理員可以刪除這個儲存貯體。 ``` wspool-logs-us-west-2-1234567890123-abcdefg ``` 停用工作階段指令碼不會刪除存放在 S3 儲存貯體中的日誌檔案。您或具有足夠許可的其他管理員必須使用 Amazon S3 主控台或 API，才能永久刪除日誌檔。WorkSpaces 集區會新增儲存貯體政策，以防止意外刪除儲存貯體。 當工作階段指令碼啟用時，將會為每個啟動的串流工作階段建立唯一資料夾。 在您的帳戶中，日誌檔存放在 S3 儲存貯體中的資料夾路徑使用以下結構： ``` //////SessionScriptsLogs/ ``` ****** 存放工作階段指令碼的 S3 儲存貯體名稱。名稱格式如本節前文所述。 ****** 工作階段的來源堆疊名稱。 ****** 工作階段指令碼執行所在的 WorkSpaces 集區名稱。 ***<存取模式>*** 使用者的身分方法：`custom`適用於 WorkSpaces API 或 CLI、`federated`適用於 SAML，以及`userpool`適用於使用者集區中的使用者。 ****** 使用者特定的資料夾名稱。此名稱是使用從使用者識別符產生的小寫 SHA-256 雜湊十六進位字串建立。 ****** 使用者串流工作階段的識別符。每個使用者串流工作階段都會產生唯一 ID。 ****** 產生工作階段指令碼日誌的事件。事件值為：`SessionStart` 和 `SessionTermination`。 以下範例資料夾結構適用於從 test-stack 和 test-fleet 開始的串流工作階段。工作階段使用來自 之 `testuser@mydomain.com` AWS 帳戶 ID 的使用者 ID 的 API`123456789012`，以及美國西部 （奧勒岡） 區域中的設定群組 `test-stack` ()`us-west-2`： ``` wspool-logs-us-west-2-1234567890123-abcdefg/test-stack/test-fleet/custom/a0bcb1da11f480d9b5b3e90f91243143eac04cfccfbdc777e740fab628a1cd13/05yd1391-4805-3da6-f498-76f5x6746016/SessionScriptsLogs/SessionStart/ ``` 在此範例資料夾結構中，一個日誌檔用於使用者環境工作階段開始指令碼，另一個日誌檔用於系統環境工作階段開始指令碼 (如果適用)。