Verwenden der Windows-Einstellungs-API in Microsoft Graph

Artikel
06/10/2024

Die Windows-Einstellungs-API ermöglicht es Benutzern und autorisierten Dritten, die im Namen von Benutzern handeln, ihre in der Microsoft-Cloud gespeicherten Windows-Betriebssystemeinstellungsdaten abzurufen. Die Windows-Einstellungsdaten sind in der Microsoft-Cloud nur verfügbar, wenn Benutzer das Feature aktivieren. Der Für jeden Benutzer verfügbare Datenbereich hängt von der Auswahl der Sicherungseinstellungen ab. Die Standardwerte für alle Einstellungen bleiben lokal und werden nicht in die Cloud übertragen. Die Windows-Einstellungs-API gibt nur Einstellungsdaten weiter, die der Benutzer in die Cloud hochlädt.

Windows-Einstellungen

Die WindowsSetting-Ressource stellt verschiedene Windows-Betriebssystemeinstellungen dar, die für einen bestimmten Benutzer in der Cloud gespeichert werden. Windows-Einstellungen haben zwei Typen: roaming und backup. Die settingType-Eigenschaft eines windowsSetting-Objekts gibt den Typ der Einstellung an.

Einstellungstyp	Beschreibung
Roaming	Die Windows-Einstellung ist dem Konto eines Benutzers zugeordnet. Die Einstellung ist auf allen Geräten konsistent, und alle Änderungen am Einstellungswert werden synchronisiert oder auf alle Windows-Geräte angewendet, die dem Benutzer gehören.
Sicherungskopie	Die Windows-Einstellung wird nicht geräteübergreifend übertragen oder synchronisiert. Diese Einstellungsart wird in Sicherungs- und Wiederherstellungsszenarien für Geräte verwendet.

Ein windowsSetting-Objekt vom Typ backup kann über eine windowsDeviceId-Eigenschaft verfügen, die die Einstellung mit einem bestimmten Gerät verknüpft.

Die API für Windows-Einstellungen auflisten gibt eine Auflistung von windowsSetting-Objekten und deren Eigenschaften zurück. Sie können die Ergebnisse nach den Eigenschaften windowsDeviceId und settingType filtern.

Mit der get windowsSetting-API können Sie die ID eines windowsSetting-Objekts in der URL übergeben, um ein bestimmtes Windows-Einstellungsobjekt zu lesen.

Die folgende JSON-Darstellung zeigt ein Beispiel für einen windowsSetting-Ressourcentyp . Die Instances-Auflistung stellt windowsSettingInstance-Objekte dar.

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

Warnung

Die Struktur der ID eines windowsSetting-Objekts ist nicht garantiert, und der Aufrufer sollte keine Abhängigkeit davon übernehmen. Die ID sollte als undurchsichtige Zeichenfolge behandelt werden.

Windows-Einstellungsinstanzen

Eine windowsSettingInstance stellt eine Einstellungsinstanz des Windows-Betriebssystems dar, die für einen bestimmten Benutzer in der Cloud gespeichert ist. Eine windowsSettingInstance gehört zu einem windowsSetting.

Die folgende JSON-Darstellung zeigt ein Beispiel für einen windowsSettingInstance-Ressourcentyp .

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

Die API Windows-Einstellungsinstanzen auflisten gibt eine Auflistung von windowsSettingInstance-Objekten und deren Eigenschaften zurück. Die API erfordert die ID eines windowsSetting in der URL, um die Einstellungsinstanzen zu lesen.

Mit der API zum Abrufen der Windows-Einstellungsinstanz können Sie die ID eines windowsSetting- und windowsSettingInstance-Objekts in der URL übergeben, um ein bestimmtes Windows-Einstellungsinstanzobjekt zu lesen.

Die payload-Eigenschaft einer windowsSettingInstance enthält den tatsächlichen Einstellungswert. Die Nutzlast ist eine Zeichenfolge im Base64-codierten Format. Die payloadType-Eigenschaft des windowsSetting-Objekts gibt den Typ des Einstellungswerts an. Bei der Decodierung handelt es sich bei der Nutzlast um ein JSON-Objekt, das sich von Einstellung zu Einstellung unterscheidet und für den payloadType spezifisch ist.

payloadType-Eigenschaft

Der payloadType definiert die Struktur einer windowsSettingInstance-Nutzlast . Windows enthält eine Reihe von Nutzlasttypen, die unterschiedliche Einstellungsstrukturen darstellen, die von verschiedenen Betriebssystemumgebungen verwendet werden. Mit der Weiterentwicklung von Windows werden mehr Nutzlasttypen erstellt und in die Cloud integriert. Das Abfragen der API und das Untersuchen der verfügbaren Einstellungen ist die beste Möglichkeit, sich über die verschiedenen Nutzlasttypen zu informieren. Die Benutzer und Administratoren haben die Kontrolle darüber, welche Einstellungen in die Cloud hochgeladen werden, und die meisten Komponenten laden keine Standardeinstellungen hoch, die der Benutzer nicht angepasst hat.

Das folgende Beispiel zeigt ein windowsSettingsInstance-Objekt , das von der API zurückgegeben wird.

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

In diesem Beispiel stellt payloadTypewindows.data.fileexplorerclassic.advancedsettings einige der Einstellungen dar, die der Datei-Explorer in der Cloud sichert. Die Base64-Nutzlast kann in eine UTF-8-Zeichenfolge decodiert werden, um die JSON-Darstellung dieses Objekts anzuzeigen.

Das folgende Beispiel zeigt die decodierte Nutzlast.

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

Eigenschaften im -Objekt sind in der Regel eine Teilmenge der Eigenschaften, die in der Benutzeroberfläche der Komponente verfügbar sind, da Komponentenbesitzer entscheiden, welche Einstellungen beim Hochladen in die Cloud den größten Wert bieten.

Nutzlasttypen

Die in diesem Abschnitt beschriebenen Nutzlasttypen haben eine besondere Rolle beim Sichern von Windows-Einstellungen.

windows.data.platform.backuprestore.deviceprofile

Der Nutzlasttyp windows.data.platform.backuprestore.deviceprofile ist keine Einstellung, die der Benutzer angewendet hat. Dieser Typ zeichnet Informationen zu Geräten auf, die die Sicherungsfunktionen für Einstellungen aktiviert haben. Die folgenden Eigenschaften für dieses Objekt sind nützlich, um die restlichen Einstellungen zu verstehen:

deviceDisplayName : Der Name des Computers. Diese Einstellung finden Sie in den Windows-Systemeinstellungen unter "Starteinstellungen>>System".
profileId : Ein Bezeichner, der verwendet wird, um windowsSetting-Elemente mit dem Gerät zu verknüpfen, das sie hochgeladen hat. Diese Eigenschaft entspricht windowsSetting.windowsDeviceId und kann als Filter verwendet werden, um Einstellungen für ein bestimmtes Gerät aus der API für Windows-Einstellungen auflisten abzurufen.

Das folgende Beispiel zeigt diesen Ressourcentyp.

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

Das folgende Beispiel zeigt die decodierte Nutzlast.

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

Die Einstellungen für den BackupUnitStore-Nutzlasttyp sind eindeutig, da der tatsächliche Einstellungswert ein Blob in der data-Eigenschaft ist. Dies liegt daran, dass backupUnitStore-Einstellungen direkt aus der Windows-Registrierung, auf Datenträgerdateien oder anderen ruhenden Speicherorten in Windows gesammelt werden. Diese Einstellungen wurden nicht so konzipiert, dass sie mit anderen Umgebungen als den Komponenten interoperabel sind, die sie erstellt haben. Sie werden in dieser API verfügbar gemacht, um eine umfassende Abdeckung aller Windows-Einstellungen zu erhalten, die in der Cloud gespeichert sind.

Freigeben über