Uso de Bicep programática com JSON-RPC

O comando jsonrpc executa a CLI Bicep com uma interface JSON-RPC. Usando essa interface, você pode interagir programaticamente com a saída estruturada. Você também evita atrasos de início frio ao compilar vários arquivos. Essa configuração dá suporte à criação de bibliotecas para interagir com Bicep programaticamente.

Formato de fio

O formato de fio adere à especificaçãoJSON-RPC 2.0. Cada mensagem é delimitada por cabeçalho, usando a seguinte estrutura, onde \r e \n representam caracteres de retorno de carro e feed de linha:

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

• <length>é o comprimento da cadeia de <message> caracteres, incluindo o .\r\n\r\n
• <message> é a mensagem JSON bruta.

Por exemplo, para chamar o bicep/version método:

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

O resultado correspondente se parece com:

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

Methods

Os métodos a seguir estão disponíveis por meio da interface JSON-RPC.

bicep/versão

Retorna a versão da CLI do Bicep.

Params

Esse método não usa parâmetros.

Resultado

Exemplo

Params:

{}

Resultado:

{
  "version": "0.24.211"
}

bicep/compile

Compila um arquivo especificado .bicep e retorna o modelo do ARM compilado JSON.

Params

Resultado

Exemplo

Params:

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

Resultado:

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

bicep/compileParams

Compila um arquivo especificado .bicepparam . Retorna os parâmetros compilados JSON e o modelo associado.

Params

Resultado

Exemplo

Params:

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

Resultado:

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

Retorna metadados sobre um arquivo especificado .bicep , incluindo parâmetros, saídas, exportações e decoradores de metadados.

Params

Resultado

Exemplo

Params:

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

Resultado:

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

Retorna o grafo de implantação de um arquivo especificado .bicep , descrevendo os recursos e suas dependências.

Params

Resultado

Exemplo

Params:

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

Resultado:

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

Obtém a lista completa de caminhos de arquivo referenciados por uma compilação. Útil para determinar um conjunto de arquivos para observar as alterações.

Params

Resultado

Exemplo

Params:

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

Resultado:

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

bicep/getSnapshot

Cria um instantâneo de implantação para um determinado .bicepparam arquivo. O instantâneo agrupa todas as informações necessárias para implantação em um único documento JSON independente.

Params

Resultado

Exemplo

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

Resultado:

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

bicep/format

Formata um arquivo especificado .bicep .

Params

Resultado

Exemplo

Params:

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

Resultado:

{
  "contents": "..."
}

Tipos

Os tipos a seguir são usados em entradas e saídas de método.

Posição

Representa uma posição baseada em zero em um arquivo de origem Bicep.

Intervalo

Representa um intervalo dentro de um arquivo de origem Bicep.

DiagnosticDefinition

Representa uma mensagem de diagnóstico produzida durante a compilação ou análise.

MetadadosDefinition

Representa uma entrada de metadados no nível do arquivo declarada com a metadata palavra-chave.

SymbolDefinition

Representa um parâmetro ou símbolo de saída em um arquivo Bicep.

TypeDefinition

Representa uma referência de tipo para um parâmetro ou saída.

ExportDefinição

Representa um símbolo exportado declarado com o @export() decorador.

Node

Representa um nó de recurso em um grafo de implantação.

Edge

Representa uma borda de dependência direcionada entre dois nós de recurso em um grafo de implantação.

SnapshotMetadata

Fornece Azure contexto de implantação para geração de instantâneo. Todos os campos são opcionais.

ExternalInputValue

Representa um valor de entrada externo para injetar em um instantâneo.

Usage

Com transporte de pipe nomeado

Use o argumento --pipe para passar um pipe nomeado para a CLI do Bicep para se conectar. Observe que o processo de chamada já deve ter iniciado o pipe como um servidor e Bicep CLI se conectará como um cliente.

bicep jsonrpc --pipe <named_pipe>

<named_pipe> é um pipe nomeado existente para conectar o cliente JSON-RPC.

Exemplo

Para se conectar a um pipe nomeado no macOS ou linux:

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

Para se conectar a um pipe nomeado no Windows:

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

Com o transporte de soquete TCP

Use o argumento --socket para passar uma porta TCP para a CLI Bicep para se conectar. Observe que o processo de chamada já deve estar escutando conexões na porta.

bicep jsonrpc --socket <tcp_socket>

<tcp_socket> é o número do soquete ao qual o cliente JSON-RPC se conecta.

Exemplo

Para se conectar a um soquete TCP:

bicep jsonrpc --socket 12345

Com transporte stdin/stdout

Use a sintaxe a seguir para iniciar o servidor JSON-RPC com dados de solicitação recebidos por meio de stdin e dados de resposta enviados por meio de stdout.

bicep jsonrpc --stdio

biblioteca de clientes .NET

O Azure.Bicep. RpcClient pacote NuGet fornece uma biblioteca de cliente .NET para a interface Bicep JSON-RPC. Ele pode baixar automaticamente a versão especificada da CLI do Bicep e gerenciar seu ciclo de vida, portanto, você não precisa instalá-la separadamente.

Exemplo

O exemplo a seguir baixa Bicep versão da CLI 0.39.26, compila um arquivo Bicep e imprime o modelo do ARM resultante:

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