Utiliser l’API paramètres Windows dans Microsoft Graph

Article
06/10/2024

L’API de paramètre Windows permet aux utilisateurs et aux tiers autorisés agissant au nom des utilisateurs de récupérer leurs données de paramètres de système d’exploitation Windows stockées dans le cloud Microsoft. Les données des paramètres Windows sont disponibles dans le cloud Microsoft uniquement lorsque les utilisateurs activent la fonctionnalité. L’étendue des données disponibles pour chaque utilisateur dépend de ses sélections de paramètres de sauvegarde. Les valeurs par défaut des paramètres restent locales et ne sont pas transférées vers le cloud. L’API paramètres Windows partage uniquement les données de paramètres que l’utilisateur charge dans le cloud.

Paramètres Windows

La ressource windowsSetting représente différents paramètres du système d’exploitation Windows stockés dans le cloud pour un utilisateur donné. Les paramètres Windows sont de deux types : roaming et backup. La propriété settingType d’un objet windowsSetting indique le type du paramètre.

Type de paramètre	Description
itinérance	Le paramètre Windows est associé au compte d’un utilisateur. Le paramètre est cohérent sur tous les appareils et toutes les modifications apportées à la valeur du paramètre sont synchronisées ou appliquées à tous les appareils Windows dont l’utilisateur est propriétaire.
sauvegarde	Le paramètre Windows n’est pas itinérant ni synchronisé entre les appareils. Ce type de paramètre est utilisé dans les scénarios de sauvegarde et de restauration de l’appareil.

Un objet windowsSetting de type backup peut avoir une propriété windowsDeviceId qui lie le paramètre à un appareil spécifique.

L’API Répertorier les paramètres Windows renvoie une collection d’objets windowsSetting et leurs propriétés. Vous pouvez filtrer les résultats par les propriétés windowsDeviceId et settingType .

L’API Get windowsSetting vous permet de passer l’ID d’un windowsSetting dans l’URL pour lire un objet de paramètre Windows spécifique.

La représentation JSON suivante montre un exemple de type de ressource windowsSetting . La collection instances représente des objets windowsSettingInstance .

{
  "@odata.type": "#microsoft.graph.windowsSetting",
  "id": "{67585f9f-ee4b-4dd8-808e-d88375d66ef7}$windows.data.apps.devicemetadata",
  "windowsDeviceId": "67585f9f-ee4b-4dd8-808e-d88375d66ef7",
  "settingType": "backup",
  "payloadType": "windows.data.apps.devicemetadata",
  "instances": [
            {
                "id": "14b50191-10e5-4da5-9099-8c909b8458bd",
                "payload": "VGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUh",
                "lastModifiedDateTime": "2024-10-31T23:30:41Z",
                "createdDateTime": "2024-02-12T19:34:35.223Z",
                "expirationDateTime": "2034-02-09T19:34:33.771Z"
            }
        ]
}

Avertissement

La structure de l’ID d’un objet windowsSetting n’est pas garantie et l’appelant ne doit pas en dépendre. L’ID doit être traité comme une chaîne opaque.

Instances de paramètres Windows

Un windowsSettingInstance représente une instance de paramètre du système d’exploitation Windows qui est stockée dans le cloud pour un utilisateur donné. Un windowsSettingInstance appartient à un windowsSetting.

La représentation JSON suivante montre un exemple de type de ressource windowsSettingInstance .

{
  "@odata.type": "#microsoft.graph.windowsSettingInstance",
  "id": "6984732f-86b0-8e31-dc02-37fce0df6d61",
  "payload": "VGhpcyBpcyBhbm90aGVyIGp1c3QgYW4gZXhhbXBsZSE=",
  "lastModifiedDateTime": "2024-10-31T23:30:41Z",
  "createdDateTime": "2024-02-12T19:34:35.223Z",
  "expirationDateTime": "2034-02-09T19:34:33.771Z"
}

L’API List Windows setting instances renvoie une collection d’objets windowsSettingInstance et leurs propriétés. L’API nécessite l’ID d’un windowsSetting dans l’URL pour lire les instances de paramètre.

L’API Obtenir l’instance de paramètre Windows vous permet de passer l’ID d’un windowsSetting et windowsSettingInstance dans l’URL pour lire un objet d’instance de paramètre Windows spécifique.

La propriété payload d’un windowsSettingInstance contient la valeur de paramètre réelle. La charge utile est une chaîne au format encodé en Base64. La propriété payloadType de l’objet windowsSetting indique le type de la valeur de paramètre. La charge utile lorsqu’elle est décodée est un objet JSON, qui diffère de la définition et est spécifique à payloadType.

payloadType, propriété

PayloadType définit la structure d’une charge utile windowsSettingInstance. Windows inclut un certain nombre de types de charge utile qui représentent des structures de paramètres distinctes utilisées par différentes expériences de système d’exploitation. À mesure que Windows évolue, davantage de types de charge utile sont créés et intégrés au cloud. L’interrogation de l’API et l’exploration des paramètres disponibles sont la meilleure façon d’en savoir plus sur les différents types de charge utile. Les utilisateurs et les administrateurs contrôlent les paramètres qui sont chargés dans le cloud et la plupart des composants ne chargent pas les paramètres par défaut que l’utilisateur n’a pas personnalisés.

L’exemple suivant montre un objet windowsSettingsInstance retourné par l’API.

{
    "id": "default$windows.data.fileexplorerclassic.advancedsettings",
    "settingType": "roaming",
    "payloadType": "windows.data.fileexplorerclassic.advancedsettings",
    "instances": [
        {
            "id": "d9a7f6e2-8c4b-4e3a-bf7c-1e5a9d8c6f4b",
            "payload": "eyJtaWdyYXRlZEZyb21TU0YiOmZhbHNlLCJhbHdheXNTaG93TWVudXMiOmZhbHNlLCJmb2xkZXJDb250ZW50c0luZm9UaXAiOmZhbHNlLCJoaWRlRHJpdmVzV2l0aE5vTWVkaWEiOmZhbHNlLCJuYXZQYW5lRXhwYW5kVG9DdXJyZW50Rm9sZGVyIjpmYWxzZSwibmF2UGFuZVNob3dBbGxGb2xkZXJzIjpmYWxzZSwibmF2UGFuZVNob3dGYXZvcml0ZXMiOmZhbHNlLCJwZXJzaXN0QnJvd3NlcnMiOmZhbHNlLCJzaGFyaW5nV2l6YXJkT24iOmZhbHNlLCJzaG93RHJpdmVMZXR0ZXJzIjpmYWxzZSwic2hvd1ByZXZpZXdIYW5kbGVycyI6ZmFsc2UsInR5cGVBaGVhZCI6ZmFsc2UsInNob3dTdGF0dXNCYXIiOmZhbHNlLCJzaG93TGlicmFyaWVzIjpmYWxzZSwic2hvd0NvbXBDb2xvciI6ZmFsc2V9",
            "lastModifiedDateTime": "2022-06-27T00:53:00Z",
            "createdDateTime": "2024-02-13T19:51:15.8217101Z",
            "expirationDateTime": "2034-02-10T19:51:14.813Z"
        }
    ]
}

Dans cet exemple, payloadTypewindows.data.fileexplorerclassic.advancedsettings représente certains des paramètres que l’Explorateur de fichiers sauvegarde dans le cloud. La charge utile Base64 peut être décodée en chaîne UTF-8 pour voir la représentation JSON de cet objet.

L’exemple suivant montre la charge utile décodée.

{
    "migratedFromSSF": false,
    "alwaysShowMenus": false,
    "folderContentsInfoTip": false,
    "hideDrivesWithNoMedia": false,
    "navPaneExpandToCurrentFolder": false,
    "navPaneShowAllFolders": false,
    "navPaneShowFavorites": false,
    "persistBrowsers": false,
    "sharingWizardOn": false,
    "showDriveLetters": false,
    "showPreviewHandlers": false,
    "typeAhead": false,
    "showStatusBar": false,
    "showLibraries": false,
    "showCompColor": false
}

Les propriétés de l’objet sont généralement un sous-ensemble de celles qui sont disponibles dans l’expérience utilisateur du composant, car les propriétaires de composants décident quels paramètres fournissent le plus de valeur lorsqu’ils sont chargés dans le cloud.

Types de charge utile

Les types de charge utile décrits dans cette section ont un rôle spécial dans le processus de sauvegarde des paramètres Windows.

windows.data.platform.backuprestore.deviceprofile

Le type de charge utile windows.data.platform.backuprestore.deviceprofile n’est pas un paramètre appliqué par l’utilisateur ; ce type enregistre des informations sur les appareils qui ont choisi les fonctionnalités de sauvegarde des paramètres. Les propriétés suivantes sur cet objet sont utiles pour comprendre le reste des paramètres :

deviceDisplayName : nom de l’ordinateur. Ce paramètre se trouve dans les paramètres système Windows à l’adresse « Démarrer> lesystèmede paramètres> ».
profileId : identificateur utilisé pour lier des éléments windowsSetting à l’appareil qui les a chargés. Cette propriété correspond à windowsSetting.windowsDeviceId et peut être utilisée comme filtre pour obtenir les paramètres d’un appareil spécifique à partir de l’API Lister les paramètres Windows .

L’exemple suivant montre ce type de ressource.

{
    "id": "default$windows.data.platform.backuprestore.deviceprofile$deviceprofiles",
    "settingType": "backup",
    "payloadType": "windows.data.platform.backuprestore.deviceprofile",
    "instances": [
        {
            "id": "73b1a0b8-262a-4804-592a-b82a3a2a0c0d",
            "payload": "ewogICAgInByb2ZpbGVJZCI6ICJ7OTViM2EyYzgtNDgyYS00YTA2LTdiM2EtZGEyYTVhNGIyYzBmfSIsCiAgICAiZGV2aWNlRGlzcGxheU5hbWUiOiAiRVhBTVBMRVVTRVJERVNLVE9QIiwKICAgICJjcmVhdGVkQnkiOiAid2luZG93cyIsCiAgICAic291cmNlUHJvZmlsZUlkIjogIiIsCiAgICAiY3JlYXRlZFRpbWUiOiAxNjY0NjgwNTg5LAogICAgIm1vZGlmaWVkVGltZSI6IDE2OTg3OTUwNDAsCiAgICAiaXNBY3RpdmUiOiB0cnVlLAogICAgImxhc3RGdWxsQmFja3VwQ29tcGxldGVkVGltZSI6IDE2OTgzMzIxMzcsCiAgICAib3NWZXJzaW9uIjogIjE4MDQ1LjM3NTAudmJfcmVsZWFzZSIKfQ==",
            "lastModifiedDateTime": "2023-10-31T23:30:40Z",
            "createdDateTime": "2024-02-13T22:49:02.376Z",
            "expirationDateTime": "2034-02-10T22:49:03.365Z"
        }
    ]
}

L’exemple suivant montre la charge utile décodée.

{
    "profileId": "{95b3a2c8-482a-4a06-7b3a-da2a5a4b2c0f}",
    "deviceDisplayName": "EXAMPLEUSERDESKTOP",
    "createdBy": "windows",
    "sourceProfileId": "",
    "createdTime": 1664680589,
    "modifiedTime": 1698795040,
    "isActive": true,
    "lastFullBackupCompletedTime": 1698332137,
    "osVersion": "18045.3750.vb_release"
}

windows.data.platform.settingsbackup.backupunitstore

Les paramètres de type de charge utile backupUnitStore sont uniques, car la valeur réelle des paramètres est un objet blob dans la propriété de données. Cela est dû au fait que les paramètres backupUnitStore sont collectés directement à partir du Registre Windows, sur les fichiers disque ou d’autres emplacements au repos dans Windows. Ces paramètres n’ont pas été conçus pour être interopérables avec d’autres expériences que les composants qui les ont créés. Ils sont exposés dans cette API pour une couverture complète de tous les paramètres Windows stockés dans le cloud.

Partager via