Szybki start: tworzenie i publikowanie definicji aplikacji zarządzanej platformy Azure przy użyciu aplikacji Bicep

  • Artykuł

W tym przewodniku Szybki start opisano sposób używania aplikacji Bicep do tworzenia i publikowania definicji aplikacji zarządzanej platformy Azure w katalogu usług. Definicje w katalogu usług są dostępne dla członków organizacji.

Aby utworzyć i opublikować definicję aplikacji zarządzanej w katalogu usług, wykonaj następujące zadania:

  • Użyj narzędzia Bicep, aby opracować szablon i przekonwertować go na szablon usługi Azure Resource Manager (szablon usługi ARM). Szablon definiuje zasoby platformy Azure wdrożone przez aplikację zarządzaną.
  • Przekonwertuj Bicep na kod JSON za pomocą polecenia Bicep build . Po przekonwertowaniu pliku na kod JSON zaleca się zweryfikowanie kodu pod kątem dokładności.
  • Zdefiniuj elementy interfejsu użytkownika portalu, stosowane podczas wdrażania aplikacji zarządzanej.
  • Utwórz pakiet zip zawierający wymagane pliki JSON. Plik pakietu zip ma limit 120 MB dla definicji aplikacji zarządzanej katalogu usług.
  • Opublikuj definicję aplikacji zarządzanej, aby była dostępna w katalogu usług.

Jeśli definicja aplikacji zarządzanej jest większa niż 120 MB lub jeśli chcesz używać własnego konta magazynu ze względów zgodności organizacji, przejdź do przewodnika Szybki start: Tworzenie i publikowanie definicji aplikacji zarządzanej platformy Azure.

Możesz również użyć narzędzia Bicep, aby wdrożyć definicję aplikacji zarządzanej z katalogu usług. Aby uzyskać więcej informacji, przejdź do przewodnika Szybki start: wdrażanie definicji aplikacji zarządzanej platformy Azure za pomocą narzędzia Bicep.

Wymagania wstępne

Do wykonania zadań w tym artykule potrzebne są następujące elementy:

Tworzenie pliku Bicep

Każda definicja aplikacji zarządzanej zawiera plik o nazwie mainTemplate.json. Szablon definiuje zasoby platformy Azure do wdrożenia i nie różni się od zwykłego szablonu usługi ARM. Szablon można opracować przy użyciu Bicep, a następnie przekonwertować plik Bicep na format JSON.

Otwórz program Visual Studio Code, utwórz plik z nazwą wrażliwą na wielkość liter mainTemplate.bicep i zapisz go.

Dodaj następujący kod Bicep i zapisz plik. Definiuje ona zasoby aplikacji zarządzanej w celu wdrożenia usługi App Service, planu usługi App Service i konta magazynu.

param location string = resourceGroup().location

@description('App Service plan name.')
@maxLength(40)
param appServicePlanName string

@description('App Service name prefix.')
@maxLength(47)
param appServiceNamePrefix string

@description('Storage account name prefix.')
@maxLength(11)
param storageAccountNamePrefix string

@description('Storage account type allowed values')
@allowed([
  'Premium_LRS'
  'Standard_LRS'
  'Standard_GRS'
])
param storageAccountType string

var appServicePlanSku = 'F1'
var appServicePlanCapacity = 1
var appServiceName = '${appServiceNamePrefix}${uniqueString(resourceGroup().id)}'
var storageAccountName = '${storageAccountNamePrefix}${uniqueString(resourceGroup().id)}'
var appServiceStorageConnectionString = 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};EndpointSuffix=${environment().suffixes.storage};Key=${storageAccount.listKeys().keys[0].value}'

resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanCapacity
  }
}

resource appServiceApp 'Microsoft.Web/sites@2022-03-01' = {
  name: appServiceName
  location: location
  properties: {
    serverFarmId: appServicePlan.id
    httpsOnly: true
    siteConfig: {
      appSettings: [
        {
          name: 'AppServiceStorageConnectionString'
          value: appServiceStorageConnectionString
        }
      ]
    }
  }
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

output appServicePlan string = appServicePlan.name
output appServiceApp string = appServiceApp.properties.defaultHostName
output storageAccount string = storageAccount.properties.primaryEndpoints.blob

Konwertowanie kodu Bicep na format JSON

Użyj programu PowerShell lub interfejsu wiersza polecenia platformy Azure, aby skompilować plik mainTemplate.json . Przejdź do katalogu, w którym zapisano plik Bicep i uruchom build polecenie .

bicep build mainTemplate.bicep

Aby dowiedzieć się więcej, przejdź do sekcji Kompilacja Bicep.

Po przekonwertowaniu pliku Bicep na format JSON plik mainTemplate.json powinien być zgodny z poniższym przykładem. Mogą istnieć różne wartości we właściwościach metadata i versiontemplateHash.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.17.1.54307",
      "templateHash": "1234567891234567890"
    }
  },
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "appServicePlanName": {
      "type": "string",
      "maxLength": 40,
      "metadata": {
        "description": "App Service plan name."
      }
    },
    "appServiceNamePrefix": {
      "type": "string",
      "maxLength": 47,
      "metadata": {
        "description": "App Service name prefix."
      }
    },
    "storageAccountNamePrefix": {
      "type": "string",
      "maxLength": 11,
      "metadata": {
        "description": "Storage account name prefix."
      }
    },
    "storageAccountType": {
      "type": "string",
      "allowedValues": [
        "Premium_LRS",
        "Standard_LRS",
        "Standard_GRS"
      ],
      "metadata": {
        "description": "Storage account type allowed values"
      }
    }
  },
  "variables": {
    "appServicePlanSku": "F1",
    "appServicePlanCapacity": 1,
    "appServiceName": "[format('{0}{1}', parameters('appServiceNamePrefix'), uniqueString(resourceGroup().id))]",
    "storageAccountName": "[format('{0}{1}', parameters('storageAccountNamePrefix'), uniqueString(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Web/serverfarms",
      "apiVersion": "2022-03-01",
      "name": "[parameters('appServicePlanName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[variables('appServicePlanSku')]",
        "capacity": "[variables('appServicePlanCapacity')]"
      }
    },
    {
      "type": "Microsoft.Web/sites",
      "apiVersion": "2022-03-01",
      "name": "[variables('appServiceName')]",
      "location": "[parameters('location')]",
      "properties": {
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]",
        "httpsOnly": true,
        "siteConfig": {
          "appSettings": [
            {
              "name": "AppServiceStorageConnectionString",
              "value": "[format('DefaultEndpointsProtocol=https;AccountName={0};EndpointSuffix={1};Key={2}', variables('storageAccountName'), environment().suffixes.storage, listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2022-09-01').keys[0].value)]"
            }
          ]
        }
      },
      "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]",
        "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]"
      ]
    },
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[variables('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      },
      "kind": "StorageV2",
      "properties": {
        "accessTier": "Hot"
      }
    }
  ],
  "outputs": {
    "appServicePlan": {
      "type": "string",
      "value": "[parameters('appServicePlanName')]"
    },
    "appServiceApp": {
      "type": "string",
      "value": "[reference(resourceId('Microsoft.Web/sites', variables('appServiceName')), '2022-03-01').defaultHostName]"
    },
    "storageAccount": {
      "type": "string",
      "value": "[reference(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2022-09-01').primaryEndpoints.blob]"
    }
  }
}

Definiowanie środowiska portalu

Jako wydawca definiujesz środowisko portalu w celu utworzenia aplikacji zarządzanej. Plik createUiDefinition.json generuje interfejs użytkownika portalu. Definiujesz sposób, w jaki użytkownicy udostępniają dane wejściowe dla każdego parametru przy użyciu elementów sterujących, takich jak listy rozwijane i pola tekstowe.

W tym przykładzie interfejs użytkownika wyświetla monit o wprowadzenie prefiksu nazwy usługi App Service, nazwy planu usługi App Service, prefiksu konta magazynu i typu konta magazynu. Podczas wdrażania zmienne w pliku mainTemplate.json używają uniqueString funkcji do dołączania 13-znakowego ciągu do prefiksów nazw, dzięki czemu nazwy są globalnie unikatowe na platformie Azure.

Otwórz program Visual Studio Code, utwórz plik o nazwie z uwzględnieniem wielkości liter createUiDefinition.json i zapisz go.

Dodaj następujący kod JSON do pliku i zapisz go.

{
  "$schema": "https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json#",
  "handler": "Microsoft.Azure.CreateUIDef",
  "version": "0.1.2-preview",
  "parameters": {
    "basics": [
      {}
    ],
    "steps": [
      {
        "name": "webAppSettings",
        "label": "Web App settings",
        "subLabel": {
          "preValidation": "Configure the web app settings",
          "postValidation": "Completed"
        },
        "elements": [
          {
            "name": "appServicePlanName",
            "type": "Microsoft.Common.TextBox",
            "label": "App Service plan name",
            "placeholder": "App Service plan name",
            "defaultValue": "",
            "toolTip": "Use alphanumeric characters or hyphens with a maximum of 40 characters.",
            "constraints": {
              "required": true,
              "regex": "^[a-z0-9A-Z-]{1,40}$",
              "validationMessage": "Only alphanumeric characters or hyphens are allowed, with a maximum of 40 characters."
            },
            "visible": true
          },
          {
            "name": "appServiceName",
            "type": "Microsoft.Common.TextBox",
            "label": "App Service name prefix",
            "placeholder": "App Service name prefix",
            "defaultValue": "",
            "toolTip": "Use alphanumeric characters or hyphens with minimum of 2 characters and maximum of 47 characters.",
            "constraints": {
              "required": true,
              "regex": "^[a-z0-9A-Z-]{2,47}$",
              "validationMessage": "Only alphanumeric characters or hyphens are allowed, with a minimum of 2 characters and maximum of 47 characters."
            },
            "visible": true
          }
        ]
      },
      {
        "name": "storageConfig",
        "label": "Storage settings",
        "subLabel": {
          "preValidation": "Configure the storage settings",
          "postValidation": "Completed"
        },
        "elements": [
          {
            "name": "storageAccounts",
            "type": "Microsoft.Storage.MultiStorageAccountCombo",
            "label": {
              "prefix": "Storage account name prefix",
              "type": "Storage account type"
            },
            "toolTip": {
              "prefix": "Enter maximum of 11 lowercase letters or numbers.",
              "type": "Available choices are Standard_LRS, Standard_GRS, and Premium_LRS."
            },
            "defaultValue": {
              "type": "Standard_LRS"
            },
            "constraints": {
              "allowedTypes": [
                "Premium_LRS",
                "Standard_LRS",
                "Standard_GRS"
              ]
            },
            "visible": true
          }
        ]
      }
    ],
    "outputs": {
      "location": "[location()]",
      "appServicePlanName": "[steps('webAppSettings').appServicePlanName]",
      "appServiceNamePrefix": "[steps('webAppSettings').appServiceName]",
      "storageAccountNamePrefix": "[steps('storageConfig').storageAccounts.prefix]",
      "storageAccountType": "[steps('storageConfig').storageAccounts.type]"
    }
  }
}

Aby dowiedzieć się więcej, przejdź do tematu Wprowadzenie do metody CreateUiDefinition.

Pakowanie plików

Dodaj dwa pliki do pliku pakietu o nazwie app.zip. Dwa pliki muszą znajdować się na poziomie głównym pliku zip . Jeśli pliki znajdują się w folderze, podczas tworzenia definicji aplikacji zarządzanej zostanie wyświetlony błąd wskazujący, że wymagane pliki nie są obecne.

Przekaż plik app.zip do konta usługi Azure Storage, aby można było go używać podczas wdrażania definicji aplikacji zarządzanej. Nazwa konta magazynu musi być globalnie unikatowa na platformie Azure, a długość musi zawierać od 3 do 24 znaków z małymi literami i cyframi. W poleceniu zastąp symbol zastępczy <demostorageaccount> zawierający nawiasy kątowe (<>), unikatową nazwą konta magazynu.

W programie Visual Studio Code otwórz nowy terminal programu PowerShell i zaloguj się do subskrypcji platformy Azure.

Connect-AzAccount

Polecenie otwiera domyślną przeglądarkę i wyświetla monit o zalogowanie się na platformie Azure. Aby uzyskać więcej informacji, przejdź do tematu Logowanie się przy użyciu programu Azure PowerShell.

Po nawiązaniu połączenia uruchom następujące polecenia.

New-AzResourceGroup -Name packageStorageRG -Location westus3

$storageAccount = New-AzStorageAccount `
  -ResourceGroupName packageStorageRG `
  -Name "<demostorageaccount>" `
  -Location westus3 `
  -SkuName Standard_LRS `
  -Kind StorageV2 `
  -AllowBlobPublicAccess $true

$ctx = $storageAccount.Context

New-AzStorageContainer -Name appcontainer -Context $ctx -Permission blob

Set-AzStorageBlobContent `
  -File "app.zip" `
  -Container appcontainer `
  -Blob "app.zip" `
  -Context $ctx

Użyj następującego polecenia, aby zapisać identyfikator URI pliku pakietu w zmiennej o nazwie packageuri. Wartość zmiennej jest używana podczas wdrażania definicji aplikacji zarządzanej.

$packageuri=(Get-AzStorageBlob -Container appcontainer -Blob app.zip -Context $ctx).ICloudBlob.StorageUri.PrimaryUri.AbsoluteUri

Tworzenie definicji aplikacji zarządzanej

W tej sekcji uzyskasz informacje o tożsamości od firmy Microsoft Entra ID, utworzysz grupę zasobów i wdrożysz definicję aplikacji zarządzanej.

Pobieranie identyfikatora grupy i identyfikatora definicji roli

Następnym krokiem jest wybranie użytkownika, grupy zabezpieczeń lub aplikacji do zarządzania zasobami dla klienta. Ta tożsamość ma uprawnienia do zarządzanej grupy zasobów zgodnie z przypisaną rolą. Rola może być dowolną wbudowaną rolą platformy Azure, na przykład właścicielem lub współautorem.

W tym przykładzie użyto grupy zabezpieczeń, a Twoje konto Microsoft Entra powinno być członkiem grupy. Aby uzyskać identyfikator obiektu grupy, zastąp symbol zastępczy <managedAppDemo> , w tym nawiasy kątowe (<>), nazwą grupy. Wartość zmiennej jest używana podczas wdrażania definicji aplikacji zarządzanej.

Aby utworzyć nową grupę firmy Microsoft Entra, przejdź do sekcji Zarządzanie grupami i członkostwem w grupach firmy Microsoft.

$principalid=(Get-AzADGroup -DisplayName <managedAppDemo>).Id

Następnie uzyskaj identyfikator definicji roli wbudowanej roli platformy Azure, której chcesz udzielić dostępu użytkownikowi, grupie lub aplikacji. Wartość zmiennej jest używana podczas wdrażania definicji aplikacji zarządzanej.

$roleid=(Get-AzRoleDefinition -Name Owner).Id

Tworzenie szablonu wdrożenia definicji

Użyj pliku Bicep, aby wdrożyć definicję aplikacji zarządzanej w katalogu usług.

Otwórz program Visual Studio Code, utwórz plik o nazwie deployDefinition.bicep i zapisz go.

Dodaj następujący kod Bicep i zapisz plik.

param location string = resourceGroup().location

@description('Name of the managed application definition.')
param managedApplicationDefinitionName string

@description('The URI of the .zip package file.')
param packageFileUri string

@description('Publishers Principal ID that needs permissions to manage resources in the managed resource group.')
param principalId string

@description('Role ID for permissions to the managed resource group.')
param roleId string

var definitionLockLevel = 'ReadOnly'
var definitionDisplayName = 'Sample Bicep managed application'
var definitionDescription = 'Sample Bicep managed application that deploys web resources'

resource managedApplicationDefinition 'Microsoft.Solutions/applicationDefinitions@2021-07-01' = {
  name: managedApplicationDefinitionName
  location: location
  properties: {
    lockLevel: definitionLockLevel
    description: definitionDescription
    displayName: definitionDisplayName
    packageFileUri: packageFileUri
    authorizations: [
      {
        principalId: principalId
        roleDefinitionId: roleId
      }
    ]
  }
}

Aby uzyskać więcej informacji na temat właściwości szablonu, zobacz Microsoft.Solutions/applicationDefinitions.

Grupa lockLevel zasobów zarządzanych uniemożliwia klientowi wykonywanie niepożądanych operacji w tej grupie zasobów. ReadOnly Obecnie jest jedynym obsługiwanym poziomem blokady. ReadOnly określa, że klient może odczytywać tylko zasoby obecne w zarządzanej grupie zasobów. Tożsamości wydawcy, którym udzielono dostępu do zarządzanej grupy zasobów, są wykluczone z poziomu blokady.

Tworzenie pliku parametrów

Szablon wdrożenia definicji aplikacji zarządzanej wymaga danych wejściowych dla kilku parametrów. Polecenie wdrożenia wyświetla monit o wartości lub możesz utworzyć plik parametrów dla wartości. W tym przykładzie użyjemy pliku parametrów, aby przekazać wartości parametrów do polecenia wdrożenia.

W programie Visual Studio Code utwórz nowy plik o nazwie deployDefinition.parameters.json i zapisz go.

Dodaj następujący kod do pliku parametrów i zapisz go. Następnie zastąp nawiasy <placeholder values> kątowe (<>), swoimi wartościami.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "managedApplicationDefinitionName": {
      "value": "sampleBicepManagedApplication"
    },
    "packageFileUri": {
      "value": "<placeholder for the packageFileUri>"
    },
    "principalId": {
      "value": "<placeholder for principalid value>"
    },
    "roleId": {
      "value": "<placeholder for roleid value>"
    }
  }
}

W poniższej tabeli opisano wartości parametrów definicji aplikacji zarządzanej.

Parametr Wartość
managedApplicationDefinitionName Nazwa definicji aplikacji zarządzanej. W tym przykładzie użyj przykładuBicepManagedApplication.
packageFileUri Wprowadź identyfikator URI pliku pakietu zip . packageuri Użyj wartości zmiennej. Format to https://yourStorageAccountName.blob.core.windows.net/appcontainer/app.zip.
principalId Identyfikator podmiotu zabezpieczeń wydawców, który wymaga uprawnień do zarządzania zasobami w zarządzanej grupie zasobów. principalid Użyj wartości zmiennej.
roleId Identyfikator roli uprawnień do zarządzanej grupy zasobów. Na przykład Właściciel, Współautor, Czytelnik. roleid Użyj wartości zmiennej.

Aby uzyskać wartości zmiennych:

  • Azure PowerShell: w programie PowerShell wpisz $variableName , aby wyświetlić wartość zmiennej.
  • Interfejs wiersza polecenia platformy Azure: w powłoce Bash wpisz echo $variableName , aby wyświetlić wartość zmiennej.

Wdrażanie definicji

Po wdrożeniu definicji aplikacji zarządzanej staje się ona dostępna w katalogu usług. Ten proces nie wdraża zasobów aplikacji zarządzanej.

Utwórz grupę zasobów o nazwie bicepDefinitionRG i wdróż definicję aplikacji zarządzanej.

New-AzResourceGroup -Name bicepDefinitionRG -Location westus3

New-AzResourceGroupDeployment `
  -ResourceGroupName bicepDefinitionRG `
  -TemplateFile deployDefinition.bicep `
  -TemplateParameterFile deployDefinition.parameters.json

Weryfikowanie wyników

Uruchom następujące polecenie, aby sprawdzić, czy definicja została opublikowana w katalogu usług.

Get-AzManagedApplicationDefinition -ResourceGroupName bicepDefinitionRG

Get-AzManagedApplicationDefinition Wyświetla listę wszystkich dostępnych definicji w określonej grupie zasobów, takich jak sampleBicepManagedApplication.

Upewnij się, że użytkownicy mogą uzyskiwać dostęp do definicji

Masz dostęp do definicji aplikacji zarządzanej, ale chcesz mieć pewność, że inni użytkownicy w Twojej organizacji również mają do niej dostęp. Z definicji przyznaj im co najmniej rolę czytelnika. Użytkownicy mogą odziedziczyć ten poziom dostępu z subskrypcji lub grupy zasobów. Aby sprawdzić, kto ma dostęp do definicji i dodać użytkowników lub grupy, przejdź do sekcji Przypisywanie ról platformy Azure przy użyciu witryny Azure Portal.

Czyszczenie zasobów

Jeśli zamierzasz wdrożyć definicję, przejdź do sekcji Następne kroki , która zawiera linki do artykułu, aby wdrożyć definicję za pomocą Bicep.

Jeśli skończysz z definicją aplikacji zarządzanej, możesz usunąć utworzone grupy zasobów o nazwie packageStorageRG i bicepDefinitionRG.

Polecenie wyświetla monit o potwierdzenie, że chcesz usunąć grupę zasobów.

Remove-AzResourceGroup -Name packageStorageRG

Remove-AzResourceGroup -Name bicepDefinitionRG

Następne kroki

Opublikowano definicję aplikacji zarządzanej. Następnym krokiem jest dowiedzieć się, jak wdrożyć wystąpienie tej definicji.

Szybki start: wdrażanie definicji aplikacji zarządzanej platformy Azure za pomocą narzędzia Bicep.