Programowe użycie Bicep za pomocą kodu JSON-RPC

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 kompilowanie bibliotek do interakcji z Bicep programowo.

Format przewodu

Format przewodu jest zgodny ze specyfikacjąJSON-RPC 2.0. Każdy komunikat jest rozdzielany nagłówkami, używając 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.

Aby na przykład wywołać metodę bicep/version :

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

Odpowiedni wynik wygląda następująco:

Content-Length: 64\r\n\r\n{"jsonrpc": "2.0", "id": 0, "result": {"version": "0.38.5"}}\r\n\r\n

Methods

Poniższe metody są dostępne za pośrednictwem interfejsu JSON-RPC.

bicep/wersja

Zwraca wersję interfejsu wiersza polecenia Bicep.

Params

Ta metoda nie przyjmuje parametrów.

Wynik

Przykład

Params:

{}

Wynik:

{
  "version": "0.24.211"
}

bicep/compile

Kompiluje określony .bicep plik i zwraca skompilowany kod JSON szablonu usługi ARM.

Params

Wynik

Przykład

Params:

{
  "path": "/path/to/main.bicep"
}

Wynik:

{
  "success": true,
  "diagnostics": [],
  "contents": "{\"$schema\": \"https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#\", ...}"
}

bicep/compileParams

Kompiluje określony .bicepparam plik. Zwraca skompilowane parametry JSON i skojarzony szablon.

Params

Wynik

Przykład

Params:

{
  "path": "/path/to/main.bicepparam",
  "parameterOverrides": {}
}

Wynik:

{
  "success": true,
  "diagnostics": [],
  "parameters": "{\"$schema\": \"https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\", ...}",
  "template": "{\"$schema\": \"https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#\", ...}",
  "templateSpecId": null
}

bicep/getMetadata

Zwraca metadane dotyczące określonego .bicep pliku, w tym parametry, dane wyjściowe, eksporty i dekoratory metadanych.

Params

Wynik

Przykład

Params:

{
  "path": "/path/to/main.bicep"
}

Wynik:

{
  "metadata": [
    { "name": "description", "value": "My deployment" }
  ],
  "parameters": [
    {
      "range": { "start": { "line": 0, "char": 0 }, "end": { "line": 0, "char": 20 } },
      "name": "location",
      "type": { "range": null, "name": "string" },
      "description": "The Azure region for deployment"
    }
  ],
  "outputs": [
    {
      "range": { "start": { "line": 5, "char": 0 }, "end": { "line": 5, "char": 30 } },
      "name": "endpoint",
      "type": { "range": null, "name": "string" },
      "description": null
    }
  ],
  "exports": []
}

bicep/getDeploymentGraph

Zwraca wykres wdrożenia dla określonego .bicep pliku opisujący zasoby i ich zależności.

Params

Wynik

Przykład

Params:

{
  "path": "/path/to/main.bicep"
}

Wynik:

{
  "nodes": [
    {
      "range": { "start": { "line": 2, "char": 0 }, "end": { "line": 8, "char": 1 } },
      "name": "storageAccount",
      "type": "Microsoft.Storage/storageAccounts",
      "isExisting": false,
      "relativePath": null
    }
  ],
  "edges": [
    { "source": "roleAssignment", "target": "storageAccount" }
  ]
}

bicep/getFileReferences

Pobiera pełną listę ścieżek plików, do których odwołuje się kompilacja. Przydatne do określenia zestawu plików do obserwowanego pod kątem zmian.

Params

Wynik

Przykład

Params:

{
  "path": "/path/to/main.bicep"
}

Wynik:

{
  "filePaths": [
    "/path/to/main.bicep",
    "/path/to/modules/storage.bicep",
    "/path/to/bicepconfig.json"
  ]
}

bicep/getSnapshot

Tworzy migawkę wdrożenia dla danego .bicepparam pliku. Migawka zawiera wszystkie informacje potrzebne do wdrożenia w jednym samodzielnym dokumencie JSON.

Params

Wynik

Przykład

Params:

{
  "path": "/path/to/main.bicepparam",
  "metadata": {
    "tenantId": "00000000-0000-0000-0000-000000000000",
    "subscriptionId": "00000000-0000-0000-0000-000000000000",
    "resourceGroup": "myResourceGroup",
    "location": "eastus",
    "deploymentName": "myDeployment"
  },
  "externalInputs": []
}

Wynik:

{
  "snapshot": "{...}"
}

bicep/format

Formatuje określony .bicep plik.

Params

Wynik

Przykład

Params:

{
  "path": "/path/to/file.bicep"
}

Wynik:

{
  "contents": "..."
}

Types

Następujące typy są używane w danych wejściowych i wyjściowych metody.

Stanowisko

Reprezentuje pozycję opartą na zerze w pliku źródłowym Bicep.

Zakres

Reprezentuje zakres w pliku źródłowym Bicep.

DiagnostykaDefinition

Reprezentuje komunikat diagnostyczny generowany podczas kompilacji lub analizy.

MetadataDefinition

Reprezentuje wpis metadanych na poziomie pliku zadeklarowany za pomocą słowa kluczowego metadata .

SymbolDefinition

Reprezentuje parametr lub symbol wyjściowy w pliku Bicep.

Definicja typu

Reprezentuje odwołanie do typu dla parametru lub danych wyjściowych.

ExportDefinition (Definicje eksportu)

Reprezentuje wyeksportowany symbol zadeklarowany za pomocą dekoratora @export() .

Node

Reprezentuje węzeł zasobu na grafie wdrożenia.

Edge

Reprezentuje skierowaną krawędź zależności między dwoma węzłami zasobów na grafie wdrożenia.

SnapshotMetadata

Udostępnia Azure kontekst wdrażania na potrzeby generowania migawek. Wszystkie pola są opcjonalne.

ExternalInputValue

Reprezentuje zewnętrzną wartość wejściową do wstrzykiwania do migawki.

Użycie

Z nazwanym transportem rur

Użyj argumentu --pipe, aby przekazać nazwany potok interfejsu wiersza polecenia Bicep do nawiązania połączenia. Należy pamiętać, że proces wywołujący musi już zainicjować potok jako serwer, a Bicep interfejs wiersza polecenia połączy się jako klient.

bicep jsonrpc --pipe <named_pipe>

<named_pipe> to istniejący nazwany potok do łączenia klienta JSON-RPC z.

Przykład

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

Z transportem gniazda TCP

Użyj argumentu --socket, aby przekazać port TCP dla interfejsu wiersza polecenia Bicep do nawiązania połączenia. Należy pamiętać, że proces wywołujący musi już nasłuchiwać połączeń na porcie.

bicep jsonrpc --socket <tcp_socket>

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

Przykład

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

bicep jsonrpc --socket 12345

Z transportem stdin/stdout

Użyj następującej składni, aby uruchomić serwer JSON-RPC z danymi żądania odebranymi za pośrednictwem narzędzia stdin i danymi odpowiedzi wysyłanymi za pośrednictwem stdout.

bicep jsonrpc --stdio

biblioteka klienta .NET

Azure.Bicep. RpcClient pakiet NuGet udostępnia bibliotekę klienta .NET dla interfejsu Bicep JSON-RPC. Może automatycznie pobrać określoną wersję interfejsu wiersza polecenia Bicep i zarządzać jej cyklem życia, aby nie trzeba było go instalować oddzielnie.

Przykład

Poniższy przykład pobiera Bicep wersję interfejsu wiersza polecenia 0.39.26, kompiluje plik Bicep i drukuje wynikowy szablon usługi ARM:

using Bicep.RpcClient;

var factory = new BicepClientFactory();
using var bicep = await factory.Initialize(new() {
    BicepVersion = "0.39.26"
});

var version = await bicep.GetVersion();
Console.WriteLine($"Bicep version: {version}");

var tempFile = Path.Combine(Path.GetTempPath(), $"{Guid.NewGuid()}.bicep");
File.WriteAllText(tempFile, """
    param foo string
    output foo string = foo
    """);

var result = await bicep.Compile(new(tempFile));
Console.Write(result.Contents);