本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用映像助理 CLI 操作，以程式設計方式建立 Amazon WorkSpaces 應用程式映像
<a name="programmatically-create-image"></a>

您可以連線至映像建置器，並使用映像助理圖形使用者界面 (GUI) 或命令列界面 (CLI) 操作來建立 Amazon WorkSpaces 應用程式映像。映像助理 CLI 操作提供與映像助理 GUI 類似的功能。您可以使用這些操作，以程式設計方式執行下列動作：
+ 管理在映像中所含的應用程式。
+ 儲存、更新和重設預設應用程式設定。
+ 啟用或停用 WorkSpaces 應用程式動態應用程式架構。
+ 指定標籤。
+ 建立映像。

 您可以使用這些操作，將 WorkSpaces 應用程式映像建立與持續整合或部署軟體開發程序整合。

若要使用映像助理 CLI 操作，請在映像建置器上使用所選的命令列殼層。例如，您可以使用 Windows 命令提示字元或 PowerShell。

**注意**  
映像建置器必須使用 2019 年 7 月 26 日當天或之後發行的 WorkSpaces 應用程式代理程式版本。如果您沒有映像建置器，必須進行建立。如需詳細資訊，請參閱[啟動映像建置器以安裝和設定串流應用程式](tutorial-image-builder-create.md)。

**Topics**
+ [

# 使用映像助理 CLI 操作建立預設應用程式和 Windows 設定
](create-default-app-windows-settings-image-assistant.md)
+ [

# 使用映像助理 CLI 操作來將應用程式的啟動效能最佳化
](optimize-app-launch-performance-image-assistant-cli.md)
+ [

# 以程式設計方式建立 Amazon WorkSpaces 應用程式映像的程序概觀
](process-overview-creating-image-programmatically-image-assistant-cli.md)
+ [

# 建立和管理 Amazon WorkSpaces 應用程式映像的映像助理 CLI 操作
](cli-operations-managing-creating-image-image-assistant.md)

# 使用映像助理 CLI 操作建立預設應用程式和 Windows 設定
<a name="create-default-app-windows-settings-image-assistant"></a>

您可以建立預設應用程式和 Windows 設定，讓使用者可以快速開始使用應用程式。當您建立這些設定時，WorkSpaces 應用程式會將 Windows 預設使用者設定檔取代為您設定的設定檔。如此一來，您即可使用 Windows 預設使用者描述檔，為機群執行個體中的使用者建立初始設定。如果您透過使用映像助理 CLI 操作、應用程式安裝程式或自動化建立這些設定，應直接修改 Windows 預設使用者描述檔。

若要使用另一個 Windows 使用者的使用者描述檔覆寫 Windows 預設使用者描述檔，您也可以使用映像助理 `update-default-profile` CLI 操作。

如需設定預設應用程式和 Windows 設定的詳細資訊，請參閱在 中*為您的 WorkSpaces 應用程式使用者建立預設應用程式和 Windows 設定*[Amazon WorkSpaces 應用程式的預設應用程式和 Windows 設定以及應用程式啟動效能](customizing-appstream-images.md)。

# 使用映像助理 CLI 操作來將應用程式的啟動效能最佳化
<a name="optimize-app-launch-performance-image-assistant-cli"></a>

WorkSpaces 應用程式可讓您最佳化使用者串流工作階段的應用程式啟動效能。當您透過使用映像助理 CLI 操作來這麼做時，可以指定檔案來將應用程式的啟動最佳化。將檔案新增到應用程式最佳化資訊清單，可縮短在新機群執行個體上第一次啟動該應用程式所需的時間。不過，這也會延長將該機群執行個體提給使用者使用所需的時間。此最佳化資訊清單是依應用程式以行分隔的文字檔案。

**注意**  
如果您是透過同時使用映像助理 CLI 操作和映像助理 GUI，來採用應用程式最佳化資訊清單，則會合併資訊清單。

以下是應用程式最佳化清單檔案的範例：

```
C:\Program Files (x86)\Notepad++\autoCompletion
C:\Program Files (x86)\Notepad++\localization
C:\Program Files (x86)\Notepad++\plugins
C:\Program Files (x86)\Notepad++\themes
C:\Program Files (x86)\Notepad++\updater
C:\Program Files (x86)\Notepad++\userDefineLangs
C:\Program Files (x86)\Notepad++\change.log
C:\Program Files (x86)\Notepad++\config.xml
C:\Program Files (x86)\Notepad++\contextMenu.xml
C:\Program Files (x86)\Notepad++\doLocalConf.xml
C:\Program Files (x86)\Notepad++\functionList.xml
C:\Program Files (x86)\Notepad++\langs.model.xml
C:\Program Files (x86)\Notepad++\license.txt
C:\Program Files (x86)\Notepad++\notepad++.exe
C:\Program Files (x86)\Notepad++\readme.txt
C:\Program Files (x86)\Notepad++\SciLexer.dll
C:\Program Files (x86)\Notepad++\shortcuts.xml
C:\Program Files (x86)\Notepad++\stylers.model.xml
```

如需有關最佳化應用程式啟動效能的詳細資訊，請參閱 [Amazon WorkSpaces 應用程式的預設應用程式和 Windows 設定以及應用程式啟動效能](customizing-appstream-images.md) 中的*最佳化應用程式的啟動效能*。

# 以程式設計方式建立 Amazon WorkSpaces 應用程式映像的程序概觀
<a name="process-overview-creating-image-programmatically-image-assistant-cli"></a>

您可以使用映像助理 CLI 操作搭配應用程式安裝自動化，來建立完全程式設計的 WorkSpaces 應用程式映像建立工作流程。在應用程式安裝自動化完成後，但在建立映像前，請使用映像助理 CLI 操作來指定下列各項：
+ 您的使用者可以啟動的可執行檔
+ 適用於您應用程式的最佳化資訊清單
+ 其他 WorkSpaces 應用程式映像中繼資料

下列高階概觀說明以程式設計方式建立 WorkSpaces 應用程式映像的程序。

1. 使用應用程式安裝自動化在映像建置器上安裝所需的應用程式。此安裝可能包含使用者將啟動的應用程式、任何依存項目，與背景應用程式。

1. 決定要最佳化的檔案和資料夾。

1. 如果適用，請使用映像助理 `add-application` CLI 操作來指定 WorkSpaces 應用程式映像的應用程式中繼資料和最佳化資訊清單。

1. 若要為 WorkSpaces 應用程式映像指定其他應用程式，請視需要為每個應用程式重複步驟 1 到 3。

1. 如果適用，請使用映像助理 `update-default-profile` CLI 操作來覆寫預設的 Windows 描述檔，並為您的使用者建立預設應用程式和 Windows 設定。

1. 使用映像助理 `create-image` CLI 操作來建立映像。

# 建立和管理 Amazon WorkSpaces 應用程式映像的映像助理 CLI 操作
<a name="cli-operations-managing-creating-image-image-assistant"></a>

本節說明可用來建立和管理 WorkSpaces 應用程式映像的映像助理 CLI 操作。

在 Windows 映像建置器上，包含命令列介面的可執行檔位於：C:\$1Program Files\$1Amazon\$1Photon\$1ConsoleImageBuilder\$1Image-Assistant.exe。為方便起見，這個可執行檔會包含在 Windows PATH 變數中。這可讓您呼叫映像助理 CLI 操作，無需指定可執行檔的絕對路徑。若要呼叫這些操作，請輸入 **image-assistant.exe** 命令。

在 Linux 映像建置器上，映像助理工具位於 /usr/local/appstream/image-assistant/AppStreamImageAssistant，且符號連結位於 /bin/AppStreamImageAssistant。

## `help` 操作
<a name="help-operation-image-assistant-cli"></a>

擷取所有映像助理 CLI 操作的清單。已針對此清單中的每個操作提供描述和用法語法。若要顯示特定操作的說明，輸入該操作的名稱，並指定 **--help** 參數。例如：

```
add-application --help
```

**概要**

```
help
```

**輸出**

列印可用操作清單與其功能描述的標準輸出。

## `add-application` 操作
<a name="add-application-operation-image-assistant-cli"></a>

將應用程式新增至 WorkSpaces 應用程式使用者的應用程式清單。這個清單中的應用程式會包含在應用程式型錄中。應用程式目錄會在使用者登入 WorkSpaces 應用程式串流工作階段時顯示。

**注意**  
如果您需要變更應用程式組態，請移除應用程式，並新增包含更新設定的應用程式。

**概要**

```
add-application
--name <value>
--absolute-app-path <value>
[--display-name <value>]
[--absolute-icon-path <value>]
[--working-directory <value>]
[--launch-parameters <""-escaped value>]
[--absolute-manifest-path <value>]
```

**選項**

**`--name` (string)**  
應用程式的唯一名稱。長度上限為 256 個字元。您可以新增最多 50 個應用程式。您不能使用空白字元。

**`--absolute-app-path` (string)**  
可執行檔、批次檔案或應用程式指令碼的絕對路徑。路徑必須指向有效的檔案。

**`--display-name` (string)**  
在應用程式型錄中顯示的應用程式名稱。如果您未指定顯示名稱，WorkSpaces 應用程式會建立衍生自可執行檔名稱的名稱。名稱建立時沒有副檔名且其中以底線代替空格。長度上限為 256 個字元。

**`--absolute-icon-path` (string)**  
應用程式圖示的絕對路徑。路徑必須指向以下其中一個類型的有效圖示檔案：.jpg、.png 或 .bmp。最大尺寸為 256 px x 256 px。如果您沒有指定路徑，則會使用可執行檔的預設圖示 (如果可用)。如果可執行檔無法使用預設圖示，則會使用預設 WorkSpaces 應用程式圖示。

**`--working-directory` (string)**  
啟動應用程式時，應用程式的初始工作目錄。

**`--absolute-manifest-path` (string)**  
以新行分隔之文字檔案的路徑。該檔案會指定檔案的絕對路徑，以在將機群執行個體供使用者用於串流前進行最佳化。路徑必須指向有效的文字檔案。

**訊息輸出**


| 結束程式碼 | 列印為標準輸出的訊息 | Description | 
| --- | --- | --- | 
| 0 |  \$1"狀態": 0, "訊息": "成功"\$1  |  已成功新增應用程式。 | 
| 1 |  \$1"狀態": 1, "訊息": "需要管理員權限才能執行此操作"\$1  |  需要管理員權限才能完成此操作。 | 
| 1 |  \$1"狀態": 1, "訊息": "無法將超過 50 個應用程式新增到型錄。"\$1  |  無法新增應用程式，因為可新增至 WorkSpaces 應用程式應用程式目錄的應用程式數目上限為 50。 | 
| 1 |  \$1"狀態": 1, "訊息": "名稱不是唯一的"\$1  |  WorkSpaces 應用程式目錄中已存在具有該名稱的應用程式。 | 
| 1 |  \$1"狀態": 1, "訊息": "找不到檔案 (absolute-app-path)"\$1  |  找不到指定的 absolute-app-path 檔案。 | 
| 1 |  \$1"狀態": 1, "訊息": "不支援的副檔名"\$1  |  此 Absolute-app-path 參數僅支援以下檔案類型：.exe 和 .bat。 | 
| 1 |  \$1"狀態": 1, "訊息": "找不到目錄 (working-directory)" |  找不到指定的 working-directory 目錄。 | 
| 1 |  \$1"狀態": 1, "訊息": "找不到最佳化資訊清單：<filename>"\$1  |  找不到指定的 optimization-manifest 檔案。 | 
| 1 |  \$1"狀態": 1, "訊息": "找不到檔案：<filename>"\$1  |  找不到在最佳化資訊清單中指定的檔案。 | 
| 255 |  \$1"狀態": 255, "訊息": <error message>\$1  |  發生未預期的錯誤。再次嘗試請求。如果錯誤仍然存在，請聯絡 AWS 支援 尋求協助。如需詳細資訊，請參閱 [AWS 支援 中心](https://console.aws.amazon.com/support/home#/)。 | 

## `remove-application` 操作
<a name="remove-application-operation-image-assistant-cli"></a>

從 WorkSpaces 應用程式映像的應用程式清單中移除應用程式。應用程式不會解除安裝或修改，但使用者將無法從 WorkSpaces 應用程式目錄啟動它。

**概要**

```
remove-application
--name <value>
```

**選項**

**`--name` (string)**  
要移除的應用程式唯一識別符。

**訊息輸出**


| 結束程式碼 | 列印為標準輸出的訊息 | Description | 
| --- | --- | --- | 
| 0 |  \$1"狀態": 0, "訊息": "成功"\$1  |  已成功移除應用程式。 | 
| 1 |  \$1"狀態": 1, "訊息": "需要管理員權限才能執行此操作"\$1  |  需要管理員權限才能完成此操作。 | 
| 1 |  \$1"狀態": 1, "訊息": "找不到應用程式"\$1  |  WorkSpaces 應用程式目錄中找不到指定的應用程式。 | 
| 255 |  \$1"狀態": 255, "訊息": <error message>\$1  |  發生未預期的錯誤。再次嘗試請求。如果錯誤仍然存在，請聯絡 AWS 支援 尋求協助。如需詳細資訊，請參閱 [AWS 支援 中心](https://console.aws.amazon.com/support/home#/)。 | 

## `list-applications` 操作
<a name="list-applications-operation-image-assistant-cli"></a>

列出在應用程式型錄中指定的所有應用程式。

**概要**

```
list-applications
```

**訊息輸出**


| 結束程式碼 | 列印為標準輸出的訊息 | Description | 
| --- | --- | --- | 
| 0 |  \$1"狀態": 0, "訊息": "成功", "應用程式": [ \$1..app1.. \$1, \$1 ..app2.. \$1]\$1  |  WorkSpaces 應用程式目錄中的應用程式清單。 | 
| 255 |  \$1"狀態": 255, "訊息": <error message>\$1  |  發生未預期的錯誤。再次嘗試請求。如果錯誤仍然存在，請聯絡 AWS 支援 尋求協助。如需詳細資訊，請參閱 [AWS 支援 中心](https://console.aws.amazon.com/support/home#/)。 | 

## `update-default-profile` 操作
<a name="update-default-profile-image-assistant-cli"></a>

將指定的 Windows 使用者描述檔複製到 Windows 預設使用者描述檔中。串流的新使用者會繼承在指定描述檔中存放的設定。

**注意**  
Linux 映像助理 CLI 工具不支援此操作。

**概要**

```
update-default-profile
[--profile <value>]
```

**選項**

**`--profile` (string)**  
要將其 Windows 描述檔複製到 Windows 預設使用者描述檔的使用者名稱。使用下列名稱格式：  
"<domain>\$1<username>"  
如果映像建置器未加入 Microsoft Active Directory 網域，請在網域中輸入句號「.」。如果您未指定使用者，則會使用 WorkSpaces 應用程式範本使用者帳戶。

**訊息輸出**


| 結束程式碼 | 列印為標準輸出的訊息 | Description | 
| --- | --- | --- | 
| 0 |  \$1"狀態": 0, "訊息": "成功"\$1  |  已成功將使用者設定複製到預設的 Windows 描述檔。 | 
| 1 |  \$1"狀態": 1, "訊息": "需要管理員權限才能執行此操作"\$1  |  需要管理員權限才能完成此操作。 | 
| 1 |  \$1"狀態": 1, "訊息": "無法複製檔案或資料夾：<path>。<reason>"\$1  |  檔案或資料夾無法使用，因此無法複製使用者設定。 | 
| 1 |  \$1"狀態": 1, "訊息": "未加入網域時，無法複製網域使用者""\$1  |  已指定 Microsoft Active Directory 網域使用者，但映像建置器未加入 Active Directory 網域。 | 
| 255 |  \$1"狀態": 255, "訊息": <error message>\$1  |  發生未預期的錯誤。再次嘗試請求。如果錯誤仍然存在，請聯絡 AWS 支援 尋求協助。如需詳細資訊，請參閱 [AWS 支援 中心](https://console.aws.amazon.com/support/home#/)。 | 

## `reset-user-profile` 操作
<a name="reset-user-profile-image-assistant-cli"></a>

刪除指定使用者的 Windows 使用者描述檔。

**注意**  
Linux 映像助理 CLI 工具不支援此操作。

**概要**

```
reset-user-profile
[--profile <value>]
```

**選項**

**`--profile` (string)**  
其 Windows 描述檔將遭到刪除的 Windows 使用者名稱。使用下列名稱格式：  
"<domain>\$1<username>"  
如果映像建置器未加入 Microsoft Active Directory 網域，請在網域中輸入句號「.」。

**訊息輸出**


| 結束程式碼 | 列印為標準輸出的訊息 | Description | 
| --- | --- | --- | 
| 0 |  \$1"狀態": 0, "訊息": "成功"\$1  |  已成功刪除指定的使用者設定。 | 
| 1 |  \$1"狀態": 1, "訊息": "需要管理員權限才能執行此操作"\$1  |  需要管理員權限才能完成此操作。 | 
| 1 |  \$1"狀態": 1, "訊息": "無法複製檔案或資料夾：<path>。<reason>"\$1  |  檔案或資料夾無法使用，因此無法重設使用者設定。 | 
| 1 |  \$1"狀態": 1, "訊息": "未加入網域時，無法複製網域使用者""\$1  |  已指定 Microsoft Active Directory 網域使用者，但映像建置器未加入 Active Directory 網域。 | 
| 255 |  \$1"狀態": 255, "訊息": <error message>\$1  |  發生未預期的錯誤。再次嘗試請求。如果錯誤仍然存在，請聯絡 AWS 支援 尋求協助。如需詳細資訊，請參閱 [AWS 支援 中心](https://console.aws.amazon.com/support/home#/)。 | 

## `create-image` 操作
<a name="create-image-operation-image-assistant-cli"></a>

啟動映像建立工作流程，產生可用於 WorkSpaces 應用程式機群的 WorkSpaces 應用程式映像。

**概要**

```
create-image
--name <value>
[--description <value>]
[--display-name <value>]
[--enable-dynamic-app-catalog] | [--no-enable-dynamic-app-catalog]
[--use-latest-agent-version] | [--no-use-latest-agent-version]            
[--tags <value>]
[--dry-run]
```

**選項**

**`--name` (string)**  
WorkSpaces 應用程式映像的名稱。名稱在 Amazon Web Services 帳戶和 AWS 區域中必須是唯一的。長度上限為 100 個字元。允許的字元如下：  
a-z、A-Z、0-9、底線 (\$1)、連字號 (-) 和句號 (.)  
映像名稱不得以下列任何前綴為開頭：「aws」、「appstream」及「amazon」。這些字首已保留給 AWS 使用。

**`--description` (string)**  
要顯示的映像描述。長度上限為 256 個字元。

**`--display-name` (string)**  
要顯示的映像名稱。長度上限為 256 個字元。

**`--enable-dynamic-app-catalog` \$1 `--no-enable-dynamic-app-catalog`**  
啟用或停用 WorkSpaces 應用程式動態應用程式架構的支援。如果您沒有指定參數，則不會啟用對動態應用程式架構的支援。  
動態應用程式架構提供 WorkSpaces 應用程式串流執行個體內的操作，您可用來建置動態應用程式提供者。動態應用程式提供者可使用這些操作，來修改使用者可以即時存取的應用程式型錄。如需詳細資訊，請參閱[使用 WorkSpaces 應用程式動態應用程式架構來建置動態應用程式提供者](build-dynamic-app-provider.md)。

**`--use-latest-agent-version` \$1 `--no-use-latest-agent-version`**  
指定要將映像鎖定到目前安裝的 WorkSpaces 應用程式代理程式版本，還是一律使用最新的代理程式版本。如果您未指定任一參數，映像會固定到目前安裝的 WorkSpaces 應用程式代理程式版本。如需詳細資訊，請參閱[管理 WorkSpaces 應用程式代理程式版本](base-images-agent.md)。

**`--tags` (string)**  
要與此映像關聯的標籤。標籤是索引鍵值組。使用下列格式：  
--tags "mykey" "myval" "mykey2" "myval2"  
如需標籤的詳細資訊，請參閱[標記 Amazon WorkSpaces 應用程式資源](tagging-basic.md)。

**`--dry-run` (string)**  
執行驗證，但不建立映像。使用此命令來在建立映像前識別其中是否有任何問題。

**訊息輸出**


| 結束程式碼 | 列印為標準輸出的訊息 | Description | 
| --- | --- | --- | 
| 0 |  \$1"狀態": 0, "訊息": "成功"\$1  |  已成功啟動建立映像的工作流程。 | 
| 1 |  \$1"狀態": 1, "訊息": "需要管理員權限才能執行此操作"\$1  |  需要管理員權限才能完成此操作。 | 
| 1 |  \$1"狀態": 1, "訊息": "具指定名稱的映像已存在"\$1  |  Amazon Web Services 帳戶中已有此指定名稱的映像。 | 
| 1 |  \$1"狀態": 1, "訊息": "無效值 (標籤)"\$1  |  指定的標籤無效。 | 
| 255 |  \$1"狀態": 255, "訊息": <error message>\$1  |  發生未預期的錯誤。再次嘗試請求。如果錯誤仍然存在，請聯絡 AWS 支援 尋求協助。如需詳細資訊，請參閱 [AWS 支援 中心](https://console.aws.amazon.com/support/home#/)。 |