Udostępnij za pośrednictwem

Manifest zasobu DSC — uzyskiwanie odwołania do schematu właściwości

  • Artykuł

Streszczenie

Definiuje sposób pobierania wystąpienia zasobu DSC.

Metadane

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

Opis

Każdy zasób DSC oparty na poleceniach musi zdefiniować get właściwość w manifeście. Ta właściwość definiuje sposób, w jaki dsC może uzyskać bieżący stan wystąpienia zasobu.

DsC wysyła dane do polecenia na trzy sposoby:

  1. Gdy input jest stdinto , DSC wysyła dane jako ciąg reprezentujący dane jako skompresowany obiekt JSON bez spacji lub nowych linii między właściwościami obiektu.
  2. Gdy input jest to env, DSC wysyła dane jako zmienne środowiskowe. Tworzy zmienną środowiskową dla każdej właściwości w obiekcie danych wejściowych przy użyciu nazwy i wartości właściwości.
  3. Gdy tablica args zawiera definicję argumentu wejściowego JSON, DSC wysyła dane jako ciąg reprezentujący dane jako skompresowany obiekt JSON do określonego argumentu.

Jeśli nie zdefiniujesz właściwości i nie zdefiniujesz argumentu input wejściowego JSON, usługa DSC nie może przekazać wejściowego kodu JSON do zasobu. Dla polecenia można zdefiniować tylko jeden argument wejściowy JSON.

Należy zdefiniować input właściwość , jeden argument wejściowy JSON w tablicy args właściwości lub oba te elementy.

Przykłady

Przykład 1 — minimalna definicja

Ten przykład pochodzi z Microsoft/OSInfo zasobu DSC.

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

Definiuje tylko executable właściwość . Gdy manifest nie definiuje args, DSC nie przekazuje żadnych argumentów do polecenia . Jeśli manifest nie definiuje input, domyślnym zachowaniem jest wysłanie obiektu blob JSON do polecenia za pomocą polecenia stdin.

Z tą definicją DSC wywołuje metodę get dla tego zasobu, uruchamiając polecenie:

{ ... } | osinfo

Przykład 2 — dane wejściowe z narzędzia stdin

Ten przykład pochodzi z Microsoft.Windows/Registry zasobu DSC.

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

Definiuje executable jako registry, a nie registry.exe. Rozszerzenie nie jest wymagane, gdy system operacyjny rozpoznaje polecenie jako plik wykonywalny. Manifest definiuje dwa argumenty config i get. Właściwość input wskazuje, że get polecenie oczekuje danych wejściowych jako obiektu blob JSON z stdin. W połączeniu z wartością , executableDSC wywołuje metodę get dla tego zasobu, uruchamiając polecenie:

{ ... } | registry config get

Przykład 3 — argument wejściowy JSON

W tym przykładzie użyto argumentu wejściowego JSON, aby wysłać dane do polecenia.

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

Definiuje plik wykonywalny jako tstoy. Definiuje dwa argumenty ciągu i jeden argument wejściowy JSON. Gdy dsC wywołuje operację get dla tego zasobu, przekazuje dane JSON do zasobu jako skompresowany ciąg JSON do argumentu --input .

Połączone wywołanie dla tej operacji to:

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

Gdzie { ... } reprezentuje skompresowany kod JSON dla wystąpienia zasobu.

mandatory Ponieważ opcja argumentu wejściowego JSON jest ustawiona na true, DSC przekazuje pusty ciąg do argumentu, gdy nie ma danych do wysłania do polecenia. Jeśli właściwość nie została zdefiniowana lub została zdefiniowana jako false, DSC całkowicie pominą argument, gdy nie ma danych do wysłania.

Wymagane właściwości

Definicja get musi zawierać następujące właściwości:

Właściwości

Pliku wykonywalnego

Właściwość executable definiuje nazwę polecenia do uruchomienia. Wartość musi być nazwą polecenia wykrywalnego w zmiennej środowiskowej systemu PATH lub pełną ścieżką do polecenia. Rozszerzenie pliku jest wymagane tylko wtedy, gdy polecenie nie jest rozpoznawalne przez system operacyjny jako plik wykonywalny.

Type:     string
Required: true

args

Właściwość args definiuje listę argumentów, które mają być przekazywane do polecenia. Argumenty mogą być dowolną liczbą ciągów. Jeśli chcesz przekazać obiekt JSON reprezentujący torbę właściwości dla zasobu do argumentu, możesz zdefiniować pojedynczy element w tablicy jako obiekt [JSON], wskazując nazwę argumentu z jsonInputArg właściwością string i czy argument jest obowiązkowy dla polecenia z mandatory właściwością logiczną.

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

Argumenty ciągów

Każdy element w tablicy argumentów może być ciągiem reprezentującym argument statyczny, który ma zostać przekazany do polecenia, na przykład config lub --format.

Type: string

Argument wejściowy JSON

Definiuje argument polecenia, który akceptuje obiekt wejściowy JSON jako ciąg. DsC przekazuje dane wejściowe JSON do nazwanego argumentu, gdy jest dostępny. Argument wejściowy JSON jest definiowany jako obiekt JSON z następującymi właściwościami:

  • jsonInputArg (wymagane) — argument umożliwiający przekazanie danych JSON do polecenia, na przykład --input.
  • mandatory (opcjonalnie) — wskazuje, czy dsC zawsze powinien przekazać argument do polecenia, nawet jeśli nie ma danych wejściowych JSON dla polecenia. W takim przypadku DSC przekazuje pusty ciąg do argumentu wejściowego JSON.

Można zdefiniować tylko jeden argument wejściowy JSON dla tablicy argumentów.

Jeśli zdefiniujesz argument wejściowy JSON i input rodzaj polecenia, usługa DSC wysyła dane JSON na oba sposoby:

  • Jeśli definiujesz input jako env argument wejściowy JSON i, DSC ustawia zmienną środowiskową dla każdej właściwości w danych wejściowych JSON i przekazuje obiekt wejściowy JSON jako ciąg do zdefiniowanego argumentu.
  • Jeśli definiujesz input jako stdin i argument wejściowy JSON, DSC przekazuje dane wejściowe JSON przez stdin i jako ciąg do zdefiniowanego argumentu.
  • Jeśli definiujesz argument wejściowy JSON bez definiowania input właściwości, dsC przekazuje tylko dane wejściowe JSON jako ciąg do zdefiniowanego argumentu.

Jeśli nie zdefiniujesz właściwości i nie zdefiniujesz argumentu input wejściowego JSON, usługa DSC nie może przekazać wejściowego kodu JSON do zasobu. Powoduje to, że manifest jest nieprawidłowy. Należy zdefiniować input właściwość, argument wejściowy JSON w tablicy args właściwości lub oba te elementy.

Type:                object
RequiredProperties: [jsonInputArg]

wejście

Właściwość input definiuje sposób przekazywania danych wejściowych do zasobu. Jeśli ta właściwość nie jest zdefiniowana, a definicja nie definiuje argumentu wejściowego JSON, usługa DSC nie wysyła żadnych danych wejściowych do zasobu podczas wywoływania get operacji.

Wartość tej właściwości musi być jednym z następujących ciągów:

  • env — Wskazuje, że zasób oczekuje, że właściwości wystąpienia mają być określone jako zmienne środowiskowe o tych samych nazwach i wielkości liter.

    Ta opcja obsługuje tylko następujące typy danych dla właściwości wystąpienia:

    • boolean
    • integer
    • number
    • string
    • arraywartości integer
    • arraywartości number
    • arraywartości string

    W przypadku wartości innych niż tablica DSC ustawia zmienną środowiskową na określoną wartość zgodnie z wartością. Gdy typ danych jest tablicą wartości, DSC ustawia zmienną środowiskową jako ciąg rozdzielany przecinkami. Na przykład właściwość foo z wartością [1, 2, 3] jest zapisywana w zmiennej środowiskowej foo jako "1,2,3".

    Jeśli zasób musi obsługiwać złożone właściwości z wartością object lub tablicami wieloczęściowymi, ustaw tę wartość na stdin .

  • stdin — Wskazuje, że zasób oczekuje obiektu blob JSON reprezentującego wystąpienie z stdinklasy . Kod JSON musi być zgodny ze schematem wystąpienia zasobu.

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