Usar a API de configurações do Windows no Microsoft Graph

Artigo
04/29/2024

A API de configuração do Windows permite que usuários e terceiros autorizados que atuam em nome dos usuários recuperem os dados de configurações do sistema operacional Windows armazenados na nuvem da Microsoft. Os dados de configurações do Windows estão disponíveis na nuvem da Microsoft somente quando os usuários ativam o recurso. O escopo dos dados disponíveis para cada usuário depende de suas seleções de configurações de backup. Os valores padrão de qualquer configuração permanecem locais e não são transferidos para a nuvem. A API de configurações do Windows compartilha apenas dados de configurações que o usuário carrega na nuvem.

Configurações do Windows

O recurso windowsSetting representa várias configurações do sistema operacional Windows armazenadas na nuvem para um determinado usuário. As configurações do Windows são de dois tipos: roaming e backup. A propriedade settingType de um objeto windowsSetting indica o tipo da configuração.

Tipo de configuração	Descrição
Roaming	A configuração do Windows está associada à conta de um usuário. A configuração é consistente em todos os dispositivos e todas as alterações no valor de configuração são sincronizadas ou aplicadas a todos os dispositivos Windows que o usuário possui.
Backup	A configuração do Windows não percorre nem sincroniza entre dispositivos. Esse tipo de configuração é usado em cenários de backup e restauração do dispositivo.

Um objeto windowsSetting do tipo backup pode ter uma propriedade windowsDeviceId que vincula a configuração a um dispositivo específico.

A API de configurações do Windows de lista retorna uma coleção de objetos windowsSetting e suas propriedades. Você pode filtrar os resultados pelas propriedades windowsDeviceId e settingType .

A API Obter windowsSetting permite que você passe a ID de um windowsSetting na URL para ler um objeto específico de configuração do Windows.

A representação JSON a seguir mostra um exemplo de um tipo de recurso windowsSetting . A coleção de instâncias 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"
            }
        ]
}

Aviso

A estrutura da ID de um objeto windowsSetting não é garantida e o chamador não deve ter nenhuma dependência dele. A ID deve ser tratada como uma cadeia de caracteres opaca.

Instâncias de configuração do Windows

Um windowsSettingInstance representa uma instância de configuração do sistema operacional Windows que é armazenada na nuvem para um determinado usuário. Um windowsSettingInstance pertence a um windowsSetting.

A representação JSON a seguir mostra um exemplo de um 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"
}

A API listar instâncias de configuração do Windows retorna uma coleção de objetos windowsSettingInstance e suas propriedades. A API requer a ID de um windowsSetting na URL para ler as instâncias de configuração.

A API da instância de configuração do Windows permite que você passe a ID de um windowsSetting e windowsSettingInstance na URL para ler um objeto específico da instância de configuração de janelas.

A propriedade de carga de um windowsSettingInstance contém o valor de configuração real. A carga é uma cadeia de caracteres no formato codificado em Base64. A propriedade payloadType do objeto windowsSetting indica o tipo do valor de configuração. A carga quando decodificada é um objeto JSON, que difere da configuração para a configuração e é específica para o payloadType.

propriedade payloadType

O payloadType define a estrutura de uma carga windowsSettingInstance . O Windows inclui vários tipos de carga que representam estruturas de configuração distintas usadas por diferentes experiências do sistema operacional. À medida que o Windows evolui, mais tipos de carga são criados e integrados à nuvem. Consultar a API e explorar as configurações disponíveis é a melhor maneira de aprender sobre os vários tipos de carga. Os usuários e administradores têm controle sobre quais configurações são carregadas na nuvem e a maioria dos componentes não carrega configurações padrão que o usuário não personalizou.

O exemplo a seguir mostra um objeto windowsSettingsInstance retornado pela 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"
        }
    ]
}

Neste exemplo, o payloadTypewindows.data.fileexplorerclassic.advancedsettings representa algumas das configurações que o Explorador de Arquivos faz backup na nuvem. A carga Base64 pode ser decodificada para uma cadeia de caracteres UTF-8 para ver a representação JSON deste objeto.

O exemplo a seguir mostra a carga decodificada.

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

As propriedades no objeto geralmente são um subconjunto daqueles que estão disponíveis na experiência do usuário do componente porque os proprietários de componentes decidem quais configurações fornecem mais valor quando carregadas na nuvem.

Tipos de carga

Os tipos de carga descritos nesta seção têm uma função especial no processo de backup de configurações do Windows.

windows.data.platform.backuprestore.deviceprofile

O tipo de carga windows.data.platform.backuprestore.deviceprofile não é uma configuração aplicada pelo usuário; esse tipo registra informações sobre dispositivos que optaram por configurações de recursos de backup. As seguintes propriedades neste objeto são úteis para entender o restante das configurações:

deviceDisplayName – o nome do computador. Essa configuração é encontrada nas configurações do sistema Windows em "Iniciar>Sistema de Configurações>".
profileId – um identificador usado para vincular itens windowsSetting ao dispositivo que os carregou. Essa propriedade corresponde a windowsSetting.windowsDeviceId e pode ser usada como um filtro para obter configurações para um dispositivo específico da API de configurações do Windows de Lista .

O exemplo a seguir mostra esse 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"
        }
    ]
}

O exemplo a seguir mostra a carga decodificada.

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

As configurações de tipo de carga backupUnitStore são exclusivas, na qual o valor das configurações reais é um blob na propriedade de dados. Isso ocorre porque as configurações de backupUnitStore são coletadas diretamente do registro do Windows, em arquivos de disco ou em outros locais de repouso em todo o Windows. Essas configurações não foram projetadas para serem interoperáveis com experiências diferentes dos componentes que as criaram. Eles são expostos nesta API para cobertura abrangente de todas as configurações do Windows armazenadas na nuvem.

Share via