Opis parametrów

  • 8 min

Za pomocą parametrów można podać informacje do szablonu Bicep w czasie wdrażania. Szablon Bicep może być elastyczny i wielokrotnego użytku, deklarując parametry w szablonie.

Dekoratory umożliwiają dołączanie ograniczeń i metadanych do parametru, co ułatwia każdemu, kto korzysta z szablonów, aby zrozumieć, jakie informacje muszą podać.

W tej lekcji dowiesz się więcej o parametrach i dekoratorach.

Deklarowanie parametru

W szablonie Bicep deklarujesz parametr przy użyciu słowa kluczowego param . Te deklaracje można umieścić w dowolnym miejscu w pliku szablonu, chociaż zazwyczaj dobrym pomysłem jest umieszczenie ich w górnej części pliku, dzięki czemu kod Bicep jest łatwy do odczytania.

Poniżej przedstawiono sposób deklarowania parametru:

param environmentName string

Przyjrzyjmy się, jak działa każda część:

  • param wskazuje Bicep, że deklarujesz parametr.

  • environmentName odwołuje się do nazwy parametru. Chociaż nazwa parametru może być niczym innym, należy określić nazwę zrozumiałą dla użytkowników szablonu. W tym samym szablonie można również odwołać się do parametru przy użyciu jego nazwy. Nazwy parametrów muszą być unikatowe. Nie mogą mieć takiej samej nazwy jak zmienna lub zasób w tym samym pliku Bicep.

    Napiwek

    Użyj konwencji nazewnictwa najlepszych rozwiązań dla deklaracji parametrów. Dobre konwencje nazewnictwa ułatwiają odczytywanie i zrozumienie szablonów. Upewnij się, że używasz przejrzystych, opisowych nazw i zastosuj spójną strategię nazewnictwa.

  • string odnosi się do typu parametru.

    Napiwek

    Dokładnie zastanów się nad parametrami używanymi przez szablon. Spróbuj użyć parametrów dla ustawień, które zmieniają się między wdrożeniami. Zmienne i trwale zakodowane wartości mogą służyć do ustawień, które nie zmieniają się między wdrożeniami.

Dodawanie wartości domyślnej

Wartości domyślne można przypisać do parametrów w szablonach. Przypisując wartość domyślną, parametr jest opcjonalny. Jeśli szablon zostanie wdrożony bez określonej wartości dla parametru, zostanie przypisana wartość domyślna.

Poniżej przedstawiono sposób dodawania wartości domyślnej:

param environmentName string = 'dev'

Parametr environmentName ma przypisaną wartość domyślną .dev

Wyrażenia można używać jako wartości domyślnych. Oto przykład parametru ciągu o nazwie location z wartością domyślną ustawioną na lokalizację bieżącej grupy zasobów:

param location string = resourceGroup().location

Napiwek

Należy pamiętać o używanych wartościach domyślnych. Upewnij się, że będzie to bezpieczne dla kogoś, kto wdroży plik Bicep z wartościami domyślnymi. Rozważ na przykład użycie niedrogich warstw cenowych i jednostek SKU, aby ktoś wdrażający szablon w środowisku testowym niepotrzebnie nie ponosił dużych kosztów.

Opis typów parametrów

Podczas deklarowania parametru należy poinformować Bicep o typie informacji, które będą zawierać parametr. Bicep zapewni, że wartość przypisana do parametru jest zgodna z typem parametru.

Parametry w Bicep mogą być jednym z następujących typów:

  • string, który umożliwia wprowadzanie dowolnego tekstu.
  • int, który umożliwia wprowadzenie liczby.
  • bool, który reprezentuje wartość logiczną (true lub false).
  • object i array, które reprezentują dane ustrukturyzowane i listy.

Obiekty

Parametry obiektu umożliwiają łączenie danych ustrukturyzowanych w jednym miejscu. Obiekt może mieć wiele właściwości różnych typów. Obiekty można używać w definicjach zasobów, zmiennych lub w wyrażeniach w pliku Bicep. Oto przykład obiektu:

param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
  capacity: 1
}

Ten parametr jest obiektem z dwiema właściwościami ciągów i name tieri właściwością całkowitą . capacity Zwróć uwagę, że każda z właściwości znajduje się we własnym wierszu.

W przypadku odwołowania się do parametru w szablonie można wybrać poszczególne właściwości obiektu, używając kropki, po której następuje nazwa właściwości, jak w tym przykładzie:

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

Ważne

Należy pamiętać, że nie określasz typu każdej właściwości w obiekcie. Jednak w przypadku używania wartości właściwości jej typ musi być zgodny z oczekiwaną wartością. W poprzednim przykładzie zarówno nazwa, jak i warstwa jednostki SKU planu usługi App Service muszą być ciągami.

Innym przykładem, gdzie można użyć parametru obiektu, jest określenie tagów zasobów. Metadane tagów niestandardowych można dołączyć do wdrażanych zasobów, których można użyć do identyfikowania ważnych informacji o zasobie.

Tagi są przydatne w scenariuszach, takich jak śledzenie, który zespół jest właścicielem zasobu, lub gdy zasób należy do środowiska produkcyjnego lub nieprodukcyjnego. Zazwyczaj używasz różnych tagów dla każdego środowiska, ale chcesz ponownie użyć tych samych wartości tagów we wszystkich zasobach w szablonie. Z tego powodu tagi zasobów są dobrym zastosowaniem dla parametru obiektu, na przykład w tym przykładzie:

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

Za każdym razem, gdy zdefiniujesz zasób w pliku Bicep, możesz użyć go ponownie wszędzie tam, gdzie zdefiniujesz tags właściwość:

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'S1'
  }
}

resource appServiceApp 'Microsoft.Web/sites@' = {
  name: appServiceAppName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appServicePlan.id
  }
}

Tablice

Tablica jest listą elementów. Na przykład możesz użyć tablicy wartości ciągu, aby zadeklarować listę adresów e-mail dla grupy akcji usługi Azure Monitor. Możesz też użyć tablicy obiektów do reprezentowania listy podsieci dla sieci wirtualnej.

Uwaga

Nie można określić typu poszczególnych elementów, które tablica musi zawierać. Na przykład nie można określić, że tablica musi zawierać ciągi.

Rozważmy przykład. Usługa Azure Cosmos DB umożliwia tworzenie kont baz danych obejmujących wiele regionów i automatycznie obsługuje replikację danych. Podczas wdrażania nowego konta bazy danych należy określić listę regionów świadczenia usługi Azure, w których ma zostać wdrożone konto. Często musisz mieć inną listę lokalizacji dla różnych środowisk. Na przykład aby zaoszczędzić pieniądze w środowisku testowym, możesz użyć tylko jednej lub dwóch lokalizacji. Jednak w środowisku produkcyjnym można użyć kilku lokalizacji.

Można utworzyć parametr tablicy, który określa listę lokalizacji:

param cosmosDBAccountLocations array = [
  {
    locationName: 'australiaeast'
  }
  {
    locationName: 'southcentralus'
  }
  {
    locationName: 'westeurope'
  }
]

Napiwek

Powyższy przykład to tablica obiektów. Każdy obiekt ma właściwość, która jest oczekiwana przez usługę locationName Azure Cosmos DB. Podczas pracy z definicją zasobu w programie Visual Studio Code możesz zacząć od wprowadzenia właściwości zasobu, aby uzyskać funkcję IntelliSense z narzędzi Bicep. Korzystając z tego podejścia, możesz utworzyć przykładowe wartości. Po zadowoleniu z konfiguracji przenieś sekcję kodu Bicep do parametru . W ten sposób można zastąpić trwale zakodowaną właściwość parametrem, który można zmienić podczas każdego wdrożenia, jednocześnie upewniając się, że zasób jest poprawnie skonfigurowany.

Po zadeklarowaniu zasobu usługi Azure Cosmos DB można teraz odwołać się do parametru tablicy:

resource account 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  name: accountName
  location: location
  properties: {
    locations: cosmosDBAccountLocations
  }
}

Następnie można łatwo użyć innej wartości parametru dla środowiska deweloperskiego, zmieniając wartość parametru. Wkrótce dowiesz się, jak podać różne wartości parametrów bez modyfikowania oryginalnego szablonu.

Określanie listy dozwolonych wartości

Czasami należy upewnić się, że parametr ma pewne wartości. Na przykład zespół może zdecydować, że produkcyjne plany usługi App Service powinny być wdrażane przy użyciu jednostek SKU Premium w wersji 3. Aby wymusić tę regułę, możesz użyć dekoratora parametrów @allowed . Dekorator parametrów to sposób przekazywania informacji o wartości parametru Bicep. Oto jak parametr ciągu o nazwie appServicePlanSkuName może być ograniczony, aby można było przypisać tylko kilka określonych wartości:

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
param appServicePlanSkuName string

Napiwek

Używaj dekoratora @allowed oszczędnie. Jeśli używasz tego dekoratora zbyt szeroko, możesz zablokować prawidłowe wdrożenia, jeśli nie będziesz aktualizować listy. Powyższy przykład umożliwia używanie tylko jednostek SKU Premium w wersji 3 w środowisku produkcyjnym. Jeśli musisz użyć tego samego szablonu do wdrożenia niektórych tańszych środowisk nieprodukcyjnych, lista dozwolonych wartości może uniemożliwić korzystanie z innych jednostek SKU, które należy użyć.

Ogranicz długość parametru i wartości

W przypadku używania parametrów ciągu często trzeba ograniczyć długość ciągu. Rozważmy przykład nazewnictwa zasobów platformy Azure. Wszystkie typy zasobów platformy Azure mają limity dotyczące długości ich nazw. Dobrym rozwiązaniem jest określenie minimalnej i maksymalnej długości znaków dla parametrów, które kontrolują nazewnictwo, aby uniknąć błędów później podczas wdrażania. Można użyć @minLength dekoratorów i @maxLength do minimalnych i maksymalnych długości znaków, które mają być dozwolone dla parametru.

Oto przykład, który deklaruje parametr ciągu o nazwie storageAccountName, którego długość może wynosić tylko od 5 do 24 znaków:

@minLength(5)
@maxLength(24)
param storageAccountName string

Ten parametr zawiera dwa dekoratory. Można zastosować wiele dekoratorów do parametru, umieszczając każdy dekorator na własnej linii.

Uwaga

Można również zastosować @minLength dekoratory i @maxLength do parametrów tablicy, aby kontrolować liczbę elementów, które mogą znajdować się w tablicy.

Podczas pracy z parametrami liczbowymi może być konieczne użycie wartości w określonym zakresie. Na przykład twoja firma może zdecydować, że za każdym razem, gdy ktoś wdroży plan usługi App Service, zawsze powinien wdrożyć co najmniej jedno wystąpienie, ale nie więcej niż 10 wystąpień planu. Aby spełnić wymagania, można użyć @minValue dekoratorów i @maxValue , aby określić minimalne i maksymalne dozwolone wartości. W poniższym przykładzie zadeklarowany jest parametr appServicePlanInstanceCount liczby całkowitej, którego wartość może należeć tylko do zakresu od 1 do 10 (włącznie):

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

Dodawanie opisów do parametrów

Parametry to doskonały sposób na ponowne użycie szablonów przez inne osoby. W przypadku korzystania z szablonów należy zrozumieć, co robi każdy parametr, aby mógł podać odpowiednie wartości. Bicep udostępnia @description dekorator, dzięki czemu można udokumentować cel parametrów w czytelny dla człowieka sposób.

@description('The locations into which this Cosmos DB account should be configured. This parameter needs to be a list of objects, each of which has a locationName property.')
param cosmosDBAccountLocations array

Dobrym rozwiązaniem jest podanie opisów parametrów. Spróbuj ułatwić opisy i podaj wszelkie ważne informacje o tym, co szablon potrzebuje wartości parametrów.

Uwaga

Szablony Bicep mogą być czasami udostępniane w witrynie Azure Portal, aby użytkownicy mogli wdrażać, tak jak w przypadku korzystania ze specyfikacji szablonu. Portal używa opisów i innych dekoratorów parametrów, aby ułatwić użytkownikom zrozumienie, jaka wartość parametru musi być.