Planowanie struktury pliku Bicep

  • 7 min

Bicep zapewnia elastyczność decydowania o sposobie tworzenia struktury kodu. W tej lekcji poznasz sposoby tworzenia struktury kodu Bicep oraz znaczenie spójnego stylu i czytelnego, zrozumiałego kodu Bicep.

Jaka kolejność powinna być zgodna z kodem Bicep?

Szablony Bicep mogą zawierać wiele elementów, w tym parametry, zmienne, zasoby, moduły, dane wyjściowe i element targetScope dla całego szablonu. Bicep nie wymusza kolejności obserwowanych elementów. Należy jednak wziąć pod uwagę kolejność elementów, aby upewnić się, że szablon jest jasny i zrozumiały.

Istnieją dwa główne podejścia do zamawiania kodu:

  • Grupuj elementy według typu elementu
  • Grupuj elementy według zasobu

Ty i Twój zespół powinni się zgodzić na jeden i używać go spójnie.

Grupuj elementy według typu elementu

Wszystkie elementy tego samego typu można zgrupować razem. Wszystkie parametry będą przechodzić w jednym miejscu, zwykle w górnej części pliku. Zmienne są następne, a następnie zasoby i moduły, a dane wyjściowe znajdują się u dołu. Na przykład może istnieć plik Bicep, który wdraża bazę danych Azure SQL Database i konto magazynu.

Pogrupowanie elementów według typu może wyglądać następująco:

Diagram przedstawiający elementy pogrupowane według typu elementu. Parametry są grupowane razem, a następnie zmienne, a następnie zasoby, a następnie dane wyjściowe.

Napiwek

Jeśli przestrzegasz tej konwencji, rozważ umieszczenie targetScope elementu w górnej części pliku.

To kolejność ma sens, gdy używasz innej infrastruktury jako języków kodu (na przykład języka w szablonach usługi Azure Resource Manager). Może również ułatwić zrozumienie szablonu, ponieważ jest jasne, gdzie szukać konkretnych typów elementów. Jednak w dłuższych szablonach może być trudne przechodzenie między elementami i przechodzenie między nimi.

Nadal musisz zdecydować, jak uporządkować elementy w tych kategoriach. Dobrym pomysłem jest grupowanie powiązanych parametrów. Na przykład wszystkie parametry dotyczące konta magazynu należą do siebie, a w tym celu parametry jednostki SKU konta magazynu należą do siebie.

Podobnie można grupować powiązane zasoby. Ułatwia to każdemu, kto używa szablonu do szybkiego nawigowania po nim i zrozumienia ważnych części szablonu.

Czasami tworzy się szablon, który wdraża zasób podstawowy z wieloma pomocniczymi zasobami pomocniczymi. Możesz na przykład utworzyć szablon, aby wdrożyć witrynę internetową hostowaną w usłudze aplikacja systemu Azure. Podstawowym zasobem jest aplikacja usługi App Service. Zasoby pomocnicze w tym samym szablonie mogą obejmować plan usługi App Service, konto magazynu, wystąpienie usługi Application Insights i inne. Jeśli masz szablon podobny do tego, dobrym pomysłem jest umieszczenie zasobu podstawowego lub zasobów w górnej części sekcji zasobu szablonu, dzięki czemu każda osoba otwierająca szablon może szybko zidentyfikować przeznaczenie szablonu i znaleźć ważne zasoby.

Grupuj elementy według zasobu

Alternatywnie możesz grupować elementy na podstawie typu wdrażanych zasobów. Kontynuując poprzedni przykład, można zgrupować wszystkie parametry, zmienne, zasoby i dane wyjściowe powiązane z zasobami bazy danych Azure SQL Database. Następnie można dodać parametry, zmienne, zasoby i dane wyjściowe dla konta magazynu, jak pokazano poniżej:

Diagram przedstawiający elementy pogrupowane według zasobu. Elementy konta magazynu są grupowane, a następnie elementy bazy danych Azure SQL Database.

Grupowanie według zasobu może ułatwić odczytywanie szablonu, ponieważ wszystkie elementy potrzebne do określonego zasobu znajdują się w jednym miejscu. Jednak utrudnia szybkie sprawdzenie, w jaki sposób określone typy elementów są deklarowane, gdy na przykład chcesz przejrzeć wszystkie parametry.

Należy również wziąć pod uwagę sposób obsługi parametrów i zmiennych, które są wspólne dla wielu zasobów, takich jak environmentType parametr podczas korzystania z mapy konfiguracji. Wspólne parametry i zmienne należy umieścić razem, zwykle w górnej części pliku Bicep.

Napiwek

Zastanów się, czy tworzenie modułów dla grup powiązanych zasobów może mieć większe znaczenie, a następnie użycie prostszego szablonu w celu połączenia modułów. Bardziej szczegółowo omówimy moduły Bicep w ramach ścieżek szkoleniowych Bicep.

Jak białe znaki mogą pomóc w tworzeniu struktury?

Puste wiersze lub białe znaki mogą pomóc w dodaniu struktury wizualizacji do szablonu. Korzystając z białej przestrzeni przemyślanej, możesz logicznie zgrupować sekcje kodu Bicep, co z kolei może pomóc wyjaśnić relacje między zasobami. W tym celu rozważ dodanie pustej linii między głównymi sekcjami, niezależnie od preferowanego stylu grupowania.

Jak zdefiniować kilka podobnych zasobów?

Dzięki funkcji Bicep można użyć pętli, aby wdrożyć podobne zasoby z jednej definicji. Używając słowa kluczowego for do definiowania pętli zasobów, możesz sprawić, że kod Bicep będzie czystszy i zmniejszyć niepotrzebne duplikowanie definicji zasobów. W przyszłości, gdy trzeba zmienić definicję zasobów, wystarczy zaktualizować jedno miejsce. Domyślnie, gdy usługa Azure Resource Manager wdraża zasoby, wdraża wszystkie zasoby w pętli w tym samym czasie, dzięki czemu wdrożenie jest tak wydajne, jak to możliwe.

Poszukaj miejsc, w których definiujesz wiele zasobów, które są identyczne lub mają kilka różnic w ich właściwościach. Następnie dodaj zmienną, aby wyświetlić listę zasobów do utworzenia wraz z właściwościami, które różnią się od innych zasobów. W poniższym przykładzie użyto pętli do zdefiniowania zestawu kontenerów usługi Azure Cosmos DB, z których każda ma własną nazwę i klucz partycji:

var cosmosDBContainerDefinitions = [
  {
    name: 'customers'
    partitionKey: '/customerId'
  }
  {
    name: 'orders'
    partitionKey: '/orderId'
  }
  {
    name: 'products'
    partitionKey: '/productId'
  }
]

resource cosmosDBContainers 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-05-15' = [for cosmosDBContainerDefinition in cosmosDBContainerDefinitions: {
  parent: cosmosDBDatabase
  name: cosmosDBContainerDefinition.name
  properties: {
    resource: {
      id: cosmosDBContainerDefinition.name
      partitionKey: {
        kind: 'Hash'
        paths: [
          cosmosDBContainerDefinition.partitionKey
        ]
      }
    }
    options: {}
  }
}]

Jak wdrażać zasoby tylko w niektórych środowiskach?

Czasami definiuje się zasoby, które powinny być wdrażane tylko w określonych środowiskach lub w określonych warunkach. Za pomocą słowa kluczowego if można selektywnie wdrażać zasoby na podstawie wartości parametru, zmiennej mapy konfiguracji lub innego warunku. W poniższym przykładzie użyto mapy konfiguracji do wdrożenia zasobów rejestrowania dla środowisk produkcyjnych, ale nie dla środowisk testowych:

var environmentConfigurationMap = {
  Production: {
    enableLogging: true
  }
  Test: {
    enableLogging: false
  }
}

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' = if (environmentConfigurationMap[environmentType].enableLogging) {
  name: logAnalyticsWorkspaceName
  location: location
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = if (environmentConfigurationMap[environmentType].enableLogging) {
  scope: cosmosDBAccount
  name: cosmosDBAccountDiagnosticSettingsName
  properties: {
    workspaceId: logAnalyticsWorkspace.id
    // ...
  }
}

Jak wyrażasz zależności między zasobami?

W każdym złożonym szablonie Bicep należy wyrazić zależności między zasobami . Gdy Bicep rozumie zależności między zasobami, wdraża je w odpowiedniej kolejności.

Bicep umożliwia jawne określenie zależności przy użyciu dependsOn właściwości . Jednak w większości przypadków możliwe jest automatyczne wykrywanie zależności przez Bicep. Gdy używasz symbolicznej nazwy jednego zasobu we właściwości innego, Bicep wykrywa relację. Lepiej jest pozwolić Bicep zarządzać nimi za każdym razem, gdy tylko możesz. W ten sposób, gdy zmienisz szablon, Bicep upewni się, że zależności są zawsze poprawne i nie dodasz niepotrzebnego kodu, który sprawia, że szablon staje się bardziej kłopotliwy i trudniejszy do odczytania.

Jak wyrażasz relacje nadrzędny-podrzędny?

Usługi Azure Resource Manager i Bicep mają pojęcie zasobów podrzędnych, które mają sens tylko wtedy, gdy są wdrażane w kontekście ich elementu nadrzędnego. Na przykład baza danych Azure SQL Database jest elementem podrzędnym wystąpienia programu SQL Server. Istnieje kilka sposobów definiowania zasobów podrzędnych, ale w większości przypadków dobrym pomysłem jest użycie parent właściwości . Pomaga to firmie Bicep zrozumieć relację, dzięki czemu może ona zapewnić walidację w programie Visual Studio Code, a relacja jest jasna dla każdego innego użytkownika, który odczytuje szablon.

Jak ustawić właściwości zasobu?

Należy określić wartości właściwości zasobów w plikach Bicep. Dobrym pomysłem jest przemyślanie podczas kodowania wartości w definicjach zasobów. Jeśli wiesz, że wartości nie zmienią się, stałe kodowanie może być lepsze niż użycie innego parametru, który utrudnia testowanie szablonu i pracę z nim. Jeśli jednak wartości mogą ulec zmianie, rozważ zdefiniowanie ich jako parametrów lub zmiennych, aby kod Bicep był bardziej dynamiczny i wielokrotnego użytku.

Gdy wykonujesz stałe wartości kodu, dobrze jest upewnić się, że są one zrozumiałe dla innych. Jeśli na przykład właściwość musi być ustawiona na określoną wartość, aby zasób zachowywał się poprawnie dla rozwiązania, rozważ utworzenie dobrze nazwanej zmiennej, która zawiera wyjaśnienie, a następnie przypisanie wartości przy użyciu zmiennej. W sytuacjach, w których nazwa zmiennej nie opowiada całej historii, rozważ dodanie komentarza. Więcej informacji na temat komentarzy znajdziesz w dalszej części tego modułu.

Aby utworzyć wartości automatycznie dla niektórych właściwości zasobów, należy utworzyć złożone wyrażenia, które obejmują funkcje i interpolację ciągów. Kod Bicep jest zwykle jaśniejszy podczas deklarowania zmiennych i odwoływania się do nich w blokach kodu zasobu.

Napiwek

Podczas tworzenia danych wyjściowych spróbuj użyć właściwości zasobów wszędzie tam, gdzie możesz. Unikaj dołączania własnych założeń dotyczących sposobu działania zasobów, ponieważ te założenia mogą ulec zmianie w czasie.

Jeśli na przykład musisz wyświetlić adres URL aplikacji usługi App Service, unikaj konstruowania adresu URL:

output hostname string = '${app.name}.azurewebsites.net'

Powyższe podejście ulegnie awarii, jeśli usługa App Service zmieni sposób przypisywania nazw hostów do aplikacji lub w przypadku wdrażania w środowiskach platformy Azure korzystających z różnych adresów URL.

Zamiast tego użyj defaultHostname właściwości zasobu aplikacji:

output hostname string = app.properties.defaultHostname

Jak efektywnie używać kontroli wersji?

Systemy kontroli wersji, takie jak Git, mogą ułatwić pracę podczas refaktoryzacji kodu.

Ponieważ systemy kontroli wersji są przeznaczone do śledzenia zmian w plikach, można ich używać do łatwego powrotu do starszej wersji kodu, jeśli popełnisz błąd. Dobrym pomysłem jest często zatwierdzanie pracy, dzięki czemu możesz wrócić do dokładnego punktu w czasie, którego potrzebujesz.

Kontrola wersji pomaga również usunąć stary kod z plików Bicep. Co zrobić, jeśli kod Bicep zawiera definicję zasobu, której już nie potrzebujesz? W przyszłości może być konieczne ponowne wprowadzenie definicji i jest kuszące, aby po prostu oznaczyć ją jako komentarz i zachować ją w pliku. Ale naprawdę, utrzymanie go tam tylko zaśmieca plik Bicep, co utrudnia innym zrozumieć, dlaczego skomentowane zasoby są nadal tam.

Inną kwestią jest możliwość przypadkowego rozłączenia definicji przez kogoś z nieprzewidywalnymi lub potencjalnie negatywnymi wynikami. W przypadku korzystania z systemu kontroli wersji można po prostu usunąć starą definicję zasobu. Jeśli potrzebujesz definicji ponownie w przyszłości, możesz pobrać ją z historii plików.