Utilização programática do Bicep com JSON-RPC

O comando jsonrpc executa a CLI Bicep com uma interface JSON-RPC. Ao usar esta interface, pode interagir programaticamente com a saída estruturada. Também evita atrasos no arranque a frio ao compilar vários ficheiros. Esta configuração suporta a construção de bibliotecas para interagir programáticamente com o Bicep.

Formato de fios

O formato do fio segue a especificaçãoJSON-RPC 2.0. Cada mensagem é delimitada por cabeçalhos, usando a seguinte estrutura, onde \r e \n representam caracteres de retorno de carro e de avanço de linha:

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

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

Por exemplo, 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 é o seguinte:

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

Methods

Os seguintes métodos estão disponíveis através da interface JSON-RPC.

bíceps/versão

Devolve a versão do Bicep CLI.

Params

Este método não aceita parámetros.

Result

Exemplo

Parámetros:

{}

Resultado:

{
  "version": "0.24.211"
}

bíceps/compilar

Compila um ficheiro especificado .bicep e devolve o template ARM compilado JSON.

Params

Result

Exemplo

Parámetros:

{
  "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 ficheiro especificado .bicepparam . Devolve os parâmetros compilados JSON e o template associado.

Params

Result

Exemplo

Parámetros:

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

bícep/getMetadata

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

Params

Result

Exemplo

Parámetros:

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

Devolve o gráfico de implementação de um ficheiro especificado .bicep , descrevendo os recursos e as suas dependências.

Params

Result

Exemplo

Parámetros:

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

bíceps/getFileReferences

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

Params

Result

Exemplo

Parámetros:

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

Resultado:

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

bíceps/getSnapshot

Cria um snapshot de implementação para um determinado .bicepparam ficheiro. O snapshot agrupa toda a informação necessária para a implementação num único documento JSON autónomo.

Params

Result

Exemplo

Parámetros:

{
  "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": "{...}"
}

bíceps/formato

Formata um ficheiro especificado .bicep .

Params

Result

Exemplo

Parámetros:

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

Resultado:

{
  "contents": "..."
}

Tipos

Os seguintes tipos são usados nas entradas e saídas dos métodos.

Position

Representa uma posição baseada em zero dentro de um ficheiro-fonte Bicep.

Intervalo

Representa um intervalo dentro de um ficheiro-fonte Bicep.

Definição de Diagnóstico

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

MetadadosDefinição

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

SymbolDefinition

Representa um parâmetro ou símbolo de saída num ficheiro Bicep.

Definição de Tipo

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

ExportDefinition

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

Node

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

Edge

Representa uma aresta de dependência direcionada entre dois nós de recurso num grafo de implementação.

SnapshotMetadados

Fornece contexto de implementação no Azure para geração de snapshots. Todos os campos são opcionais.

Valor de EntradaExterna

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

Usage

Com transporte de tubos nomeado

Use o argumento --pipe para passar um canal nomeado para a Bicep CLI se ligar. Note que o processo de chamada já deve ter iniciado o pipeline como servidor, e a CLI do Bicep irá ligar-se como cliente.

bicep jsonrpc --pipe <named_pipe>

<named_pipe> é um tubo nomeado existente para ligar o cliente JSON-RPC.

Exemplo

Para se ligar a um pipe nomeado no macOS ou Linux:

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

Para ligar a um tubo nomeado no Windows:

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

Com transporte de soquete TCP

Use o argumento --socket para passar uma porta TCP para que a CLI do Bicep se ligue. Note que o processo de chamada já deve estar a ouvir ligações na porta.

bicep jsonrpc --socket <tcp_socket>

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

Exemplo

Para ligar a um soquete TCP:

bicep jsonrpc --socket 12345

Com transporte stdin/stdout

Use a seguinte sintaxe para iniciar o servidor JSON-RPC com dados de pedido recebidos via stdin e dados de resposta enviados via stdout.

bicep jsonrpc --stdio

Biblioteca cliente .NET

O Azure.Bicep. O pacote NuGet RpcClient fornece uma biblioteca cliente .NET para a interface Bicep JSON-RPC. Pode descarregar automaticamente a versão especificada do Bicep CLI e gerir o seu ciclo de vida, por isso não precisa de o instalar separadamente.

Exemplo

O exemplo seguinte descarrega Bicep versão CLI 0.39.26, compila um ficheiro Bicep e imprime o template 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);