Utilizar a API de definições do Windows no Microsoft Graph

Artigo
07/04/2024

A API de definição do Windows permite que os utilizadores e terceiros autorizados que atuam em nome dos utilizadores obtenham os respetivos dados de definições do sistema operativo Windows armazenados na nuvem da Microsoft. Os dados de definições do Windows só estão disponíveis na cloud da Microsoft quando os utilizadores ativam a funcionalidade. O âmbito dos dados disponíveis para cada utilizador depende das respetivas seleções de definições de cópia de segurança. Os valores predefinidos para quaisquer definições permanecem locais e não são transferidos para a cloud. A API de definições do Windows só partilha dados de definições que o utilizador carrega para a cloud.

Configurações do Windows

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

Tipo de definição	Descrição
roaming	A definição do Windows está associada à conta de um utilizador. A definição é consistente em todos os dispositivos e todas as alterações ao valor de definição são sincronizadas ou aplicadas a todos os dispositivos Windows que o utilizador possui.
cópia de segurança	A definição do Windows não circula ou sincroniza entre dispositivos. Este tipo de definição é utilizado em cenários de cópia de segurança e restauro de dispositivos.

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

A API listar definições do Windows devolve uma coleção de objetos windowsSetting e respetivas propriedades. Pode filtrar os resultados pelas propriedades windowsDeviceId e settingType .

A API Get windowsSetting permite-lhe transmitir o ID de um windowsSetting no URL para ler um objeto de definição específico do Windows.

A representação JSON seguinte mostra um exemplo de um tipo de recurso windowsSetting . A coleção de instâncias representa os 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 do ID de um objeto windowsSetting não é garantida e o autor da chamada não deve assumir qualquer dependência. O ID deve ser tratado como uma cadeia opaca.

Instâncias de definição do Windows

Uma windowsSettingInstance representa uma instância de definição do sistema operativo Windows armazenada na nuvem para um determinado utilizador. Uma windowsSettingInstance pertence a um windowsSetting.

A representação JSON seguinte 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 definição do Windows devolve uma coleção de objetos windowsSettingInstance e as respetivas propriedades. A API requer o ID de um windowsSetting no URL para ler as instâncias de definição.

A API obter instância de definição do Windows permite-lhe transmitir o ID de um windowsSetting e windowsSettingInstance no URL para ler um objeto de instância de definição do Windows específico.

A propriedade payload de um windowsSettingInstance contém o valor de definição real. O payload é uma cadeia no formato codificado em Base64. A propriedade payloadType do objeto windowsSetting indica o tipo do valor de definição. O payload quando descodificado é um objeto JSON, que difere da definição para a definição e é específico do payloadType.

propriedade payloadType

O payloadType define a estrutura de um payload windowsSettingInstance . O Windows inclui vários tipos de payload que representam estruturas de definições distintas utilizadas por diferentes experiências do sistema operativo. À medida que o Windows evolui, são criados e integrados mais tipos de payload na cloud. Consultar a API e explorar as definições disponíveis é a melhor forma de saber mais sobre os vários tipos de payload. Os utilizadores e administradores têm controlo sobre as definições que são carregadas para a cloud e a maioria dos componentes não carrega as predefinições que o utilizador não personalizou.

O exemplo seguinte mostra um objeto windowsSettingsInstance devolvido 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, payloadTypewindows.data.fileexplorerclassic.advancedsettings representa algumas das definições que o Explorador de Ficheiros faz cópia de segurança para a cloud. O payload Base64 pode ser descodificado para uma cadeia UTF-8 para ver a representação JSON deste objeto.

O exemplo seguinte mostra o payload descodificado.

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

Normalmente, as propriedades no objeto são um subconjunto das que estão disponíveis na experiência de utilizador do componente, porque os proprietários dos componentes decidem quais as definições que fornecem mais valor quando carregadas para a cloud.

Tipos de payload

Os tipos de payload descritos nesta secção têm uma função especial no processo de cópia de segurança das definições do Windows.

windows.data.platform.backuprestore.deviceprofile

O tipo de payload windows.data.platform.backuprestore.deviceprofile não é uma definição aplicada pelo utilizador; este tipo regista informações sobre dispositivos que optaram por ativar as funcionalidades de cópia de segurança de definições. As seguintes propriedades neste objeto são úteis para compreender o resto das definições:

deviceDisplayName – o nome do computador. Esta definição encontra-se nas definições do sistema Windows em "Iniciar>Sistema de Definições>".
profileId - Um identificador utilizado para ligar itens windowsSetting ao dispositivo que os carregou. Esta propriedade corresponde a windowsSetting.windowsDeviceId e pode ser utilizada como um filtro para obter definições para um dispositivo específico a partir da API de definições de Lista do Windows .

O exemplo seguinte mostra 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"
        }
    ]
}

O exemplo seguinte mostra o payload descodificado.

{
    "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 definições do tipo de payload backupUnitStore são exclusivas na medida em que o valor das definições reais é um blob na propriedade de dados. Isto deve-se ao facto de as definições de backupUnitStore serem recolhidas diretamente a partir do registo do Windows, em ficheiros de disco ou noutras localizações inativas em todo o Windows. Estas definições não foram concebidas para serem interoperáveis com experiências diferentes dos componentes que as criaram. São expostas nesta API para uma cobertura abrangente de todas as definições do Windows armazenadas na cloud.

Compartilhar via