JSON-RPC でのプログラムによるBicepの使用

jsonrpc コマンドは、JSON-RPC インターフェイスを使用してBicep CLI を実行します。 このインターフェイスを使用すると、構造化された出力をプログラムで操作できます。 また、複数のファイルをコンパイルするときにコールド スタートの遅延を回避することもできます。 このセットアップでは、プログラムでBicepを操作するためのライブラリの構築がサポートされています。

ワイヤ形式

ワイヤ形式は 、JSON-RPC 2.0 仕様に準拠しています。 各メッセージは、次の構造を使用してヘッダーで区切られます。ここで、 \r と \n は復帰文字と改行文字を表します。

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

• <length>は、末尾の<message>を含む、\r\n\r\n文字列の長さです。
• <message> は生の JSON メッセージです。

たとえば、 bicep/version メソッドを呼び出すには、次のようにします。

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

対応する結果は次のようになります。

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

メソッド

JSON-RPC インターフェイスでは、次のメソッドを使用できます。

bicep/version

Bicep CLI のバージョンを返します。

Params

このメソッドはパラメーターを受け取っていません。

結果

例

Params：

{}

結果:

{
  "version": "0.24.211"
}

bicep/compile

指定した .bicep ファイルをコンパイルし、コンパイル済みの ARM テンプレート JSON を返します。

Params

結果

例

Params：

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

結果:

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

bicep/compileParams

指定した .bicepparam ファイルをコンパイルします。 コンパイル済みのパラメーター JSON と関連するテンプレートを返します。

Params

結果

例

Params：

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

結果:

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

パラメーター、出力、エクスポート、メタデータ デコレーターなど、指定した .bicep ファイルに関するメタデータを返します。

Params

結果

例

Params：

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

結果:

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

指定した .bicep ファイルのデプロイ グラフを返します。リソースとその依存関係について説明します。

Params

結果

例

Params：

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

結果:

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

コンパイルによって参照されるファイル パスの完全な一覧を取得します。 変更を監視するファイルのセットを決定するのに役立ちます。

Params

結果

例

Params：

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

結果:

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

bicep/getSnapshot

特定の .bicepparam ファイルのデプロイ スナップショットを作成します。 スナップショットは、デプロイに必要なすべての情報を 1 つの自己完結型 JSON ドキュメントにバンドルします。

Params

結果

例

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

結果:

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

bicep/format

指定した .bicep ファイルの書式を設定します。

Params

結果

例

Params：

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

結果:

{
  "contents": "..."
}

種類

メソッドの入力と出力では、次の型が使用されます。

職位

Bicep ソース ファイル内の 0 から始まる位置を表します。

範囲

Bicep ソース ファイル内の範囲を表します。

DiagnosticDefinition

コンパイルまたは分析中に生成された診断メッセージを表します。

MetadataDefinition

metadata キーワードで宣言されたファイル レベルのメタデータ エントリを表します。

SymbolDefinition

Bicep ファイル内のパラメーターまたは出力シンボルを表します。

TypeDefinition

パラメーターまたは出力の型参照を表します。

エクスポート定義

@export() デコレーターで宣言されたエクスポートされたシンボルを表します。

Node

デプロイ グラフ内のリソース ノードを表します。

Edge

デプロイ グラフ内の 2 つのリソース ノード間の有向依存関係エッジを表します。

SnapshotMetadata

スナップショット生成Azureデプロイ コンテキストを提供します。 すべてのフィールドは省略可能です。

ExternalInputValue

スナップショットに挿入する外部入力値を表します。

使用方法

名前付きパイプ トランスポートを使用する

--pipe 引数を使用して、接続する Bicep CLI の名前付きパイプを渡します。 呼び出し元のプロセスは既にサーバーとしてパイプを開始している必要があり、Bicep CLI はクライアントとして接続されることに注意してください。

bicep jsonrpc --pipe <named_pipe>

<named_pipe> は、JSON-RPC クライアントを接続する既存の名前付きパイプです。

例

macOS または Linux 上の名前付きパイプに接続するには:

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

Windowsの名前付きパイプに接続するには:

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

TCP ソケット トランスポートを使用する場合

Bicep CLI の接続先の TCP ポートを渡すには、--socket 引数を使用します。 呼び出し元プロセスは、ポートでの接続を既にリッスンしている必要があることに注意してください。

bicep jsonrpc --socket <tcp_socket>

<tcp_socket> は、JSON-RPC クライアントが接続するソケット番号です。

例

TCP ソケットに接続するには:

bicep jsonrpc --socket 12345

stdin/stdout トランスポートを使用する

stdin 経由で受信した要求データと stdout 経由で送信された応答データを使用して、JSON-RPC サーバーを起動するには、次の構文を使用します。

bicep jsonrpc --stdio

.NET クライアント ライブラリ

Azure.Bicep。RpcClient NuGet パッケージは、Bicep JSON-RPC インターフェイス用の.NET クライアント ライブラリを提供します。 指定したバージョンの Bicep CLI を自動的にダウンロードし、そのライフサイクルを管理できるため、個別にインストールする必要はありません。

例

次の例では、CLI バージョン 0.39.26Bicepダウンロードし、Bicep ファイルをコンパイルして、結果の 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);