Использование API параметров Windows в Microsoft Graph

Статья
04/29/2024

API параметров Windows позволяет пользователям и авторизованным третьим лицам, действующим от имени пользователей, получать данные параметров операционной системы Windows, хранящиеся в облаке Майкрософт. Данные параметров Windows доступны в облаке Майкрософт только тогда, когда пользователи активируют эту функцию. Область данных, доступных для каждого пользователя, зависит от выбранных параметров резервного копирования. Значения по умолчанию для любых параметров остаются локальными и не передаются в облако. API параметров Windows предоставляет доступ только к данным параметров, которые пользователь отправляет в облако.

Параметры Windows

Ресурс windowsSetting представляет различные параметры операционной системы Windows, которые хранятся в облаке для конкретного пользователя. Параметры Windows бывают двух типов: roaming и backup. Свойство settingType объекта windowsSetting указывает тип параметра.

Тип параметра	Описание
роуминг	Параметр Windows связан с учетной записью пользователя. Параметр согласован на всех устройствах, и все изменения значения параметра синхронизируются или применяются ко всем устройствам Windows, принадлежащим пользователю.
резервная копия	Параметр Windows не перемещается или не синхронизируется между устройствами. Этот тип параметров используется в сценариях резервного копирования и восстановления устройств.

Объект windowsSetting типа backup может иметь свойство windowsDeviceId , которое связывает параметр с определенным устройством.

API перечисления параметров Windows возвращает коллекцию объектов windowsSetting и их свойства. Результаты можно фильтровать по свойствам windowsDeviceId и settingType .

API get windowsSetting позволяет передать идентификатор windowsSetting в URL-адресе для чтения определенного объекта параметров Windows.

В следующем представлении JSON показан пример типа ресурса windowsSetting . Коллекция экземпляров представляет объекты 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"
            }
        ]
}

Предупреждение

Структура идентификатора объекта windowsSetting не гарантируется, и вызывающий объект не должен зависеть от него. Идентификатор должен рассматриваться как непрозрачная строка.

Экземпляры параметров Windows

WindowsSettingInstance представляет экземпляр параметра из операционной системы Windows, который хранится в облаке для данного пользователя. Объект windowsSettingInstance принадлежит windowsSetting.

В следующем представлении JSON показан пример типа ресурса 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"
}

API перечисления экземпляров параметров Windows возвращает коллекцию объектов windowsSettingInstance и их свойства. Api требует идентификатор windowsSetting в URL-адресе для чтения экземпляров параметров.

API получения экземпляра параметра Windows позволяет передать идентификатор windowsSetting и windowsSettingInstance в URL-адресе для чтения определенного объекта экземпляра параметра Windows.

Свойство полезных данныхобъекта windowsSettingInstance содержит фактическое значение параметра. Полезные данные — это строка в формате Base64. Свойство payloadType объекта windowsSetting указывает тип значения параметра. Полезные данные при декодировании — это объект JSON, который отличается от параметра к параметру и связан с полезным типом.

свойство payloadType

PayloadType определяет структуру полезных данных windowsSettingInstance. Windows включает ряд типов полезных данных, которые представляют различные структуры параметров, используемые различными операционными системами. По мере развития Windows создаются и подключены к облаку дополнительные типы полезных данных. Запрос API и изучение доступных параметров — лучший способ узнать о различных типах полезных данных. Пользователи и администраторы имеют контроль над параметрами, которые передаются в облако, а большинство компонентов не передают параметры по умолчанию, которые пользователь не настроил.

В следующем примере показан объект windowsSettingsInstance, возвращенный 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"
        }
    ]
}

В этом примере значение payloadTypewindows.data.fileexplorerclassic.advancedsettings представляет некоторые параметры, которые проводник резервирует в облаке. Полезные данные Base64 можно декодировать в строку UTF-8, чтобы увидеть представление этого объекта в формате JSON.

В следующем примере показаны полезные данные, декодированные.

{
    "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
}

Свойства в объекте обычно являются подмножеством свойств, доступных в пользовательском интерфейсе компонента, так как владельцы компонентов определяют, какие параметры предоставляют наибольшее значение при отправке в облако.

Типы полезных данных

Типы полезных данных, описанные в этом разделе, имеют особую роль в процессе резервного копирования параметров Windows.

windows.data.platform.backuprestore.deviceprofile

Тип полезных данных windows.data.platform.backuprestore.deviceprofile не является параметром, примененным пользователем; этот тип записывает сведения об устройствах, которые выбрали функции резервного копирования параметров. Следующие свойства этого объекта полезны для понимания остальных параметров:

deviceDisplayName — имя компьютера. Этот параметр находится в системных параметрах Windows в разделе "Пуск>системы параметров>".
profileId — идентификатор, используемый для связывания элементов windowsSetting с устройством, которое их отправило. Это свойство соответствует windowsSetting.windowsDeviceId и может использоваться в качестве фильтра для получения параметров для определенного устройства из API перечисления параметров Windows .

В следующем примере показан этот тип ресурса.

{
    "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"
        }
    ]
}

В следующем примере показаны полезные данные, декодированные.

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

Параметры типа полезных данных backupUnitStore уникальны тем, что фактическое значение параметров — это большой двоичный объект в свойстве данных. Это связано с тем, что параметры backupUnitStore собираются непосредственно из реестра Windows, в файлах на диске или в других неактивных расположениях в Windows. Эти параметры не были разработаны для взаимодействия с интерфейсами, кроме компонентов, которые их создали. Они предоставляются в этом API для полного охвата всех параметров Windows, хранящихся в облаке.

Поделиться через