建立和發佈自訂 Azure Stack Hub Marketplace 項目Create and publish a custom Azure Stack Hub Marketplace item

發佈至 Azure Stack Hub Marketplace 的每個項目都會使用 Azure 資源庫套件 (.azpkg) 格式。Every item published to the Azure Stack Hub Marketplace uses the Azure Gallery Package (.azpkg) format. Azure Gallery Packager 工具可讓您建立自訂的 Azure 資源庫套件,且您可以將此套件上傳至 Azure Stack Hub Marketplace,供使用者下載。The Azure Gallery Packager tool enables you to create a custom Azure Gallery package that you can upload to the Azure Stack Hub Marketplace, which can then be downloaded by users. 部署程序會使用 Azure Resource Manager 範本。The deployment process uses an Azure Resource Manager template.

Marketplace 項目Marketplace items

本文中的範例說明如何建立 Windows 或 Linux 類型的單一 VM Marketplace 供應項目。The examples in this article show how to create a single VM Marketplace offer, of type Windows or Linux.

必要條件Prerequisites

在建立 VM marketplace 專案之前,請執行下列動作:Before creating the VM marketplace item, do the following:

  1. 遵循 將 vm 映射新增至 Azure Stack Hub中的指示,將自訂 vm 映射上傳至 Azure Stack Hub 入口網站。Upload the custom VM image to the Azure Stack Hub portal, following the instructions in Add a VM image to Azure Stack Hub.
  2. 遵循本文中的指示封裝映射 (建立 .azpkg) 並將其上傳至 Azure Stack Hub Marketplace。Follow the instructions in this article to package the image (create an .azpkg) and upload it to the Azure Stack Hub Marketplace.

建立 Marketplace 項目Create a Marketplace item

若要建立自訂 Marketplace 項目,請執行下列動作:To create a custom marketplace item, do the following:

  1. 下載 Azure Gallery Packager 工具和範例 Azure Stack Hub 資源庫套件。Download the Azure Gallery Packager tool and the sample Azure Stack Hub gallery package. 此下載包含自訂 VM 範本。This download includes custom VM templates. 將 .zip 檔案解壓縮,且在 [自訂 VM] 資料夾底下,您可以使用可用的 Linux 或 Windows 範本。Extract the .zip file, and under the folder Custom VMs, you can use either the Linux or the Windows templates that are available. 您可以決定重複使用預先製作的範本,並以您將在 Azure Stack Hub 入口網站上顯示項目的產品詳細資料,修改各自的參數。You can decide to re-use the pre-made templates and modify the respective parameters with the product details of the item that you will show on your Azure Stack Hub portal. 或者,您可以直接重複使用 .azpkg 檔案,並略過下列步驟來自訂自己的資源庫套件。Or, you can simply re-use the .azpkg file available and skip the following steps to customize your own gallery package.

  2. 建立 Azure Resource Manager 範本,或使用我們針對 Windows/Linux 提供的範例範本。Create an Azure Resource Manager template or use our sample templates for Windows/Linux. 這些範例範本會提供於您在步驟 1 下載的封裝工具 .zip 檔案中。These sample templates are provided in the packager tool .zip file you downloaded in step 1. 您可以使用範本並變更文字欄位,也可以從 GitHub 下載預先設定的範本。You can either use the template and change the text fields, or you can download a pre-configured template from GitHub. 如需 Azure Resource Manager 範本的詳細資訊,請參閱 Azure Resource Manager 範本For more information about Azure Resource Manager templates, see Azure Resource Manager templates.

  3. 資源庫套件應包含下列結構:The Gallery package should contain the following structure:

    資源庫套件結構的螢幕擷取畫面

    部署範本檔案結構會顯示如下:The deployment templates file structure appears as follows:

    部署範本結構的螢幕擷取畫面

  4. 將下列在 Manifest.json 範本中醒目提示的值 (具有數字的值),取代為您在上傳自訂映像時所提供的值。Replace the following highlighted values (those with numbers) in the Manifest.json template with the value that you provided when uploading your custom image.

    注意

    絕對不要硬式編碼任何祕密 (例如 Azure Resource Manager 範本中的產品金鑰、密碼或任何客戶識別資訊)。Never hard code any secrets such as product keys, password, or any customer identifiable information in the Azure Resource Manager template. 範本 JSON 檔案只要發佈至資源庫就可供存取,而不需要驗證。Template JSON files are accessible without the need for authentication once published in the gallery. 將所有祕密都儲存至 Key Vault,並從範本呼叫它們。Store all secrets in Key Vault and call them from within the template.

    建議您在發佈自己的自訂範本之前,先嘗試依原樣發佈範例,並確定它可以在您的環境中運作。It's recommended that before publishing your own custom template, you try to publish the sample as-is and make sure it works in your environment. 當您確認這個步驟可行之後,請從圖庫刪除範例,並進行反復的變更,直到您對結果感到滿意為止。Once you've verified this step works, then delete the sample from gallery and make iterative changes until you are satisfied with the result.

    以下範本是 Manifest.json 檔案的範例:The following template is a sample of the Manifest.json file:

    {
       "$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"
             }]
        }]
    }
    

    下列清單說明範例範本中的前述編號值:The following list explains the preceding numbered values in the example template:

    • (1) -供應專案的名稱。(1) - The name of the offer.
    • (2) -發行者的名稱,不含空格。(2) - The name of the publisher, without a space.
    • (3) -您的範本版本,不含空格。(3) - The version of your template, without a space.
    • (4) -客戶看到的名稱。(4) - The name that customers see.
    • (5) -客戶看到的發行者名稱。(5) - The publisher name that customers see.
    • (6) -發行者法定名稱。(6) - The publisher legal name.
    • (7) -每個圖示的路徑和名稱。(7) - The path and name for each icon.
  5. 針對所有參考 ms-resource 的欄位,您必須在 strings/resources.json 檔案內變更適當的值:For all fields referring to ms-resource, you must change the appropriate values inside the strings/resources.json file:

    {
    "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"
    }
    
  6. 若要確定可以成功部署資源,請使用 Azure Stack Hub API 來測試範本。To ensure that the resource can be deployed successfully, test the template with the Azure Stack Hub APIs.

  7. 如果範本仰賴虛擬機器 (VM) 映像,請遵循指示來將 VM 映像新增至 Azure Stack HubIf your template relies on a virtual machine (VM) image, follow the instructions to add a VM image to Azure Stack Hub.

  8. 將 Azure Resource Manager 範本儲存在 /Contoso.TodoList/DeploymentTemplates/ 資料夾中。Save your Azure Resource Manager template in the /Contoso.TodoList/DeploymentTemplates/ folder.

  9. 選擇您的 Marketplace 項目的圖示和文字。Choose the icons and text for your Marketplace item. 將圖示新增至 Icons 資料夾,以及將文字新增至 Strings 資料夾的 resources 檔案中。Add icons to the Icons folder, and add text to the resources file in the Strings folder. 針對圖示使用 smallmediumlargewide 命名慣例。Use the small, medium, large, and wide naming convention for icons. 如需這些大小的詳細說明,請參閱 Marketplace 項目 UI 參考See the Marketplace item UI reference for a detailed description of these sizes.

    注意

    需要全部四個圖示大小 (小、中、大、寬) 才能正確建立 Marketplace 項目。All four icon sizes (small, medium, large, wide) are required for building the Marketplace item correctly.

  10. 若要對 Manifest.json 進行任何進一步的編輯,請參閱參考:Marketplace 項目 manifest.jsonFor any further edits to Manifest.json, see Reference: Marketplace item manifest.json.

  11. 完成檔案的修改後,請將其轉換成 .azpkg 檔案。When you finish modifying your files, convert it to an .azpkg file. 您可以使用 AzureGallery.exe 工具以及您先前下載的範例資源庫套件來執行轉換。You perform the conversion using the AzureGallery.exe tool and the sample gallery package you downloaded previously. 執行以下命令:Run the following command:

    .\AzureGallery.exe package -m c:\<path>\<gallery package name>\manifest.json -o c:\Temp
    

    注意

    輸出路徑可以是您選擇的任何路徑,且不一定要位於 C: 磁碟機下。The output path can be any path you choose, and does not have to be under the C: drive. 但 manifest.json 檔案和輸出套件都必須有完整路徑存在。However, the full path to both the manifest.json file, and the output package, must exist. 例如,如果輸出路徑為 C:\<path>\galleryPackageName.azpkg,則必須有 C:\<path> 資料夾存在。For example, if the output path is C:\<path>\galleryPackageName.azpkg, the folder C:\<path> must exist.

發佈 Marketplace 項目Publish a Marketplace item

  1. 使用 PowerShell 或 Azure 儲存體總管來將您的 Marketplace 項目 (.azpkg) 上傳至 Azure Blob 儲存體。Use PowerShell or Azure Storage Explorer to upload your Marketplace item (.azpkg) to Azure Blob storage. 您可以上傳至本機 Azure Stack Hub 儲存體或上傳至 Azure 儲存體,其為套件的暫時性位置。You can upload to local Azure Stack Hub storage or upload to Azure Storage, which is a temporary location for the package. 請確定 Blob 可公開存取。Make sure that the blob is publicly accessible.

  2. 若要將資源庫套件匯入 Azure Stack Hub 中,首先必須從遠端連線 (RDP) 至用戶端 VM,以將您剛才建立的檔案複製到 Azure Stack Hub。To import the gallery package into Azure Stack Hub, the first step is to remotely connect (RDP) to the client VM, in order to copy the file you just created to your Azure Stack Hub.

  3. 新增內容:Add a context:

    $ArmEndpoint = "https://adminmanagement.local.azurestack.external"
    Add-AzEnvironment -Name "AzureStackAdmin" -ArmEndpoint $ArmEndpoint
    Connect-AzAccount -EnvironmentName "AzureStackAdmin"
    
  4. 執行下列指令碼,將資源匯入您的資源庫中:Run the following script to import the resource into your gallery:

    Add-AzsGalleryItem -GalleryItemUri `
    https://sample.blob.core.windows.net/<temporary blob name>/<offerName.publisherName.version>.azpkg -Verbose
    
  5. 確認您有有效的儲存體帳戶可用來儲存您的項目。Verify that you have a valid Storage account that is available to store your item. 您可以從 Azure Stack Hub 系統管理員入口網站取得 GalleryItemURI 值。You can get the GalleryItemURI value from the Azure Stack Hub administrator portal. 選取 [儲存體帳戶] > [Blob 屬性] -> [URL],副檔名為 .azpkg。Select Storage account -> Blob Properties -> URL, with the extension .azpkg. 儲存體帳戶僅供暫時使用,以便發佈至 Marketplace。The storage account is only for temporary use, in order to publish to the marketplace.

    完成您的資源庫套件,並使用 Add-AzsGalleryItem 加以上傳後,您的自訂 VM 現在應該會出現在 Marketplace 上,以及 [建立資源] 檢視中。After completing your gallery package and uploading it using Add-AzsGalleryItem, your custom VM should now appear on the Marketplace as well as in the Create a resource view. 請注意,[Marketplace 管理] 中不會顯示自訂資源庫套件。Note that the custom gallery package is not visible in Marketplace Management.

    已上傳的自訂市集項目Custom marketplace item uploaded

  6. 在您的項目成功發佈至 Marketplace 之後,您就可以從儲存體帳戶中刪除內容。Once your item has been successfully published to the marketplace, you can delete the content from the storage account.

    現在,透過下列 URL,可以未經驗證存取所有預設資源庫成品和您的自訂資源庫成品:All default gallery artifacts and your custom gallery artifacts are now accessible without authentication under the following URLs:

    • https://galleryartifacts.adminhosting.[Region].[externalFQDN]/artifact/20161101/[TemplateName]/DeploymentTemplates/Template.json
    • https://galleryartifacts.hosting.[Region].[externalFQDN]/artifact/20161101/[TemplateName]/DeploymentTemplates/Template.json
  7. 您可以使用 AzGalleryItem Cmdlet 來移除 Marketplace 專案。You can remove a Marketplace item by using the Remove-AzGalleryItem cmdlet. 例如:For example:

    Remove-AzsGalleryItem -Name <Gallery package name> -Verbose
    

注意

移除項目之後,Marketplace UI 可能會顯示錯誤。The Marketplace UI may show an error after you remove an item. 若要修正錯誤,請按一下入口網站中的 [設定]。To fix the error, click Settings in the portal. 然後,在 [入口網站自訂] 之下,選取 [捨棄修改]。Then, select Discard modifications under Portal customization.

參考:Marketplace 項目 manifest.jsonReference: Marketplace item manifest.json

身分識別資訊Identity information

名稱Name 必要Required 類型Type 條件約束Constraints 描述Description
名稱Name XX StringString [A-a-za-z0-9] +[A-Za-z0-9]+
發行者Publisher XX StringString [A-a-za-z0-9] +[A-Za-z0-9]+
版本Version XX StringString SemVer v2SemVer v2

中繼資料Metadata

名稱Name 必要Required 類型Type 條件約束Constraints 描述Description
DisplayNameDisplayName XX StringString 建議 80 個字元Recommendation of 80 characters 如果超過 80 個字元,入口網站可能無法正確顯示項目名稱。The portal might not display your item name correctly if it's longer than 80 characters.
PublisherDisplayNamePublisherDisplayName XX StringString 建議 30 個字元Recommendation of 30 characters 如果超過 30 個字元,入口網站可能無法正確顯示發行者名稱。The portal might not display your publisher name correctly if it's longer than 30 characters.
PublisherLegalNamePublisherLegalName XX StringString 上限 256 個字元Maximum of 256 characters
摘要Summary XX StringString 60 到 100 個字元60 to 100 characters
LongSummaryLongSummary XX StringString 140 到 256 個字元140 to 256 characters 目前在 Azure Stack Hub 中不適用。Not yet applicable in Azure Stack Hub.
描述Description XX HTMLHTML 500 到 5,000 個字元500 to 5,000 characters

影像Images

Marketplace 會使用下列圖示:The Marketplace uses the following icons:

名稱Name 寬度Width 高度Height 注意Notes
Wide 255 像素255 px 115 像素115 px 一律需要Always required
大型Large 115 像素115 px 115 像素115 px 一律需要Always required
Medium 90 像素90 px 90 像素90 px 一律需要Always required
小型Small 40 像素40 px 40 像素40 px 一律需要Always required
螢幕擷取畫面Screenshot 533 像素533 px 324 像素324 px 選用Optional

類別Categories

每個 Marketplace 項目應該以可識別項目出現在入口網站 UI 上位置的類別加以標記。Each Marketplace item should be tagged with a category that identifies where the item appears on the portal UI. 您可以在 Azure Stack Hub 中選擇其中一個現有的類別 (計算資料 + 儲存體 等等) 或選擇新的類別。You can choose one of the existing categories in Azure Stack Hub (Compute, Data + Storage, and so on) or choose a new one.

每個 Marketplace 項目可以包含各種其他內容的連結。Each Marketplace item can include various links to additional content. 連結是以名稱與 URI 清單的形式指定:The links are specified as a list of names and URIs:

名稱Name 必要Required 類型Type 條件約束Constraints 描述Description
DisplayNameDisplayName XX StringString 上限 64 個字元。Maximum of 64 characters.
UriUri XX URIURI

其他屬性Additional properties

除了前述中繼資料,Marketplace 作者可以下列形式提供自訂的成對索引鍵/值資料:In addition to the preceding metadata, Marketplace authors can provide custom key/value pair data in the following form:

名稱Name 必要Required 類型Type 條件約束Constraints 描述Description
DisplayNameDisplayName XX StringString 上限 25 個字元。Maximum of 25 characters.
Value XX StringString 上限 30 個字元。Maximum of 30 characters.

HTML 病毒掃描HTML sanitization

任何可使用 HTML 的欄位,都可以使用下列項目與屬性For any field that allows HTML, the following elements and attributes are allowed:

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

參考:Marketplace 項目 UIReference: Marketplace item UI

在 Azure Stack Hub 入口網站中所看見 Marketplace 項目的圖示和文字如下所示。Icons and text for Marketplace items as seen in the Azure Stack Hub portal are as follows.

建立刀鋒視窗Create blade

建立刀鋒視窗 - Azure Stack Hub Marketplace 項目

Marketplace 項目詳細資料刀鋒視窗Marketplace item details blade

Azure Stack Hub Marketplace 項目詳細資料刀鋒視窗

後續步驟Next steps