Referência de esquema de propriedade get do manifesto do recurso DSC

Artigo
05/11/2024

Sinopse

Define como recuperar uma instância de recurso DSC.

Metadados

SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json
Type:          object

Descrição

Cada recurso DSC baseado em comando deve definir a get propriedade em seu manifesto. Essa propriedade define como o DSC pode obter o estado atual de uma instância de recurso.

O DSC envia dados para o comando de três maneiras:

Quando input é stdin, o DSC envia os dados como uma cadeia de caracteres que representa os dados como um objeto JSON compactado sem espaços ou novas linhas entre as propriedades do objeto.
Quando input é env, o DSC envia os dados como variáveis de ambiente. Ele cria uma variável de ambiente para cada propriedade no objeto de dados de entrada, usando o nome e o valor da propriedade.
Quando a args matriz inclui uma definição de argumento de entrada JSON, o DSC envia os dados como uma cadeia de caracteres que representa os dados como um objeto JSON compactado para o argumento especificado.

Se você não definir a input propriedade e não definir um argumento de entrada JSON, o DSC não poderá passar o JSON de entrada para o recurso. Você só pode definir um argumento de entrada JSON para um comando.

Você deve definir a input propriedade , um argumento de entrada JSON na matriz de args propriedades ou ambos.

Exemplos

Exemplo 1 – Definição mínima

Este exemplo é do Microsoft/OSInfo recurso DSC.

"get": {
  "executable": "osinfo"
}

Ele define apenas a executable propriedade . Quando um manifesto não define args, o DSC não passa argumentos para o comando . Quando um manifesto não define input, o comportamento padrão é enviar um blob JSON para o comando por .stdin

Com essa definição, o DSC chama o get método para esse recurso executando:

{ ... } | osinfo

Exemplo 2 – Entrada de stdin

Este exemplo é do Microsoft.Windows/Registry recurso DSC.

"get": {
  "executable": "registry",
  "args": [
    "config",
    "get"
  ],
  "input": "stdin"
}

Ele define executable como registry, em vez de registry.exe. A extensão não é necessária quando o sistema operacional reconhece o comando como um executável. O manifesto define dois argumentos e configget. A input propriedade indica que o get comando espera sua entrada como um blob JSON de stdin. Combinado com o valor de executable, o DSC chama o método get para esse recurso executando:

{ ... } | registry config get

Exemplo 3 – Argumento de entrada JSON

Este exemplo usa um argumento de entrada JSON para enviar os dados para o comando .

"get": {
  "executable": "tstoy",
  "args": [
    "config",
    "get",
    { "jsonInputArg": "--input", "mandatory": true }
  ],
}

Ele define o executável como tstoy. Ele define dois argumentos de cadeia de caracteres e um argumento de entrada JSON. Quando o DSC invoca a get operação para esse recurso, ele passa os dados JSON para o recurso como uma cadeia de caracteres JSON compactada para o --input argumento .

A chamada combinada para esta operação é:

tstoy config get --input "{ ... }"

Em que { ... } representa o JSON compactado para a instância de recurso.

Como a opção mandatory para o argumento de entrada JSON está definida como true, o DSC passa uma cadeia de caracteres vazia para o argumento quando não há dados a serem enviados para o comando. Se a propriedade não foi definida ou foi definida como false, o DSC omitirá o argumento inteiramente quando não houver dados a serem enviados.

Propriedades obrigatórias

A get definição deve incluir estas propriedades:

executable

Propriedades

executável

A executable propriedade define o nome do comando a ser executado. O valor deve ser o nome de um comando detectável na variável de ambiente do PATH sistema ou o caminho completo para o comando. Uma extensão de arquivo só é necessária quando o comando não é reconhecível pelo sistema operacional como um executável.

Type:     string
Required: true

args

A args propriedade define a lista de argumentos a serem passados para o comando . Os argumentos podem ser qualquer número de cadeias de caracteres. Se você quiser passar o objeto JSON que representa o recipiente de propriedades do recurso para um argumento, poderá definir um único item na matriz como um [objeto JSON], indicando o nome do argumento com a jsonInputArg propriedade string e se o argumento é obrigatório para o comando com a mandatory propriedade booleana.

Type:     array
Required: false
Default:  []
Type:     [string, object(JSON Input Argument)]

Argumentos de cadeia de caracteres

Qualquer item na matriz de argumentos pode ser uma cadeia de caracteres que representa um argumento estático para passar para o comando, como config ou --format.

Type: string

Argumento de entrada JSON

Define um argumento para o comando que aceita o objeto de entrada JSON como uma cadeia de caracteres. O DSC passa a entrada JSON para o argumento nomeado quando disponível. Um argumento de entrada JSON é definido como um objeto JSON com as seguintes propriedades:

jsonInputArg (obrigatório) – o argumento para passar os dados JSON para o comando , como --input.
mandatory (opcional) – Indique se o DSC deve sempre passar o argumento para o comando, mesmo quando não houver nenhuma entrada JSON para o comando. Nesse caso, o DSC passa uma cadeia de caracteres vazia para o argumento de entrada JSON.

Você só pode definir um argumento de entrada JSON por matriz de argumentos.

Se você definir um argumento de entrada JSON e um input tipo para um comando, o DSC enviará os dados JSON de ambas as maneiras:

Se você definir input como env e um argumento de entrada JSON, o DSC definirá uma variável de ambiente para cada propriedade na entrada JSON e passará o objeto de entrada JSON como uma cadeia de caracteres para o argumento definido.
Se você definir input como stdin e um argumento de entrada JSON, o DSC passará a entrada JSON sobre stdin e como uma cadeia de caracteres para o argumento definido.
Se você definir um argumento de entrada JSON sem definir a propriedade, o input DSC passará apenas a entrada JSON como uma cadeia de caracteres para o argumento definido.

Se você não definir a input propriedade e não definir um argumento de entrada JSON, o DSC não poderá passar o JSON de entrada para o recurso. Isso torna o manifesto inválido. Você deve definir a input propriedade , um argumento de entrada JSON na matriz de args propriedades ou ambos.

Type:                object
RequiredProperties: [jsonInputArg]

input

A input propriedade define como passar a entrada para o recurso. Se essa propriedade não estiver definida e a definição não definir um argumento de entrada JSON, o DSC não enviará nenhuma entrada para o recurso ao invocar a get operação.

O valor dessa propriedade deve ser uma das seguintes cadeias de caracteres:

env - Indica que o recurso espera que as propriedades de uma instância sejam especificadas como variáveis de ambiente com os mesmos nomes e maiúsculas e minúsculas.

Essa opção só dá suporte aos seguintes tipos de dados para propriedades de instância:
- boolean
- integer
- number
- string
- array de integer valores
- array de number valores
- array de string valores
Para valores que não são de matriz, o DSC define a variável de ambiente como o valor especificado no estado em que se encontra. Quando o tipo de dados é uma matriz de valores, o DSC define a variável de ambiente como uma cadeia de caracteres delimitada por vírgulas. Por exemplo, a propriedade foo com um valor de [1, 2, 3] é salva na variável de foo ambiente como "1,2,3".

Se o recurso precisar dar suporte a propriedades complexas com um object valor ou matrizes de vários tipos, defina-o como stdin .
stdin - Indica que o recurso espera um blob JSON que representa uma instância de stdin. O JSON deve aderir ao esquema de instância do recurso.

Type:        string
Required:    false
ValidValues: [env, stdin]

Compartilhar via