Partager via

Fournisseur de services de configuration DeclaredConfiguration

  • Article

Logo de Windows Insider.

Important

Ce csp contient certains paramètres en cours de développement et qui s’appliquent uniquement aux builds Windows Insider Preview. Ces paramètres sont susceptibles d’être modifiés et peuvent avoir des dépendances vis-à-vis d’autres fonctionnalités ou services en préversion.

Le modèle MDM principal est celui où le serveur MDM est seul responsable de l’orchestration et de la maintenance continue de l’état de l’appareil pour les scénarios de configuration. Ce comportement entraîne un trafic réseau intensif et une latence réseau élevée en raison du modèle de configuration synchrone basé sur la norme OMA-DM Syncml. Elle est également sujette aux erreurs, étant donné que le serveur a besoin d’une connaissance approfondie du client.

Le modèle de gestion des appareils windows de configuration déclarée (WinDC) nécessite que le serveur fournisse toutes les valeurs de paramètre à l’appareil pour la configuration du scénario. Le serveur les envoie de façon asynchrone par lots via le fournisseur de services de configuration DeclaredConfiguration.

  • Pendant la session OMA-DM initiée par le client, le serveur WinDC envoie une configuration ou un document WinDC d’inventaire au client via l’URI CSP DeclaredConfiguration. Si l’appareil vérifie que la syntaxe du document est correcte, la pile cliente envoie la requête à son orchestrateur pour traiter la requête de manière asynchrone. La pile cliente se ferme et retourne le contrôle au service WinDC. Ce comportement permet à l’appareil de traiter la requête de manière asynchrone.

  • Sur le client, s’il y a des demandes en cours de traitement ou terminées, il envoie une alerte générique au serveur. Cette alerte résume les status, l’état et la progression de chaque document. Chaque requête HTTPS cliente adressée au serveur WinDC OMA-DM inclut ce résumé.

  • Le serveur WinDC utilise l’alerte générique pour déterminer quelles demandes sont effectuées avec succès ou avec des erreurs. Le serveur peut ensuite récupérer de façon synchrone les résultats du processus de document WinDC via l’URI CSP DeclaredConfiguration.

La liste suivante présente les nœuds du fournisseur de services de configuration DeclaredConfiguration :

Host

Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host

Le nœud interne de l’hôte indique que la cible de la demande de configuration ou de la demande d’inventaire est le système d’exploitation hôte. Ce nœud est destiné à l’étendue au cas où des enclaves sont ciblées pour la configuration.

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format node
Type d’accès Ajouter, Supprimer, Obtenir

Hôte/Terminé

Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete

Ce nœud interne indique que la configuration a des valeurs de paramètres discrètes et qu’elle est autonome avec des paires de paramètres et de valeurs complètes qui ne contiennent pas d’espaces réservés qui doivent être résolus ultérieurement avec des données supplémentaires. La demande est prête à être traitée telle qu’elle est.

Le flux serveur-client de la requête Complete est identique à une demande d’inventaire .

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format node
Type d’accès Ajouter, Supprimer, Obtenir

Hôte/Complet/Documents

Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents

Le nœud Documents indique que la configuration se présente sous la forme d’un document, qui est une collection de paramètres utilisés pour configurer un scénario par la pile Configuration déclarée.

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format node
Type d’accès Ajouter, Supprimer, Obtenir
Host/Complete/Documents/{DocID}
Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}

Identifie de manière unique le document de configuration. Aucun autre document ne peut avoir cet ID. L’ID doit être un GUID.

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format node
Type d’accès Ajouter, Supprimer, Obtenir
Nommage de nœud dynamique ServerGeneratedUniqueIdentifier
Valeurs autorisées Expression régulière: [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}
Hôte/Complete/Documents/{DocID}/Document
Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/Document

La valeur du nœud Document est un document XML contenant une collection de paramètres et de valeurs pour configurer le scénario spécifié. La pile Declared Configuration vérifie la syntaxe du document, la pile marque le document à traiter de façon asynchrone par le client. La pile retourne ensuite le contrôle au service OMA-DM. La pile, à son tour, traite la requête de manière asynchrone. Voici un exemple de configuration d’état souhaité spécifiée utilisant l’URI de configuration déclaré ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68. B9-4320-9. FC4-296. F6FDFAFE2/Document.

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format chr (chaîne)
Type d’accès Ajouter, Supprimer, Obtenir, Remplacer
Host/Complete/Documents/{DocID}/Properties
Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/Properties

Le nœud Propriétés encapsule la liste des propriétés qui s’appliquent au document spécifié référencé par [DocID].

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format node
Type d’accès Ajouter, Supprimer, Obtenir
Host/Complete/Documents/{DocID}/Properties/Abandoned
Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/Properties/Abandoned

Le nœud Abandonné permet au serveur OMA-DM d’indiquer que le document n’est plus géré.

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format int
Type d’accès Ajouter, Supprimer, Obtenir, Remplacer
Valeur par défaut 0

Valeurs autorisées:

Valeur Description
0 (par défaut) Le document n’est plus géré.
1 Le document est géré.

Hôte/Terminé/Résultats

Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results

Le nœud Résultats indique qu’il fait partie du chemin d’URI qui retourne un document XML contenant les résultats de la demande de configuration.

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format node
Type d’accès Télécharger
Hôte/Complete/Results/{DocID}
Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/{DocID}

Identifie de manière unique le document de configuration dans lequel les résultats de la demande de configuration seront retournés.

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format node
Type d’accès Télécharger
Nommage de nœud dynamique ClientInventory
Hôte/Complete/Results/{DocID}/Document
Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/{DocID}/Document

La valeur du nœud Document est un document XML contenant une collection de résultats de définition de la demande de configuration spécifiée par [DocId].

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format chr (chaîne)
Type d’accès Télécharger

Hôte/Inventaire

Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory

Le nœud interne Inventaire indique qu’il s’agit d’une demande d’inventaire. Les valeurs de paramètre à récupérer sont spécifiées dans un document XML via le nœud feuille de document.

Le flux serveur-client de la demande d’inventaire est identique à la requête Complete .

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format node
Type d’accès Ajouter, Supprimer, Obtenir

Hôte/Inventaire/Documents

Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents

Le nœud Documents indique que la demande d’inventaire se présente sous la forme d’un document, qui est une collection de paramètres utilisés pour récupérer leurs valeurs.

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format node
Type d’accès Ajouter, Supprimer, Obtenir
Hôte/Inventaire/Documents/{DocID}
Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/{DocID}

Identifie de manière unique le document d’inventaire. Aucun autre document ne peut avoir cet ID. L’ID doit être un GUID.

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format node
Type d’accès Ajouter, Supprimer, Obtenir
Nommage de nœud dynamique ServerGeneratedUniqueIdentifier
Valeurs autorisées Expression régulière: [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}
Hôte/Inventaire/Documents/{DocID}/Document
Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/{DocID}/Document

La valeur du nœud Document est un document XML contenant une collection de paramètres qui seront utilisés pour récupérer leurs valeurs. La pile Declared Configuration vérifie la syntaxe du document, la pile marque le document à traiter de façon asynchrone par le client. La pile retourne ensuite le contrôle au service OMA-DM. La pile, à son tour, traite la requête de manière asynchrone. Voici un exemple de configuration d’état souhaité spécifiée utilisant l’URI de configuration déclaré ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/27FEA311-68. B9-4320-9. FC4-296. F6FDFAFE2/Document.

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format chr (chaîne)
Type d’accès Ajouter, Supprimer, Obtenir, Remplacer

Hôte/Inventaire/Résultats

Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Results

Le nœud Résultats indique qu’il fait partie du chemin d’URI qui retourne un document XML contenant les résultats de la demande d’inventaire.

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format node
Type d’accès Télécharger
Hôte/Inventaire/Résultats/{DocID}
Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Results/{DocID}

Identifie de manière unique le document d’inventaire. Aucun autre document ne peut avoir cet ID. L’ID doit être un GUID.

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format node
Type d’accès Télécharger
Nommage de nœud dynamique ClientInventory
Hôte/Inventaire/Résultats/{DocID}/Document
Étendue Éditions Système d’exploitation applicable
✅ Appareil
❌Utilisateur		 ✅Pro
✅ Enterprise
✅ Éducation
✅Windows SE
✅ IoT Enterprise / IoT Enterprise LTSC		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Results/{DocID}/Document

La valeur du nœud Document est un document XML contenant une collection de résultats de définition de la demande d’inventaire spécifiée par [DocId].

Propriétés de l’infrastructure de description :

Nom de la propriété Valeur de la propriété
Format chr (chaîne)
Type d’accès Télécharger

DeclaredConfiguration OMA URI

Une requête WinDC est envoyée à l’aide d’un URI OMA similaire à ./Device/Vendor/MSFT/DeclaredConfiguration/Host/[Complete|Inventory]/Documents/{DocID}/Document.

  • L’URI est précédé d’une étendue ciblée (User ou Device).
  • {DocID} est un identificateur unique pour l’état souhaité du scénario de configuration. Chaque document doit avoir un ID, qui doit être un GUID.
  • La demande peut être une demande d’inventaire ou complète .

L’URI suivant est un exemple de demande Complète : ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document

Document WinDC

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

La <DeclaredConfiguration> balise XML spécifie les détails du document WinDC à traiter. Le document peut faire partie d’une demande de configuration ou d’inventaire. Le fournisseur de services de configuration DeclaredConfiguration a deux URI pour permettre la spécification d’une configuration ou d’une demande d’inventaire .

Cette balise a les attributs suivants :

Attribut Description
schema Version de schéma du xml. Actuellement.1.0
context Indique si le document cible l’appareil ou l’utilisateur.
id Identificateur unique du document défini par le serveur. Cette valeur doit être un GUID.
checksum Cette valeur correspond à la version fournie par le serveur du document.
osdefinedscenario Scénario nommé que le client doit configurer avec les données de configuration données.

Le csp DeclaredConfiguration valide de façon synchrone le lot de paramètres décrit par l’élément <DeclaredConfiguration> , qui représente le document WinDC. Il vérifie la syntaxe correcte en fonction du schéma XML WinDC. En cas d’erreur de syntaxe, le csp retourne immédiatement une erreur au serveur dans le cadre de la session OMA-DM actuelle. Si la syntaxe case activée passe, la requête est transmise à un service Windows. Le service Windows tente de façon asynchrone la configuration d’état souhaitée du scénario spécifié. Ce processus libère le serveur pour effectuer d’autres tâches, ce qui entraîne la faible latence du protocole WinDC. Le service client Windows, l’orchestrateur, est chargé de piloter la configuration de l’appareil en fonction de l’état de désir fourni par le serveur. Le service conserve également cet état tout au long de sa durée de vie, jusqu’à ce que le serveur le supprime ou le modifie.

Le traitement réel de la demande pivote autour de la osdefinedscenario balise et des données de configuration spécifiées dans le document. Pour plus d’informations, voir :

Alerte générique WinDC

Sur chaque réponse du client à la demande du serveur, le client construit une alerte WinDC. Cette alerte résume l’état de chacun des documents que le service Windows a traités. Le code XML suivant est un exemple d’alerte :

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

Dans cet exemple, un document WinDC est répertorié dans le résumé de l’alerte. Le résumé de l’alerte répertorie tous les documents que la pile cliente traite, qu’il s’agit d’une demande de configuration ou d’inventaire. Il décrit le contexte du document qui spécifie l’étendue de l’application du document. La valeur de contexte doit être Device.

L’attribut state a une valeur de 60, ce qui indique que le document a été traité avec succès.

États WinDC

La classe suivante définit les valeurs d’état :

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

Exemples SyncML

Abandonner un document WinDC

L’abandon d’une ressource se produit lorsque certaines ressources ne sont plus ciblées sur un utilisateur ou un groupe. Au lieu de supprimer la ressource sur l’appareil, le serveur peut choisir d’abandonner le document WinDC. Une ressource abandonnée reste sur l’appareil, mais cesse d’actualiser le document WinDC qui gère le contrôle de dérive. En outre, la propriété de la ressource est transférée à GPM, ce qui signifie que la même ressource peut être modifiée à nouveau via le canal MDM hérité.

Cet exemple montre comment abandonner un document WinDC en définissant la propriété Abandoned sur 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>

Annuler l’affichage d’un document WinDC

L’annulation de l’attribution du document entraîne l’application immédiate du document, en transférant la propriété de la ressource vers la gestion WinDC et en empêchant le canal GPM hérité de gérer à nouveau les canaux.

Cet exemple montre comment annuler l’utilisation d’un document WinDC en définissant la propriété Abandoned sur 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>

Supprimer un document WinDC

La suppression syncML du document supprime uniquement le document, mais tous les paramètres sont conservés sur l’appareil. Cet exemple montre comment supprimer un document.

<?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>

Informations de référence sur les fournisseurs de services de configuration