Uso de la API de configuración de Windows en Microsoft Graph

Artículo
04/29/2024

La API de configuración de Windows permite a los usuarios y a terceros autorizados que actúan en nombre de los usuarios recuperar los datos de configuración del sistema operativo Windows almacenados en la nube de Microsoft. Los datos de configuración de Windows solo están disponibles en la nube de Microsoft cuando los usuarios activan la característica. El ámbito de los datos disponibles para cada usuario depende de sus selecciones de configuración de copia de seguridad. Los valores predeterminados de cualquier configuración siguen siendo locales y no se transfieren a la nube. La API de configuración de Windows solo comparte los datos de configuración que el usuario carga en la nube.

Configuración de Windows

El recurso windowsSetting representa varias configuraciones del sistema operativo Windows que se almacenan en la nube para un usuario determinado. La configuración de Windows es de dos tipos: roaming y backup. La propiedad settingType de un objeto windowsSetting indica el tipo de la configuración.

Tipo de configuración	Description
Roaming	La configuración de Windows está asociada a la cuenta de un usuario. La configuración es coherente en todos los dispositivos y los cambios realizados en el valor de configuración se sincronizan o se aplican a todos los dispositivos Windows que posee el usuario.
copia de seguridad	La configuración de Windows no se mueve ni se sincroniza entre dispositivos. Este tipo de configuración se usa en escenarios de copia de seguridad y restauración de dispositivos.

Un objeto windowsSetting de tipo backup podría tener una propiedad windowsDeviceId que vincule la configuración a un dispositivo específico.

La API De lista de configuración de Windows devuelve una colección de objetos windowsSetting y sus propiedades. Puede filtrar los resultados por las propiedades windowsDeviceId y settingType .

La API Get windowsSetting permite pasar el identificador de un elemento windowsSetting en la dirección URL para leer un objeto de configuración de Windows específico.

La siguiente representación JSON muestra un ejemplo de un tipo de recurso windowsSetting . La colección instances representa objetos 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"
            }
        ]
}

Advertencia

No se garantiza la estructura del identificador de un objeto windowsSetting y el autor de la llamada no debe depender de él. El identificador debe tratarse como una cadena opaca.

Instancias de configuración de Windows

WindowsSettingInstance representa una instancia de configuración del sistema operativo Windows que se almacena en la nube para un usuario determinado. WindowsSettingInstance pertenece a un objeto windowsSetting.

La siguiente representación JSON muestra un ejemplo de un tipo de recurso 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"
}

La API List Windows setting instances (Enumerar instancias de configuración de Windows ) devuelve una colección de objetos windowsSettingInstance y sus propiedades. La API requiere el identificador de windowsSetting en la dirección URL para leer las instancias de configuración.

La API Get Windows setting instance (Obtener instancia de configuración de Windows ) permite pasar el identificador de windowsSetting y windowsSettingInstance en la dirección URL para leer un objeto de instancia de configuración de Windows específico.

La propiedad payload de una windowsSettingInstance contiene el valor de configuración real. La carga es una cadena en formato codificado en Base64. La propiedad payloadType del objeto windowsSetting indica el tipo del valor de configuración. La carga cuando se descodifica es un objeto JSON, que difiere de la configuración a la configuración y es específica de payloadType.

payloadType (propiedad)

PayloadType define la estructura de una carga windowsSettingInstance. Windows incluye una serie de tipos de carga útil que representan estructuras de configuración distintas usadas por diferentes experiencias de sistema operativo. A medida que Windows evoluciona, se crean e incorporan más tipos de carga a la nube. Consultar la API y explorar la configuración disponible es la mejor manera de obtener información sobre los distintos tipos de carga. Los usuarios y administradores tienen control sobre qué configuración se carga en la nube y la mayoría de los componentes no cargan la configuración predeterminada que el usuario no ha personalizado.

En el ejemplo siguiente se muestra un objeto windowsSettingsInstance devuelto por la 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"
        }
    ]
}

En este ejemplo, payloadTypewindows.data.fileexplorerclassic.advancedsettings representa algunas de las opciones de configuración de las que hace copia de seguridad el Explorador de archivos en la nube. La carga base64 se puede descodificar en una cadena UTF-8 para ver la representación JSON de este objeto.

En el ejemplo siguiente se muestra la carga descodificada.

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

Las propiedades del objeto suelen ser un subconjunto de las que están disponibles en la experiencia de usuario del componente porque los propietarios de los componentes deciden qué configuración proporciona más valor cuando se cargan en la nube.

Tipos de carga útil

Los tipos de carga que se describen en esta sección tienen un rol especial en el proceso de copia de seguridad de la configuración de Windows.

windows.data.platform.backuprestore.deviceprofile

El tipo de carga windows.data.platform.backuprestore.deviceprofile no es un valor aplicado por el usuario; este tipo registra información sobre los dispositivos que han optado por las características de copia de seguridad de configuración. Las siguientes propiedades de este objeto son útiles para comprender el resto de la configuración:

deviceDisplayName : nombre del equipo. Esta configuración se encuentra en la configuración del sistema de Windows en "Iniciar>sistemade configuración>".
profileId : identificador que se usa para vincular elementos windowsSetting al dispositivo que los cargó. Esta propiedad corresponde a windowsSetting.windowsDeviceId y se puede usar como filtro para obtener la configuración de un dispositivo específico de la API De lista de configuración de Windows .

En el ejemplo siguiente se muestra este tipo de recurso.

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

En el ejemplo siguiente se muestra la carga descodificada.

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

La configuración del tipo de carga backupUnitStore es única, ya que el valor de configuración real es un blob en la propiedad de datos. Esto se debe a que la configuración de backupUnitStore se recopila directamente desde el Registro de Windows, en archivos de disco u otras ubicaciones en reposo de Windows. Esta configuración no se diseñó para interoperar con experiencias distintas de los componentes que las crearon. Se exponen en esta API para obtener una cobertura completa de toda la configuración de Windows que se almacena en la nube.

Compartir a través de