Udostępnij za pośrednictwem

Bicep polecenia interfejsu wiersza polecenia

W tym artykule opisano polecenia, których można użyć w interfejsie wiersza polecenia Bicep. Te polecenia można wykonać przy użyciu Azure CLI lub bezpośrednio wywołując polecenia interfejsu wiersza polecenia Bicep. Każda metoda wymaga odrębnego procesu instalacji. Aby uzyskać więcej informacji na temat instalacji, zobacz Azure CLI i Azure PowerShell.

Te wskazówki pokazują, jak uruchamiać polecenia w Azure CLI. Podczas uruchamiania poleceń w Azure CLI uruchom je za pomocą az. Jeśli nie używasz Azure CLI, uruchom polecenia bez az na początku każdego z nich. Na przykład az bicep build staje się bicep build, a az bicep version staje się .bicep --version

kompilacja

Polecenie build konwertuje plik Bicep na szablon Azure Resource Manager JSON (szablon usługi ARM). Zazwyczaj nie trzeba uruchamiać tego polecenia, ponieważ jest on uruchamiany automatycznie podczas wdrażania pliku Bicep. Uruchom go ręcznie, gdy chcesz wyświetlić szablon usługi ARM JSON utworzony na podstawie pliku Bicep.

Użycie dowolnej z następujących funkcji Bicep automatycznie włącza generowanie kodu w wersji 2.0 języka:

Poniższy przykład konwertuje plik Bicep o nazwie main.bicep do szablonu usługi ARM o nazwie main.json. Nowy plik jest tworzony w tym samym katalogu co plik Bicep:

bicep build main.bicep

Następny przykład zapisuje main.json w innym katalogu:

bicep build main.bicep --outdir c:\jsontemplates

W poniższym przykładzie określono nazwę i lokalizację pliku do utworzenia:

bicep build main.bicep --outfile c:\jsontemplates\azuredeploy.json

Aby wydrukować plik w pliku stdout, użyj polecenia :

bicep build main.bicep --stdout

Jeśli plik Bicep zawiera moduł odwołujący się do rejestru zewnętrznego, polecenie build automatycznie wywołuje polecenie restore. Polecenie restore pobiera plik z rejestru i zapisuje go w lokalnej pamięci podręcznej.

Uwaga

Polecenie restore nie odświeża pamięci podręcznej. Aby uzyskać więcej informacji, zobacz przywracanie.

Aby zapobiec automatycznemu przywracaniu, użyj przełącznika --no-restore :

bicep build --no-restore <bicep-file>

Aby użyć przełącznika --no-restore, musisz mieć Bicep interfejs wiersza polecenia w wersji 0.4.X lub nowszej.

Proces kompilacji z przełącznikiem kończy się niepowodzeniem --no-restore , jeśli jeden z modułów zewnętrznych nie jest jeszcze buforowany:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" hasn't been restored.

Po wystąpieniu tego błędu uruchom build polecenie bez przełącznika --no-restore lub uruchom bicep restore polecenie jako pierwsze.

parametry kompilacji

Polecenie build-params kompiluje .bicepparam plik w pliku parametrów JSON:

bicep build-params params.bicepparam

To polecenie konwertuje plik parametrów params.bicepparam na plik parametrów JSON params.json .

dekompilować

Polecenie decompile konwertuje szablon usługi ARM JSON na plik Bicep:

bicep decompile main.json

To polecenie tworzy plik o nazwie main.bicep w tym samym katalogu co main.json. Jeśli main. bicep istnieje w tym samym katalogu, użyj przełącznika --force, aby zastąpić istniejący plik Bicep.

Aby uzyskać więcej informacji na temat korzystania z tego polecenia, zobacz szablon arm Decompile JSON do Bicep.

dekompiluj-params

Polecenie decompile-params dekompiluje plik parametrów JSON do .bicepparam pliku parametrów.

bicep decompile-params azuredeploy.parameters.json --bicep-file ./dir/main.bicep

To polecenie dekompiluje plik parametrów azuredeploy.parameters.json do pliku azuredeploy.parameters.bicepparam . Użyj --bicep-file, aby określić ścieżkę do pliku Bicep (względem pliku .bicepparam), do którego odwołuje się deklaracja using.

format

Polecenie format formatuje plik Bicep tak, aby był zgodny z zalecanymi konwencjami stylu. Pomyśl o nim jako formatatora kodu lub "ładniejszy" dla plików Bicep. Ma tę samą funkcję co skrót SHIFT+ALT+F w Visual Studio Code.

bicep format main.bicep

generate-params

Polecenie generate-params kompiluje plik parametrów z danego pliku Bicep i aktualizuje go, jeśli istnieje istniejący plik parametrów.

bicep generate-params main.bicep --output-format bicepparam --include-params all

To polecenie tworzy plik parametrów Bicep o nazwie main.bicepparam. Plik parametrów zawiera wszystkie parametry w pliku Bicep, niezależnie od tego, czy jest skonfigurowany z wartościami domyślnymi, czy nie.

bicep generate-params main.bicep --outfile main.parameters.json

To polecenie tworzy plik parametrów o nazwie main.parameters.json. Plik parametrów zawiera tylko parametry bez wartości domyślnych skonfigurowanych w pliku Bicep.

instalować

Polecenie install dodaje interfejs wiersza polecenia Bicep do środowiska lokalnego i jest dostępny tylko za pośrednictwem Azure CLI. Aby uzyskać więcej informacji, zobacz Install Bicep tools.

Aby zainstalować najnowszą wersję, użyj:

N/A

Aby zainstalować określoną wersję, użyj następującego polecenia:

N/A

jsonrpc

Polecenie jsonrpc uruchamia interfejs wiersza polecenia Bicep z interfejsem JSON-RPC. Za pomocą tego interfejsu można programowo wchodzić w interakcje ze strukturą danych wyjściowych. Należy również unikać opóźnień zimnego startu podczas kompilowania wielu plików. Ta konfiguracja obsługuje tworzenie bibliotek do interakcji z plikami Bicep programowo w językach innych niż .NET.

Format przewodu do wysyłania i odbierania danych wejściowych i wyjściowych jest rozdzielany nagłówkami. Używa następującej struktury, gdzie \r i \n reprezentują znaki powrotu karetki i wiersza:

Content-Length: <length>\r\n\r\n<message>\r\n\r\n
  • <length> to długość <message> ciągu, w tym ciąg końcowy \r\n\r\n.
  • <message> to nieprzetworzona wiadomość JSON.

Na przykład:

Content-Length: 72\r\n\r\n{"jsonrpc": "2.0", "id": 0, "method": "bicep/version", "params": {}}\r\n\r\n

Następujące metody są dostępne za pośrednictwem interfejsu JSON-RPC:

  • bicep/format

    Formatuje plik Bicep.

    • Żądanie:

      {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "bicep/format",
  "params": {
    "path": "/path/to/file.bicep"
  }
}

    • Odpowiedź:

      {
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true,
    "diagnostics": [],
    "contents": "param foo string\n\nresource storage 'Microsoft.Storage/storageAccounts@2025-01-01' = {\n  name: 'mystorageaccount'\n  location: 'East US'\n}\n"
  }
}

      Po pomyślnym "success": true jest zwracana zawartość zawierająca sformatowane źródło Bicep. W przypadku awarii z "success": false opisem diagnostics błędu.

  • bicep/wersja

    Zwraca wersję interfejsu wiersza polecenia Bicep.

    • Żądanie:

      {
  "jsonrpc": "2.0",
  "id": 0,
  "method": "bicep/version",
  "params": {}
}

    • Odpowiedź:

      {
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "version": "0.24.211"
  }
}

Aby uzyskać dostępne metody i treść żądania i odpowiedzi, zobacz ICliJsonRpcProtocol.cs. Aby zapoznać się z przykładem nawiązywania połączenia JSONRPC i programowego korzystania z plików Bicep za pomocą węzła, zobacz jsonrpc.test.ts.

Użycie nazwanego potoku

Użyj następującej składni, aby nawiązać połączenie z istniejącym nazwanym potokiem jako klientem JSONRPC:

bicep jsonrpc --pipe <named_pipe>`

<named_pipe> to istniejący nazwany potok do połączenia klienta JSONRPC z.

Aby nawiązać połączenie z nazwanym potokiem w systemie macOS lub Linux:

bicep jsonrpc --pipe /tmp/bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock

Aby nawiązać połączenie z nazwanym potokiem na Windows:

bicep jsonrpc --pipe \\.\pipe\\bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock`

Aby uzyskać więcej przykładów, zobacz C# i node.js.

Użycie gniazda TCP

Użyj następującej składni, aby nawiązać połączenie z istniejącym gniazdem TCP jako klientem JSONRPC:

bicep jsonrpc --socket <tcp_socket>

<tcp_socket> to numer gniazda, z którym łączy się klient JSONRPC.

Aby nawiązać połączenie z gniazdem TCP:

bicep jsonrpc --socket 12345

Użycie dla stdin i stdout

Aby uruchomić interfejs JSONRPC, użyj następującej składni. Użyj i stdinstdout dla komunikatów:

bicep jsonrpc --stdio

Lint

Polecenie lint zwraca błędy i regułę linter naruszenia pliku Bicep.

bicep lint main.bicep

Jeśli plik Bicep zawiera moduł odwołujący się do rejestru zewnętrznego, polecenie lint automatycznie wywołuje polecenie restore. Polecenie restore pobiera plik z rejestru i zapisuje go w lokalnej pamięci podręcznej.

Uwaga

Polecenie restore nie odświeża pamięci podręcznej. Aby uzyskać więcej informacji, zobacz przywracanie.

Aby zapobiec automatycznemu przywracaniu, użyj przełącznika --no-restore :

bicep lint --no-restore <bicep-file>

Proces lint z przełącznikiem kończy się niepowodzeniem --no-restore , jeśli jeden z modułów zewnętrznych nie jest jeszcze buforowany:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not been restored.

Po wystąpieniu tego błędu uruchom lint polecenie bez przełącznika --no-restore lub uruchom bicep restore polecenie jako pierwsze.

list-versions

Polecenie list-versions zwraca wszystkie dostępne wersje interfejsu wiersza polecenia Bicep. Użyj tego polecenia, aby sprawdzić, czy chcesz uaktualnić lub zainstalować nową wersję. To polecenie jest dostępne tylko za pośrednictwem Azure CLI.

N/A

publikować

Polecenie publish dodaje moduł do rejestru. Rejestr kontenerów Azure musi istnieć, a publikowanie konta w rejestrze musi mieć odpowiednie uprawnienia. Aby uzyskać więcej informacji na temat konfigurowania rejestru modułów, zobacz Użyj rejestru prywatnego dla modułów Bicep. Aby opublikować moduł, konto musi mieć prawidłowy profil i uprawnienia dostępu do rejestru. Można skonfigurować pierwszeństwo profilu i poświadczeń na potrzeby uwierzytelniania w rejestrze w pliku konfiguracji Bicep.

Po opublikowaniu pliku w rejestrze można odwoływać się do niego w module.

Musisz mieć interfejs wiersza polecenia Bicep w wersji 0.14.X lub nowszej, aby użyć polecenia publish oraz parametru --documentationUri/-d.

Aby opublikować moduł w rejestrze, użyj:

bicep publish <bicep-file> --target br:<registry-name>.azurecr.io/<module-path>:<tag> --documentationUri <documentation-uri>

Na przykład:

bicep publish storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 --documentationUri https://www.contoso.com/exampleregistry.html

Polecenie publish nie rozpoznaje aliasów określonych w pliku bicepconfig.json. Podaj pełną ścieżkę modułu.

Ostrzeżenie

Publikowanie w tym samym obiekcie docelowym zastępuje stary moduł. Zwiększ wersję podczas aktualizowania.

przywracać

Gdy plik Bicep używa modułów publikowanych w rejestrze, polecenie restore pobiera kopie wszystkich wymaganych modułów z rejestru. Przechowuje te kopie w lokalnej pamięci podręcznej. Plik Bicep można skompilować tylko wtedy, gdy pliki zewnętrzne są dostępne w lokalnej pamięci podręcznej. Zwykle uruchamianie przywracania nie jest konieczne, ponieważ jest ono automatycznie wyzwalane przez proces kompilacji.

Aby przywrócić moduły zewnętrzne do lokalnej pamięci podręcznej, konto musi mieć prawidłowy profil i uprawnienia dostępu do rejestru. Możesz skonfigurować pierwszeństwo profile i poświadczenia na potrzeby uwierzytelniania w rejestrze w pliku konfiguracji Bicep.

Aby użyć polecenia restore, musisz mieć Bicep interfejs wiersza polecenia w wersji 0.14.X lub nowszej.

Aby ręcznie przywrócić moduły zewnętrzne dla pliku, użyj:

bicep restore <bicep-file>

Plik Bicep, który podajesz, to plik, który chcesz wdrożyć. Musi zawierać moduł, który łączy się z rejestrem. Można na przykład przywrócić następujący plik:

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Lokalna pamięć podręczna znajduje się w:

  • W Windows

    %USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>

  • W systemie Linux

    /home/<username>/.bicep

  • Na komputerze Mac

    ~/.bicep

Polecenie restore nie odświeża pamięci podręcznej, jeśli moduł jest już buforowany. Aby odświeżyć pamięć podręczną, możesz usunąć ścieżkę modułu z pamięci podręcznej lub użyć przełącznika --forcerestore za pomocą polecenia .

migawka

Korzystając z interfejsu wiersza polecenia Bicep w wersji 0.41.2 lub nowszej, można użyć polecenia snapshot, aby utworzyć znormalizowaną, deterministyczną reprezentację wdrożenia Bicep z pliku .bicepparam. Możesz porównać tę migawkę z późniejszymi migawkami, aby zrozumieć, jakie zmiany spowodowałyby refaktoryzację, bez wdrażania niczego w Azure. To polecenie jest szczególnie przydatne w następujących celach:

  • Różnice wizualne: wyświetlanie dokładnie tego, jak refaktoryzacja (na przykład przenoszenie kodu do modułu) zmienia podstawowe definicje zasobów.
  • Wyrażenia złożone: informacje o tym, co faktycznie oblicza złożony ciąg lub zmienną przed wdrożeniem.
  • Weryfikacja ciągłej integracji/ciągłego wdrażania: Automatyczne przechwytywanie niezamierzonych zmian logiki infrastruktury podczas żądań ściągnięcia.

Utwórz migawkę

To polecenie generuje .snapshot.json plik. Ten plik jest "znormalizowany", co oznacza, że usuwa szum, taki jak granice modułu, dzięki czemu można skupić się na samych zasobach.

bicep snapshot --mode overwrite <bicep-param-file>

Poniższy plik JSON przedstawia przykład migawki:

{
  "predictedResources": [
    {
      "id": "[format('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Storage/storageAccounts/stmyappstorage001', subscription().subscriptionId, resourceGroup().name)]",
      "type": "Microsoft.Storage/storageAccounts",
      "name": "stmyappstorage001",
      "apiVersion": "2025-01-01",
      "location": "eastus",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2"
    }
  ],
  "diagnostics": []
}

Weryfikowanie zmian

Po utworzeniu migawki uruchom polecenie w trybie weryfikacji. Porównuje bieżący kod Bicep z zapisaną migawką i pokazuje różnice wizualne, podobnie jak what-if polecenie, ale całkowicie lokalne.

bicep snapshot --mode validate <bicep-param-file>

Przykładowe dane wyjściowe wyglądają następująco:

PS C:\bicep> bicep snapshot --mode validate main.bicepparam
Snapshot validation failed. Expected no changes, but found the following:

Scope: <unknown>

  ~ [format('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Storage/storageAccounts/stmyappstorage001', subscription().subscriptionId, resourceGroup().name)]
    ~ apiVersion: "2025-01-01" => "2025-06-01"
    ~ sku.name:   "Standard_LRS" => "Standard_GRS"

"Weryfikacja migawki nie powiodła się" wskazuje różnice między dwoma migawkami.

Bicep migawki interfejsu wiersza polecenia i analizy co-jeżeli mają następujące różnice:

Funkcja bicep snapshot az deployment group what-if
Wykonanie Tylko lokalny (offline) Oparte na chmurze (online)
Porównanie Porównuje kod a zapisany plik Porównuje kod a stan Azure na żywo
Szybkość Bardzo szybko Wolniejsze (wymaga wywołań interfejsu API)
Przypadek użycia Refaktoryzacja i testowanie logiki Końcowe sprawdzanie przed wdrożeniem

Podaj kontekst

Podczas uruchamiania migawki Bicep interfejs wiersza polecenia wykonuje lokalną ocenę kodu. Ponieważ nie rozmawia z Azure, nie może "zapytać" chmury o identyfikator subskrypcji lub bieżącą nazwę grupy zasobów.

Jeśli kod używa funkcji środowiska (takich jak subscription().id), migawka zakończy się niepowodzeniem lub zwróci symbole zastępcze, chyba że zostanie określony kontekst za pośrednictwem argumentów interfejsu wiersza polecenia.

Aby zasymulować rzeczywiste środowisko wdrażania, można przekazać następujące flagi:

Argument Przeznaczenie Przykładowa wartość
--subscription-id Zamienia wartość zwracaną przez subscription().subscriptionId 00000000-1111-2222-3333-444444444444
--resource-group Zamienia wartość zwracaną przez resourceGroup().name my-production-rg
--location Ustawia domyślną lokalizację dla deployment().location westeurope
--tenant-id Zamienia wartość zwracaną przez tenant().tenantId 72f988bf-86f1-41af-91ab-2d7cd011db47
--management-group Zamienia wartość zwracaną przez managementGroup().name my-corp-mg 
bicep snapshot main.bicepparam \
  --subscription-id 00000000-0000-0000-0000-000000000000 \
  --resource-group my-temp-rg \
  --location eastus \
  --mode overwrite

aktualizować

Polecenie upgrade aktualizuje zainstalowaną wersję przy użyciu najnowszej wersji. To polecenie jest dostępne tylko za pośrednictwem Azure CLI.

N/A

wersja

Polecenie version zwraca zainstalowaną wersję:

bicep --version

Jeśli nie zainstalowano interfejsu wiersza polecenia Bicep, zostanie wyświetlony komunikat o błędzie informujący, że nie znaleziono interfejsu wiersza polecenia Bicep.

Polecenie wyświetla numer wersji:

Bicep CLI version 0.29.45 (57a44c0230)

Następne kroki

Aby dowiedzieć się więcej na temat wdrażania pliku Bicep, zobacz:

  • Last updated on