Programmgesteuerte Bicep Verwendung mit JSON-RPC

Der Befehl jsonrpc führt die Bicep CLI mit einer JSON-RPC Schnittstelle aus. Mithilfe dieser Schnittstelle können Sie programmgesteuert mit strukturierter Ausgabe interagieren. Sie vermeiden auch Verzögerungen beim Kaltstart beim Kompilieren mehrerer Dateien. Dieses Setup unterstützt das Erstellen von Bibliotheken für die programmgesteuerte Interaktion mit Bicep.

Drahtformat

Das Drahtformat entspricht der JSON-RPC 2.0-Spezifikation. Jede Nachricht ist durch Kopfzeilen getrennt, wobei die folgende Struktur verwendet wird, wobei \r Wagenrücklauf- und Zeilenvorschubzeichen dargestellt werden \n :

Content-Length: <length>\r\n\r\n<message>\r\n\r\n

• <length> ist die Länge der <message> Zeichenfolge, einschließlich des nachgestellten \r\n\r\n.
• <message> ist die unformatierte JSON-Nachricht.

So rufen Sie beispielsweise die bicep/version Methode auf:

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

Das entsprechende Ergebnis sieht wie folgt aus:

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

Methodik

Die folgenden Methoden sind über die JSON-RPC Schnittstelle verfügbar.

bicep/version

Gibt die Version der Bicep CLI zurück.

Params

Diese Methode verwendet keine Params.

Ergebnis

Beispiel

Params:

{}

Ergebnis:

{
  "version": "0.24.211"
}

bicep/compile

Kompiliert eine angegebene .bicep Datei und gibt die kompilierte ARM-Vorlagen-JSON zurück.

Params

Ergebnis

Beispiel

Params:

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

Ergebnis:

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

bicep/compileParams

Kompiliert eine angegebene .bicepparam Datei. Gibt die kompilierten Parameter JSON und die zugeordnete Vorlage zurück.

Params

Ergebnis

Beispiel

Params:

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

Ergebnis:

{
  "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

Gibt Metadaten zu einer angegebenen .bicep Datei zurück, einschließlich Parametern, Ausgaben, Exporten und Metadatendekortoren.

Params

Ergebnis

Beispiel

Params:

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

Ergebnis:

{
  "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

Gibt das Bereitstellungsdiagramm für eine angegebene .bicep Datei zurück, das die Ressourcen und deren Abhängigkeiten beschreibt.

Params

Ergebnis

Beispiel

Params:

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

Ergebnis:

{
  "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

Ruft die vollständige Liste der Dateipfade ab, auf die von einer Kompilierung verwiesen wird. Nützlich, um eine Reihe von Dateien zu bestimmen, die auf Änderungen überwacht werden sollen.

Params

Ergebnis

Beispiel

Params:

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

Ergebnis:

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

bicep/getSnapshot

Erstellt eine Bereitstellungsmomentaufnahme für eine bestimmte .bicepparam Datei. Die Momentaufnahme bündelt alle Informationen, die für die Bereitstellung in einem einzigen eigenständigen JSON-Dokument erforderlich sind.

Params

Ergebnis

Beispiel

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": []
}

Ergebnis:

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

bicep/format

Formatiert eine angegebene .bicep Datei.

Params

Ergebnis

Beispiel

Params:

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

Ergebnis:

{
  "contents": "..."
}

Typen

Die folgenden Typen werden in Methodeneingaben und -ausgaben verwendet.

Position

Stellt eine nullbasierte Position innerhalb einer Bicep Quelldatei dar.

Bereich

Stellt einen Bereich in einer Bicep Quelldatei dar.

DiagnosticDefinition

Stellt eine Diagnosenachricht dar, die während der Kompilierung oder Analyse erstellt wurde.

MetadataDefinition

Stellt einen Metadateneintrag auf Dateiebene dar, der mit dem metadata Schlüsselwort deklariert ist.

SymbolDefinition

Stellt einen Parameter oder ein Ausgabesymbol in einer Bicep Datei dar.

TypeDefinition

Stellt einen Typverweis für einen Parameter oder eine Ausgabe dar.

ExportDefinition

Stellt ein exportiertes Symbol dar, das mit dem @export() Dekorateur deklariert ist.

Node

Stellt einen Ressourcenknoten in einem Bereitstellungsdiagramm dar.

Microsoft Edge

Stellt einen gerichteten Abhängigkeitsrand zwischen zwei Ressourcenknoten in einem Bereitstellungsdiagramm dar.

SnapshotMetadata

Stellt Azure Bereitstellungskontext für die Momentaufnahmegenerierung bereit. Alle Felder sind optional.

ExternalInputValue

Stellt einen externen Eingabewert dar, der in eine Momentaufnahme eingefügt werden soll.

Verwendung

Mit benannten Rohrtransporten

Verwenden Sie das Argument --pipe, um eine benannte Pipe für die Bicep CLI zur Verbindung zu übergeben. Beachten Sie, dass der Aufrufvorgang die Pipe bereits als Server initiiert haben muss, und Bicep CLI eine Verbindung als Client herstellt.

bicep jsonrpc --pipe <named_pipe>

<named_pipe> ist eine vorhandene benannte Pipe, mit der der JSON-RPC Client verbunden werden soll.

Beispiel

So stellen Sie eine Verbindung mit einer benannten Pipe unter macOS oder Linux her:

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

So stellen Sie eine Verbindung mit einer benannten Pipe auf Windows her:

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

Mit TCP-Sockettransport

Verwenden Sie das Argument --socket, um einen TCP-Port für die Bicep CLI zur Verbindung zu übergeben. Beachten Sie, dass der Aufrufvorgang bereits auf Verbindungen am Port lauschen muss.

bicep jsonrpc --socket <tcp_socket>

<tcp_socket> ist die Socketnummer, mit der der JSON-RPC Client eine Verbindung herstellt.

Beispiel

So stellen Sie eine Verbindung mit einem TCP-Socket her:

bicep jsonrpc --socket 12345

Mit Stdin/Stdout-Transport

Verwenden Sie die folgende Syntax, um den JSON-RPC-Server mit Anforderungsdaten zu starten, die über Stdin empfangen wurden, und Antwortdaten, die über stdout gesendet werden.

bicep jsonrpc --stdio

.NET-Clientbibliothek

Die Azure.Bicep. RpcClient NuGet-Paket stellt eine .NET Clientbibliothek für die Bicep JSON-RPC Schnittstelle bereit. Sie kann die angegebene Version der Bicep CLI automatisch herunterladen und den Lebenszyklus verwalten, sodass Sie sie nicht separat installieren müssen.

Beispiel

Im folgenden Beispiel werden Bicep CLI-Version 0.39.26 heruntergeladen, eine Bicep Datei kompiliert und die resultierende ARM-Vorlage gedruckt:

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);