创建并发布自定义 Azure Stack Hub 市场项Create and publish a custom Azure Stack Hub Marketplace item

发布到 Azure Stack Hub 市场的每个项都使用 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 市场供用户下载。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 资源管理器模板。The deployment process uses an Azure Resource Manager template.

市场项Marketplace items

本文中的示例演示如何创建 Windows 或 Linux 类型的单个 VM 市场套餐。The examples in this article show how to create a single VM Marketplace offer, of type Windows or Linux.

创建市场项Create a Marketplace item

Important

在创建 VM 市场项之前,请将自定义 VM 映像上传到 Azure Stack Hub 门户,并根据将 VM 映像添加到 Azure Stack Hub 中的说明操作。Before creating the VM marketplace item, upload the custom VM image to the Azure Stack Hub portal, following the instructions in Add a VM image to Azure Stack Hub. 然后,根据本文中的说明打包映像(创建 .azpkg),并将其上传到 Azure Stack Hub 市场。Then, follow the instructions in this article to package the image (create an .azpkg) and upload it to the Azure Stack Hub 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 文件,在文件夹 Custom VMs 下,可以使用适用的 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 资源管理器模板,或使用适用于 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 资源管理器模板的详细信息,请参阅 Azure 资源管理器模板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.

    Note

    切勿对 Azure 资源管理器模板中的任何机密(例如产品密钥、密码或任何客户身份信息)进行硬编码。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.

    以下模板是 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",
       "uiDefinition": {
          "path": "UIDefinition.json" (7)
          },
       "links": [
        { "displayName": "ms-resource:documentationLink", "uri": "https://docs.azure.cn/zh-cn/azure-resource-manager/resource-group-authoring-templates" }
        ],
       "artifacts": [
          {
             "name": "<Template name>",
             "type": "Template",
             "path": "DeploymentTemplates\\<Template name>.json", (8)
             "isDefault": true
          }
       ],
       "categories":[ (9)
          "Custom",
          "<Template name>"
          ],
       "images": [{
          "context": "ibiza",
          "items": [{
             "id": "small",
             "path": "icons\\Small.png", (10)
             "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) - UIDefinition.json 文件的存储路径。(7) - The path to where your UIDefinition.json file is stored.
    • (8) - JSON 主模板文件的路径和名称。(8) - The path and the name of your JSON main template file.
    • (9) - 显示此模板的类别的名称。(9) - The names of the categories in which this template is displayed.
    • (10) - 每个图标的路径和名称。(10) - 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"
    }
    

    包显示 包显示Package display Package display

  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. 为市场项选择图标和文本。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. 有关这些大小的详细说明,请参阅市场项 UI 参考See the Marketplace item UI reference for a detailed description of these sizes.

    Note

    为正确生成市场项,需要全部四个图标大小(small、medium、large、wide)。All four icon sizes (small, medium, large, wide) are required for building the Marketplace item correctly.

  10. 若要进一步编辑 Manifest.json,请参阅参考:市场项 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
    

    Note

    输出路径可以是所选的任何路径,且不一定要在 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.

发布市场项Publish a Marketplace item

  1. 使用 PowerShell 或 Azure 存储资源管理器将市场项 (.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-AzureRMEnvironment -Name "AzureStackAdmin" -ArmEndpoint $ArmEndpoint
    Add-AzureRmAccount -EnvironmentName "AzureStackAdmin"
    
  4. 运行以下脚本,将资源导入库中:Run the following script to import the resource into your gallery:

    Add-AzsGalleryItem -GalleryItemUri `
    https://sample.blob.core.chinacloudapi.cn/<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. 存储帐户仅供暂时使用,以便能够发布到市场。The storage account is only for temporary use, in order to publish to the marketplace.

    完成库包并使用 Add-AzsGalleryItem 将其上传之后,自定义 VM 现在应会显示在市场中以及“创建资源”视图中。 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. 请注意,“市场管理”中不显示自定义库包。 Note that the custom gallery package is not visible in Marketplace Management.

    已上传自定义市场项Custom marketplace item uploaded

  6. 成功将项发布到市场后,可以删除存储帐户中的内容。Once your item has been successfully published to the marketplace, you can delete the content from the storage account.

    Caution

    现在,无需身份验证,即可通过以下 URL 访问所有默认的库项目和自定义库项目:All default gallery artifacts and your custom gallery artifacts are now accessible without authentication under the following URLs:
    https://adminportal.[Region].[external FQDN]:30015/artifact/20161101/[Template Name]/DeploymentTemplates/Template.json https://portal.[Region].[external FQDN]:30015/artifact/20161101/[Template Name]/DeploymentTemplates/Template.json

  7. 可以使用 Remove-AzureRMGalleryItem cmdlet 删除市场项。You can remove a Marketplace item by using the Remove-AzureRMGalleryItem cmdlet. 例如:For example:

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

    Note

    删除某个项后,市场 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.

参考:市场项 manifest.jsonReference: Marketplace item manifest.json

标识信息Identity information

名称Name 必须Required 类型Type 约束Constraints 说明Description
名称Name XX StringString [A-Za-z0-9]+[A-Za-z0-9]+
发布者Publisher XX StringString [A-Za-z0-9]+[A-Za-z0-9]+
版本Version XX StringString SemVer v2SemVer v2

MetadataMetadata

名称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

市场使用以下图标:The Marketplace uses the following icons:

名称Name 宽度Width 高度Height 注释Notes
WideWide 255 px255 px 115 px115 px 始终必需Always required
大型Large 115 px115 px 115 px115 px 始终必需Always required
中型Medium 90 px90 px 90 px90 px 始终必需Always required
小型Small 40 px40 px 40 px40 px 始终必需Always required
屏幕快照Screenshot 533 px533 px 324 px324 px 始终必需Always required

CategoriesCategories

应当为每个市场项标记一个类别,该类别标识在门户 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.

每个市场项可以包括指向其他内容的各种链接。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

除了前面的元数据之外,市场作者可以采用以下形式提供自定义键/值对数据: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.
ValueValue 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

参考:市场项 UIReference: Marketplace item UI

在 Azure Stack Hub 门户中显示的市场项的图标和文本将如下所示。Icons and text for Marketplace items as seen in the Azure Stack Hub portal are as follows.

“创建”边栏选项卡Create blade

“创建”边栏选项卡 - Azure Stack Hub 市场项

市场项详细信息边栏选项卡Marketplace item details blade

Azure Stack Hub 市场项详细信息边栏选项卡

后续步骤Next steps