在 Microsoft Graph 中使用 Windows 设置 API

项目
06/10/2024

Windows 设置 API 使用户和授权的第三方能够代表用户检索存储在Microsoft云中的 Windows 操作系统设置数据。仅当用户激活该功能时，Windows 设置数据才会在Microsoft云中可用。每个用户可用的数据范围取决于其备份设置选择。任何设置的默认值都保留在本地，不会传输到云。 Windows 设置 API 仅共享用户上传到云的设置数据。

Windows 设置

windowsSetting 资源表示为给定用户存储在云中的各种 Windows 操作系统设置。 Windows 设置有两种类型： roaming 和 backup。 windowsSetting 对象的 settingType 属性指示设置的类型。

设置类型	说明
漫游	Windows 设置与用户帐户相关联。该设置在所有设备之间是一致的，对设置值的任何更改都会同步或应用于用户拥有的所有 Windows 设备。
备份	Windows 设置不会跨设备漫游或同步。这种类型的设置用于设备备份和还原方案。

类型的 backupwindowsSetting 对象可能具有将设置链接到特定设备的 windowsDeviceId 属性。

列出 Windows 设置 API 返回 windowsSetting 对象及其属性的集合。可以按 windowsDeviceId 和 settingType 属性筛选结果。

通过获取 windowsSetting API，可以在 URL 中传递 windowsSetting 的 ID，以读取特定的 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 对象的 ID 结构，调用方不应对其进行任何依赖。 ID 应被视为不透明的字符串。

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

列出 Windows 设置实例 API 返回 windowsSettingInstance 对象及其属性的集合。 API 需要 URL 中 windowsSetting 的 ID 才能读取设置实例。

通过获取 Windows 设置实例 API，可以在 URL 中传递 windowsSetting 和 windowsSettingInstance 的 ID，以读取特定的 Windows 设置实例对象。

windowsSettingInstance 的有效负载属性包含实际设置值。 有效负载是 Base64 编码格式的字符串。 windowsSetting 对象的 payloadType 属性指示设置值的类型。解码时 的有效负载 是一个 JSON 对象，它不同于设置为设置，特定于 payloadType。

payloadType 属性

payloadType 定义 windowsSettingInstance 有效负载的结构。 Windows 包含许多有效负载类型，这些类型表示不同操作系统体验使用的不同设置结构。随着 Windows 的发展，会创建更多有效负载类型并将其载入到云中。查询 API 并探索可用的设置是了解各种有效负载类型的最佳方式。用户和管理员控制哪些设置上传到云，大多数组件不会上传用户未自定义的默认设置。

以下示例显示 API 返回的 windowsSettingsInstance 对象。

{
    "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 ，可用作筛选器，以便从列出 Windows 设置 API 获取特定设备的设置。

以下示例演示此资源类型。

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