Microsoft Graph で Windows 設定 API を使用する

[アーティクル]
04/30/2024

Windows 設定 API を使用すると、ユーザーに代わって行動するユーザーと承認されたサードパーティが、Microsoft クラウドに格納されている Windows オペレーティングシステム設定データを取得できます。 Windows 設定データは、ユーザーが機能をアクティブ化した場合にのみ、Microsoft クラウドで使用できます。各ユーザーで使用できるデータの範囲は、バックアップ設定の選択によって異なります。設定の既定値はローカルのままであり、クラウドに転送されません。 Windows 設定 API は、ユーザーがクラウドにアップロードする設定データのみを共有します。

Windows の設定

windowsSetting リソースは、特定のユーザーのクラウドに格納されているさまざまな Windows オペレーティングシステム設定を表します。 Windows 設定には、 roaming と backupの 2 種類があります。 windowsSetting オブジェクトの settingType プロパティは、設定の種類を示します。

設定の種類	説明
ローミング	Windows 設定は、ユーザーのアカウントに関連付けられています。設定はすべてのデバイスで一貫性があり、設定値に対する変更は、ユーザーが所有するすべての Windows デバイスに同期または適用されます。
バックアップ	Windows 設定は、デバイス間でローミングまたは同期されません。この種類の設定は、デバイスのバックアップと復元のシナリオで使用されます。

backup型の windowsSetting オブジェクトには、設定を特定のデバイスにリンクする windowsDeviceId プロパティがある場合があります。

List Windows 設定 API は、windowsSetting オブジェクトとそのプロパティのコレクションを返します。 windowsDeviceId プロパティと settingType プロパティで結果をフィルター処理できます。

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

List Windows 設定インスタンス API は、windowsSettingInstance オブジェクトとそのプロパティのコレクションを返します。 API では、設定インスタンスを読み取るには、URL 内の windowsSetting の ID が必要です。

Windows 設定インスタンスの取得 API を使用すると、URL に windowsSetting と windowsSettingInstance の ID を渡して、特定の Windows 設定インスタンスオブジェクトを読み取ることができます。

windowsSettingInstance の payload プロパティには、実際の設定値が含まれています。 ペイロードは、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 - コンピューターの名前。この設定は、「Start>Settings>System」の 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"
        }
    ]
}

次の例は、デコードされたペイロードを示しています。

{
    "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 ペイロードの種類の設定は、実際の設定値がデータプロパティの BLOB であるという点で一意です。これは、 backupUnitStore 設定は、Windows レジストリ、ディスクファイル、またはその他の保存場所から Windows 全体で直接収集されるためです。これらの設定は、それらを作成したコンポーネント以外のエクスペリエンスと相互運用できるように設計されていません。これらは、クラウドに格納されているすべての Windows 設定を包括的にカバーするために、この API で公開されます。

次の方法で共有