建立和發佈自訂 Azure Stack Hub Marketplace 項目

發行項
03/29/2024

發佈至 Azure Stack Hub Marketplace 的每個項目都會使用 Azure 資源庫套件 (.azpkg) 格式。 Azure Gallery Packager 工具可讓您建立自訂的 Azure 資源庫套件，且您可以將此套件上傳至 Azure Stack Hub Marketplace，供使用者下載。部署程序會使用 Azure Resource Manager 範本。

Marketplace 項目

本文中的範例說明如何建立 Windows 或 Linux 類型的單一 VM Marketplace 供應項目。

必要條件

建立 VM Marketplace 項目之前，請執行下列動作：

將自訂 VM 映像上傳至 Azure Stack Hub 入口網站，並依照將 VM 映像新增至 Azure Stack Hub 中的指示進行。
依照本文中的指示封裝映像 (建立 .azpkg)，並將其上傳至 Azure Stack Hub Marketplace。

建立 Marketplace 項目

若要建立自訂 Marketplace 項目，請執行下列動作：

下載 Azure Gallery Packager 工具：
該工具包含 .azpkg 格式的範例套件，必須先解壓縮。您可以將副檔名從 ".azpkg" 重新命名為 ".zip"，或使用您選擇的封存工具：
解壓縮之後，.zip 檔案包含可用的 Linux 或 Windows Azure Resource Manager 範本。您可以重複使用預先製作的 Resource Manager 範本，並以您將在 Azure Stack Hub 入口網站上顯示項目的產品詳細資料，修改各自的參數。或者，您可以重複使用 .azpkg 檔案，並略過下列步驟來自訂自己的資源庫套件。
建立 Azure Resource Manager 範本，或使用我們針對 Windows/Linux 提供的範例範本。這些範例範本會提供於您在步驟 1 下載的封裝工具 .zip 檔案中。您可以使用範本並變更文字欄位，也可以從 GitHub 下載預先設定的範本。如需 Azure Resource Manager 範本的詳細資訊，請參閱 Azure Resource Manager 範本。
資源庫套件應包含下列結構：

將下列在 Manifest.json 範本中醒目提示的值 (具有數字的值)，取代為您在上傳自訂映像時所提供的值。

注意

絕對不要硬式編碼任何祕密 (例如 Azure Resource Manager 範本中的產品金鑰、密碼或任何客戶識別資訊)。範本 JSON 檔案只要發佈至資源庫就可供存取，而不需要驗證。將所有祕密都儲存至 Key Vault，並從範本呼叫它們。

建議您在發佈自己的自訂範本之前，先嘗試依原狀發佈範例，並確定其可以在您的環境中運作。確認此步驟可行之後，請從資源庫刪除範例，並進行反覆變更，直到您對結果感到滿意為止。

以下範本是 Manifest.json 檔案的範例：

{
   "$schema": "https://gallery.azure.com/schemas/2015-10-01/manifest.json#",
   "name": "Test", (1)
   "publisher": "<Publisher name>", (2)
   "version": "<Version number>", (3)
   "displayName": "ms-resource:displayName", (4)
   "publisherDisplayName": "ms-resource:publisherDisplayName", (5)
   "publisherLegalName": "ms-resource:publisherDisplayName", (6)
   "summary": "ms-resource:summary",
   "longSummary": "ms-resource:longSummary",
   "description": "ms-resource:description",
   "longDescription": "ms-resource:description",
   "links": [
    { "displayName": "ms-resource:documentationLink", "uri": "http://go.microsoft.com/fwlink/?LinkId=532898" }
    ],
   "artifacts": [
      {
         "isDefault": true
      }
   ],
   "images": [{
      "context": "ibiza",
      "items": [{
         "id": "small",
         "path": "icons\\Small.png", (7)
         "type": "icon"
         },
         {
            "id": "medium",
            "path": "icons\\Medium.png",
            "type": "icon"
         },
         {
            "id": "large",
            "path": "icons\\Large.png",
            "type": "icon"
         },
         {
            "id": "wide",
            "path": "icons\\Wide.png",
            "type": "icon"
         }]
    }]
}

下列清單說明範例範本中的前述編號值：

(1) - 供應項目的名稱。
(2) - 發行者的名稱，不含空格。
(3) - 您的範本版本，不含空格。
(4) - 客戶看到的名稱。
(5) - 客戶看到的發行者名稱。
(6) - 發行者法定名稱。
(7) - 每個圖示的路徑和名稱。

針對所有參考 ms-resource 的欄位，您必須在 strings/resources.json 檔案內變更適當的值：

{
"displayName": "<OfferName.PublisherName.Version>",
"publisherDisplayName": "<Publisher name>",
"summary": "Create a simple VM",
"longSummary": "Create a simple VM and use it",
"description": "<p>This is just a sample of the type of description you could create for your gallery item!</p><p>This is a second paragraph.</p>",
"documentationLink": "Documentation"
}

部署範本檔案結構會顯示如下：

將 createuidefinition.json 檔案中的映像值取代為您上傳自訂映像時所提供的值。
若要確定可以成功部署資源，請使用 Azure Stack Hub API 來測試範本。
如果範本仰賴虛擬機器 (VM) 映像，請遵循指示來將 VM 映像新增至 Azure Stack Hub。
將 Azure Resource Manager 範本儲存在 /Contoso.TodoList/DeploymentTemplates/ 資料夾中。
選擇您的 Marketplace 項目的圖示和文字。將圖示新增至 Icons 資料夾，以及將文字新增至 Strings 資料夾的 resources 檔案中。針對圖示使用 small、medium、large 和 wide 命名慣例。如需這些大小的詳細說明，請參閱 Marketplace 項目 UI 參考。

注意

需要全部四個圖示大小 (小、中、大、寬) 才能正確建立 Marketplace 項目。
若要對 Manifest.json 進行任何進一步的編輯，請參閱參考：Marketplace 項目 manifest.json。
完成檔案的修改後，請將其轉換成 .azpkg 檔案。您可以使用 AzureGallery.exe 工具以及您先前下載的範例資源庫套件來執行轉換。執行以下命令：
```
.\AzureStackHubGallery.exe package -m c:\<path>\<gallery package name>\manifest.json -o c:\Temp
```
注意

輸出路徑可以是您選擇的任何路徑，且不一定要位於 C: 磁碟機下。但 manifest.json 檔案和輸出套件都必須有完整路徑存在。例如，如果輸出路徑為 C:\<path>\galleryPackageName.azpkg，則必須有 C:\<path> 資料夾存在。

使用 PowerShell 或 Azure 儲存體總管來將您的 Marketplace 項目 (.azpkg) 上傳至 Azure Blob 儲存體。您可以上傳至本機 Azure Stack Hub 儲存體或上傳至 Azure 儲存體，其為套件的暫時性位置。請確定 Blob 可公開存取。
若要將資源庫套件匯入 Azure Stack Hub 中，首先必須從遠端連線 (RDP) 至用戶端 VM，以將您剛才建立的檔案複製到 Azure Stack Hub。

新增內容：

$ArmEndpoint = "https://adminmanagement.local.azurestack.external"
Add-AzEnvironment -Name "AzureStackAdmin" -ArmEndpoint $ArmEndpoint
Connect-AzAccount -EnvironmentName "AzureStackAdmin"

執行下列指令碼，將資源匯入您的資源庫中：
```
Add-AzsGalleryItem -GalleryItemUri `
https://sample.blob.core.windows.net/<temporary blob name>/<offerName.publisherName.version>.azpkg -Verbose
```
如果您在執行 Add-AzsGalleryItem 時發生錯誤，您可能已安裝兩個版本的 gallery.admin 模組。請移除模組的所有版本，並安裝最新版本。如需解除安裝 PowerShell 模組的步驟，請參閱解除安裝現有的 Azure Stack Hub PowerShell 模組版本。
確認您有有效的儲存體帳戶可用來儲存您的項目。您可以從 Azure Stack Hub 系統管理員入口網站取得 GalleryItemURI 值。選取 [儲存體帳戶] -> [Blob 屬性] -> [URL]，副檔名為 .azpkg。儲存體帳戶僅供暫時使用，以便發佈至 Marketplace。

完成您的資源庫套件，並使用 Add-AzsGalleryItem 加以上傳後，您的自訂 VM 現在應該會出現在 Marketplace 上，以及 [建立資源] 檢視中。請注意，[Marketplace 管理] 中不會顯示自訂資源庫套件。
在您的項目成功發佈至 Marketplace 之後，您就可以從儲存體帳戶中刪除內容。

現在，透過下列 URL，可以未經驗證存取所有預設資源庫成品和您的自訂資源庫成品：
- https://galleryartifacts.adminhosting.[Region].[externalFQDN]/artifact/20161101/[TemplateName]/DeploymentTemplates/Template.json
- https://galleryartifacts.hosting.[Region].[externalFQDN]/artifact/20161101/[TemplateName]/DeploymentTemplates/Template.json
您可以使用 Remove-AzGalleryItem Cmdlet 來移除 Marketplace 項目。例如：
```
Remove-AzsGalleryItem -Name <Gallery package name> -Verbose
```

注意

移除項目之後，Marketplace UI 可能會顯示錯誤。若要修正錯誤，請按一下入口網站中的 [設定]。然後，在 [入口網站自訂] 之下，選取 [捨棄修改]。

使用 PowerShell 或 Azure 儲存體總管來將您的 Marketplace 項目 (.azpkg) 上傳至 Azure Blob 儲存體。您可以上傳至本機 Azure Stack Hub 儲存體或上傳至 Azure 儲存體，其為套件的暫時性位置。請確定 Blob 可公開存取。
若要將資源庫套件匯入 Azure Stack Hub 中，首先必須從遠端連線 (RDP) 至用戶端 VM，以將您剛才建立的檔案複製到 Azure Stack Hub。

新增內容：

$ArmEndpoint = "https://adminmanagement.local.azurestack.external"
Add-AzureRMEnvironment -Name "AzureStackAdmin" -ArmEndpoint $ArmEndpoint
Add-AzureRMAccount -EnvironmentName "AzureStackAdmin"

執行下列指令碼，將資源匯入您的資源庫中：
```
Add-AzsGalleryItem -GalleryItemUri `
https://sample.blob.core.windows.net/<temporary blob name>/<offerName.publisherName.version>.azpkg -Verbose
```
如果您在執行 Add-AzsGalleryItem 時發生錯誤，您可能已安裝兩個版本的 gallery.admin 模組。請移除模組的所有版本，並安裝最新版本。如需解除安裝 PowerShell 模組的步驟，請參閱解除安裝現有的 Azure Stack Hub PowerShell 模組版本。
確認您有有效的儲存體帳戶可用來儲存您的項目。您可以從 Azure Stack Hub 系統管理員入口網站取得 GalleryItemURI 值。選取 [儲存體帳戶] -> [Blob 屬性] -> [URL]，副檔名為 .azpkg。儲存體帳戶僅供暫時使用，以便發佈至 Marketplace。

完成您的資源庫套件，並使用 Add-AzsGalleryItem 加以上傳後，您的自訂 VM 現在應該會出現在 Marketplace 上，以及 [建立資源] 檢視中。請注意，[Marketplace 管理] 中不會顯示自訂資源庫套件。
在您的項目成功發佈至 Marketplace 之後，您就可以從儲存體帳戶中刪除內容。

現在，透過下列 URL，可以未經驗證存取所有預設資源庫成品和您的自訂資源庫成品：
- https://galleryartifacts.adminhosting.[Region].[externalFQDN]/artifact/20161101/[TemplateName]/DeploymentTemplates/Template.json
- https://galleryartifacts.hosting.[Region].[externalFQDN]/artifact/20161101/[TemplateName]/DeploymentTemplates/Template.json
您可以使用 Remove-AzGalleryItem Cmdlet 來移除 Marketplace 項目。例如：
```
Remove-AzsGalleryItem -Name <Gallery package name> -Verbose
```

注意

移除項目之後，Marketplace UI 可能會顯示錯誤。若要修正錯誤，請按一下入口網站中的 [設定]。然後，在 [入口網站自訂] 之下，選取 [捨棄修改]。

參考：Marketplace 項目 manifest.json

身分識別資訊

名稱	必要	類型	條件約束
名稱	X	String	[A-a-za-z0-9] +
發行者	X	String	[A-a-za-z0-9] +
版本	X	String	SemVer v2

中繼資料

名稱	必要	類型	條件約束	描述
DisplayName	X	String	建議 80 個字元	如果超過 80 個字元，入口網站可能無法正確顯示項目名稱。
PublisherDisplayName	X	String	建議 30 個字元	如果超過 30 個字元，入口網站可能無法正確顯示發行者名稱。
PublisherLegalName	X	String	上限 256 個字元
摘要	X	String	60 到 100 個字元
LongSummary	X	String	140 到 256 個字元	目前在 Azure Stack Hub 中不適用。
描述	X	HTML	500 到 5,000 個字元

影像

Marketplace 會使用下列圖示：

名稱	寬度	高度	注意
寬	255 像素	115 像素	一律需要
大型	115 像素	115 像素	一律需要
中	90 像素	90 像素	一律需要
小型	40 像素	40 像素	一律需要
螢幕擷取畫面	533 像素	324 像素	選用

類別

每個 Marketplace 項目應該以可識別項目出現在入口網站 UI 上位置的類別加以標記。您可以在 Azure Stack Hub 中選擇其中一個現有的類別 (計算、資料 + 儲存體等等) 或選擇新的類別。

連結

每個 Marketplace 項目可以包含各種其他內容的連結。連結是以名稱與 URI 清單的形式指定：

名稱	必要	類型	條件約束	描述
DisplayName	X	String	上限 64 個字元。
Uri	X	URI

其他屬性

除了前述中繼資料，Marketplace 作者可以下列形式提供自訂的成對索引鍵/值資料：

名稱	必要	類型	條件約束	描述
DisplayName	X	String	上限 25 個字元。
值	X	String	上限 30 個字元。

HTML 病毒掃描

任何可使用 HTML 的欄位，都可以使用下列項目與屬性：

h1, h2, h3, h4, h5, p, ol, ul, li, a[target|href], br, strong, em, b, i

參考：Marketplace 項目 UI

在 Azure Stack Hub 入口網站中所看見 Marketplace 項目的圖示和文字如下所示。