Condividi tramite

DeclaredConfiguration CSP

  • Articolo

Logo di Windows Insider.

Importante

Questo CSP contiene alcune impostazioni in fase di sviluppo e applicabili solo per le compilazioni Windows Insider Preview. Queste impostazioni sono soggette a modifiche e potrebbero avere dipendenze da altre funzionalità o servizi in anteprima.

Il modello MDM primario è quello in cui il server MDM è l'unico responsabile dell'orchestrazione e della manutenzione continua dello stato del dispositivo per gli scenari di configurazione. Questo comportamento comporta un traffico di rete intensivo e una latenza di rete elevata a causa del modello di configurazione sincrono basato sullo standard OMA-DM Syncml. È anche soggetto a errori, dato che il server necessita di una conoscenza approfondita del client.

Il modello di gestione dei dispositivi windows dichiarato (WinDC) richiede che il server distribuirà tutti i valori di impostazione al dispositivo per la configurazione dello scenario. Il server li invia in modo asincrono in batch tramite il provider di servizi di configurazione DeclaredConfiguration.

  • Durante la sessione OMA-DM avviata dal client, il server WinDC invia una configurazione o un documento WinDC di inventario al client tramite l'URI CSP DeclaredConfiguration. Se il dispositivo verifica che la sintassi del documento sia corretta, lo stack client esegue il push della richiesta nel relativo agente di orchestrazione per elaborare la richiesta in modo asincrono. Lo stack client viene quindi chiuso e restituisce il controllo al servizio WinDC. Questo comportamento consente al dispositivo di elaborare in modo asincrono la richiesta.

  • Nel client, se sono presenti richieste in corso di elaborazione o completate, invia un avviso generico al server. Questo avviso riepiloga lo stato, lo stato e lo stato di ogni documento. Ogni richiesta HTTPS client al server WinDC OMA-DM include questo riepilogo.

  • Il server WinDC usa l'avviso generico per determinare quali richieste vengono completate correttamente o con errori. Il server può quindi recuperare in modo sincrono i risultati del processo del documento WinDC tramite l'URI CSP DeclaredConfiguration.

L'elenco seguente mostra i nodi del provider di servizi di configurazione DeclaredConfiguration:

Host

Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host

Il nodo interno host indica che la destinazione della richiesta di configurazione o della richiesta di inventario è il sistema operativo host. Questo nodo è destinato all'ambito nel caso in cui le enclave siano mai destinate alla configurazione.

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato node
Tipo accesso Add, Delete, Get

Host/Completamento

Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete

Questo nodo interno indica che la configurazione ha valori di impostazioni discreti ed è indipendente con coppie complete di impostazione e valore che non contengono segnaposto che devono essere risolti in un secondo momento con dati aggiuntivi. La richiesta è pronta per essere elaborata così come è.

Il flusso da server a client della richiesta Completa è lo stesso di una richiesta di inventario .

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato node
Tipo accesso Add, Delete, Get

Host/Complete/Documents

Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents

Il nodo Documenti indica che la configurazione è sotto forma di documento, ovvero una raccolta di impostazioni usate per configurare uno scenario dallo stack di configurazione dichiarato.

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato node
Tipo accesso Add, Delete, Get
Host/Complete/Documents/{DocID}
Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}

Identifica in modo univoco il documento di configurazione. Nessun altro documento può avere questo ID. L'ID deve essere un GUID.

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato node
Tipo accesso Add, Delete, Get
Denominazione dinamica dei nodi ServerGeneratedUniqueIdentifier
Valori consentiti Espressione regolare: [0-9A-Fa-f]{8}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{12}
Host/Complete/Documents/{DocID}/Document
Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/Document

Il valore del nodo Document è un documento basato su XML contenente una raccolta di impostazioni e valori per configurare lo scenario specificato. Lo stack di configurazione dichiarato verifica la sintassi del documento. Lo stack contrassegna il documento per l'elaborazione asincrona da parte del client. Lo stack restituisce quindi il controllo al servizio OMA-DM. Lo stack, a sua volta, elabora in modo asincrono la richiesta. Di seguito è riportato un esempio di configurazione dello stato desiderato specificata che usa l'URI di configurazione dichiarato ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68. B9-4320-9. FC4-296. F6FDFAFE2/Documento.

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato chr (stringa)
Tipo accesso Aggiungere, eliminare, ottenere, sostituire
Host/Complete/Documents/{DocID}/Properties
Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/Properties

Il nodo Proprietà incapsula l'elenco di proprietà che si applicano al documento specificato a cui fa riferimento [DocID].

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato node
Tipo accesso Add, Delete, Get
Host/Complete/Documents/{DocID}/Properties/Abandoned
Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/Properties/Abandoned

Il nodo Abbandonato consente al server OMA-DM di indicare che il documento non è più gestito.

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato int
Tipo accesso Aggiungere, eliminare, ottenere, sostituire
Valore predefinito 0

Valori consentiti:

Value Descrizione
0 (Predefinito) Il documento non è più gestito.
1 Il documento è gestito.

Host/Completamento/Risultati

Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results

Il nodo Risultati indica che fa parte del percorso URI che restituirà un documento XML contenente i risultati della richiesta di configurazione.

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato node
Tipo accesso Ottieni
Host/Complete/Results/{DocID}
Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/{DocID}

Identifica in modo univoco il documento di configurazione in cui verranno restituiti i risultati della richiesta di configurazione.

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato node
Tipo accesso Ottieni
Denominazione dinamica dei nodi ClientInventory
Host/Complete/Results/{DocID}/Document
Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/{DocID}/Document

Il valore del nodo Document è un documento basato su XML contenente una raccolta di risultati dell'impostazione della richiesta di configurazione specificata da [DocId].

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato chr (stringa)
Tipo accesso Ottieni

Host/Inventario

Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory

Il nodo interno Inventario indica che si tratta di una richiesta di inventario. I valori di impostazione da recuperare vengono specificati in un documento XML tramite il nodo foglia Documento.

Il flusso da server a client della richiesta di inventario è uguale alla richiesta Completa .

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato node
Tipo accesso Add, Delete, Get

Host/Inventario/Documenti

Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents

Il nodo Documenti indica che la richiesta di inventario è sotto forma di documento, ovvero una raccolta di impostazioni usate per recuperare i relativi valori.

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato node
Tipo accesso Add, Delete, Get
Host/Inventory/Documents/{DocID}
Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/{DocID}

Identifica in modo univoco il documento di inventario. Nessun altro documento può avere questo ID. L'ID deve essere un GUID.

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato node
Tipo accesso Add, Delete, Get
Denominazione dinamica dei nodi ServerGeneratedUniqueIdentifier
Valori consentiti Espressione regolare: [0-9A-Fa-f]{8}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{12}
Host/Inventory/Documents/{DocID}/Document
Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/{DocID}/Document

Il valore del nodo Document è un documento basato su XML contenente una raccolta di impostazioni che verranno usate per recuperarne i valori. Lo stack di configurazione dichiarato verifica la sintassi del documento. Lo stack contrassegna il documento per l'elaborazione asincrona da parte del client. Lo stack restituisce quindi il controllo al servizio OMA-DM. Lo stack, a sua volta, elabora in modo asincrono la richiesta. Di seguito è riportato un esempio di configurazione dello stato desiderato specificata che usa l'URI di configurazione dichiarato ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/27FEA311-68. B9-4320-9. FC4-296. F6FDFAFE2/Documento.

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato chr (stringa)
Tipo accesso Aggiungere, eliminare, ottenere, sostituire

Host/Inventario/Risultati

Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Results

Il nodo Risultati indica che fa parte del percorso URI che restituirà un documento XML contenente i risultati della richiesta di inventario.

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato node
Tipo accesso Ottieni
Host/Inventory/Results/{DocID}
Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Results/{DocID}

Identifica in modo univoco il documento di inventario. Nessun altro documento può avere questo ID. L'ID deve essere un GUID.

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato node
Tipo accesso Ottieni
Denominazione dinamica dei nodi ClientInventory
Host/Inventory/Results/{DocID}/Document
Ambito Edizioni Sistema operativo applicabile
✅ dispositivo
❌ utente		 ✅ Pro
✅ Enterprise
✅ Education
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Results/{DocID}/Document

Il valore del nodo Document è un documento basato su XML contenente una raccolta di risultati dell'impostazione della richiesta di inventario specificata da [DocId].

Proprietà del framework di descrizione:

Nome della proprietà Valore proprietà
Formato chr (stringa)
Tipo accesso Ottieni

DeclaredConfiguration OMA URI

Una richiesta WinDC viene inviata usando un URI OMA simile a ./Device/Vendor/MSFT/DeclaredConfiguration/Host/[Complete|Inventory]/Documents/{DocID}/Document.

  • L'URI è preceduto da un ambito di destinazione (User o Device).
  • {DocID} è un identificatore univoco per lo stato desiderato dello scenario di configurazione. Ogni documento deve avere un ID, che deve essere un GUID.
  • La richiesta può essere un inventario o una richiesta completa .

L'URI seguente è un esempio di richiesta Completa : ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document

Documento WinDC

<DeclaredConfiguration
    schema="1.0"
    context="Device"
    id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2"
    checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999"
    osdefinedscenario="MSFTExtensibilityMIProviderConfig">
    ... {Configuration Data} ...
</DeclaredConfiguration>

Il <DeclaredConfiguration> tag XML specifica i dettagli del documento WinDC da elaborare. Il documento può far parte di una richiesta di configurazione o di una richiesta di inventario. Il provider di servizi di configurazione DeclaredConfiguration ha due URI per consentire la specifica di una configurazione o di una richiesta di inventario .

Questo tag ha gli attributi seguenti:

Attributo Descrizione
schema Versione dello schema del file xml. Attualmente 1.0.
context Indica se il documento è destinato al dispositivo o all'utente.
id Identificatore univoco del documento impostato dal server. Questo valore deve essere un GUID.
checksum Questo valore è la versione del documento fornita dal server.
osdefinedscenario Scenario denominato che il client deve configurare con i dati di configurazione specificati.

Il provider di servizi di configurazione DeclaredConfiguration convalida in modo sincrono il batch di impostazioni descritto dall'elemento <DeclaredConfiguration> , che rappresenta il documento WinDC. Verifica la sintassi corretta in base allo schema XML WinDC. Se si verifica un errore di sintassi, il provider di servizi di configurazione restituisce immediatamente un errore nel server come parte della sessione OMA-DM corrente. Se il controllo della sintassi viene superato, la richiesta viene passata a un servizio Windows. Il servizio Windows tenta in modo asincrono la configurazione dello stato desiderata dello scenario specificato. Questo processo consente al server di eseguire altre operazioni, quindi la bassa latenza del protocollo WinDC. Il servizio client Windows, l'agente di orchestrazione, è responsabile della configurazione del dispositivo in base allo stato desiderato fornito dal server. Il servizio mantiene anche questo stato per tutta la durata, fino a quando il server non lo rimuove o lo modifica.

L'elaborazione effettiva della richiesta ruota intorno al osdefinedscenario tag e ai dati di configurazione specificati all'interno del documento. Per altre informazioni, vedi:

Avviso generico WinDC

In ogni risposta client alla richiesta del server, il client crea un avviso WinDC. Questo avviso riepiloga lo stato di ogni documento elaborato dal servizio Windows. Il codice XML seguente è un avviso di esempio:

<Alert>
  <CmdID>1</CmdID>
  <Data>1224</Data>
  <Item>
    <Meta>
      <Type xmlns="syncml:metinf">com.microsoft.mdm.declaredconfigurationdocuments</Type>
    </Meta>
    <Data>
      <DeclaredConfigurations schema="1.0">
        <DeclaredConfiguration context="Device"
                               id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2"
                               checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999"
                               result_checksum="EE4F1636201B0D39F71654427E420E625B9459EED17ACCEEE1AC9B358F4283FD"
                               state="60" />
      </DeclaredConfigurations>
    </Data>
  </Item>
</Alert>

In questo esempio è presente un documento WinDC elencato nel riepilogo degli avvisi. Il riepilogo degli avvisi elenca ogni documento elaborato dallo stack client, ovvero una richiesta di configurazione o di inventario. Descrive il contesto del documento che specifica l'ambito dell'applicazione del documento. Il valore di contesto deve essere Device.

L'attributo di stato ha un valore pari a 60, che indica che il documento è stato elaborato correttamente.

Stati WinDC

La classe seguente definisce i valori di stato:

enum class DCCSPURIState :unsigned long
{
    NotDefined = 0, // transient
    ConfigRequest = 1, // transient
    ConfigInprogress = 2, // transient
    ConfigInProgressAsyncPending = 3, // transient: Async operation is performed but pending results
    DeleteRequest = 10,  // transient
    DeleteInprogress = 11,  // transient

    GetRequest = 20,  // transient
    GetInprogress = 21,  // transient

    ConstructURIStorageSuccess = 40, // transient

    ConfigCompletedSuccess = 60, // permanent
    ConfigCompletedError = 61, // permanent
    ConfigInfraError = 62, // permanent
    ConfigCompletedSuccessNoRefresh = 63, // permanent

    DeleteCompletedSuccess = 70, // permanent
    DeleteCompletedError = 71, // permanent
    DeleteInfraError = 72, // permanent

    GetCompletedSuccess = 80, // permanent
    GetCompletedError = 81, // permanent
    GetInfraError = 82 // permanent
};

Esempi di SyncML

Abbandonare un documento WinDC

L'abbandono di una risorsa si verifica quando determinate risorse non sono più destinate a un utente o a un gruppo. Invece di eliminare la risorsa nel dispositivo, il server può scegliere di abbandonare il documento WinDC. Una risorsa abbandonata rimane nel dispositivo, ma smette di aggiornare il documento WinDC che gestisce il controllo della deriva. Anche la proprietà della risorsa viene trasferita in MDM, il che significa che la stessa risorsa può essere modificata nuovamente tramite il canale MDM legacy.

Questo esempio illustra come abbandonare un documento WinDC impostando la proprietà Abandoned su 1.

<SyncML xmlns="SYNCML:SYNCML1.1">
  <SyncBody>
    <Replace>
    <CmdID>2</CmdID>
    <Item>
        <Meta>
            <Format>int</Format>
            <Type>text/plain</Type>
        </Meta>
        <Target>
            <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Properties/Abandoned</LocURI>
        </Target>
        <Data>1</Data>
    </Item>
    </Replace>
    <Final/>
  </SyncBody>
</SyncML>

Annullare ilbandon di un documento WinDC

L'annullamento dell'abbandono del documento comporta l'applicazione immediata del documento, il trasferimento della proprietà della risorsa alla gestione WinDC e il blocco della gestione dei canali MDM legacy.

Questo esempio illustra come annullare ilbandon di un documento WinDC impostando la proprietà Abandoned su 0.

<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
  <SyncBody>
    <Replace>
      <CmdID>10</CmdID>
      <Item>
        <Target>
          <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Properties/Abandoned</LocURI>
        </Target>
        <Meta>
          <Format xmlns="syncml:metinf">int</Format>
        </Meta>
        <Data>0</Data>
      </Item>
    </Replace>
    <Final />
  </SyncBody>
</SyncML>

Eliminare un documento WinDC

L'eliminazione SyncML del documento rimuove solo il documento, ma tutte le impostazioni vengono mantenute nel dispositivo. In questo esempio viene illustrato come eliminare un documento.

<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
    <Delete>
        <CmdID>2</CmdID>
        <Item>
        <Target>
            <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
        </Target>
        </Item>
    </Delete>
    <Final/>
    </SyncBody>
</SyncML>

Riferimento del provider di servizi di configurazione