From 54ac99a9bd587f91cf87871054c496841fef5af5 Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Fri, 9 Feb 2024 20:48:03 -0700 Subject: [PATCH 01/54] Added doc for DMA Settings API --- .../beta/api/usersettings-list-windows.md | 310 ++++++++++++++++++ api-reference/beta/api/windowssetting-get.md | 103 ++++++ .../beta/api/windowssetting-list-instances.md | 106 ++++++ .../beta/api/windowssettinginstance-get.md | 101 ++++++ .../beta/changelog/Microsoft.PDRS.json | 46 +++ .../usersettings-list-windows-permissions.md | 13 + .../windowssetting-get-permissions.md | 13 + ...ndowssetting-list-instances-permissions.md | 13 + .../windowssettinginstance-get-permissions.md | 13 + api-reference/beta/resources/enums.md | 10 + api-reference/beta/resources/usersettings.md | 9 +- .../beta/resources/windowssetting.md | 71 ++++ .../beta/resources/windowssettinginstance.md | 63 ++++ api-reference/beta/toc.yml | 13 + 14 files changed, 883 insertions(+), 1 deletion(-) create mode 100644 api-reference/beta/api/usersettings-list-windows.md create mode 100644 api-reference/beta/api/windowssetting-get.md create mode 100644 api-reference/beta/api/windowssetting-list-instances.md create mode 100644 api-reference/beta/api/windowssettinginstance-get.md create mode 100644 api-reference/beta/changelog/Microsoft.PDRS.json create mode 100644 api-reference/beta/includes/permissions/usersettings-list-windows-permissions.md create mode 100644 api-reference/beta/includes/permissions/windowssetting-get-permissions.md create mode 100644 api-reference/beta/includes/permissions/windowssetting-list-instances-permissions.md create mode 100644 api-reference/beta/includes/permissions/windowssettinginstance-get-permissions.md create mode 100644 api-reference/beta/resources/windowssetting.md create mode 100644 api-reference/beta/resources/windowssettinginstance.md diff --git a/api-reference/beta/api/usersettings-list-windows.md b/api-reference/beta/api/usersettings-list-windows.md new file mode 100644 index 00000000000..ff6f8e5b046 --- /dev/null +++ b/api-reference/beta/api/usersettings-list-windows.md @@ -0,0 +1,310 @@ +--- +title: "List Windows Settings" +description: "Get a list of the windowsSetting objects and their properties." +author: "MS-Arko" +ms.localizationpriority: medium +ms.prod: "cross-device-experiences" +doc_type: apiPageType +--- + +# List Windows settings stored in cloud + +Namespace: microsoft.graph + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Get a list of the [windowsSetting](../resources/windowssetting.md) objects and their properties. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + + +[!INCLUDE [permissions-table](../includes/permissions/usersettings-list-windows-permissions.md)] + +## HTTP request + + + +Get a list of Windows settings for the signed-in user. + +````http +``` http +GET /me/settings/windows +```` + +## Optional query parameters + +This method supports $filter OData query parameter to help customize the response. The result can be filtered by `windowsDeviceId` and `settingType` properties. For general information, see [OData query parameters](/graph/query-parameters). + +## Request headers + +| Name | Description | +| :------------ | :-------------------------------------------------------------------------------------------------------- | +| Authorization | Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts). | + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [windowsSetting](../resources/windowssetting.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + + + +```http +GET https://graph.microsoft.com/beta/me/settings/windows +``` + +### Response + +The following example shows the response. + +> **Note:** The response object shown here might be shortened for readability. + + + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "id": "default$windows.data.fileexplorerclassic.searchsettings", + "windowsDeviceId": "String", + "settingType": "String", + "payloadType": "String", + "instances": [ + { + "id": "9715f1d9-49d1-4b94-041b-443ac419d417", + "payload": "String (Base64 encoded JSON)", + "lastModifiedDateTime": "String (timestamp)", + "createdDateTime": "String (timestamp)", + "expirationDateTime": "String (timestamp)" + } + ] + }, + { + "id": "default$windows.data.input.devices.pensyncedsettings", + "windowsDeviceId": "String", + "settingType": "String", + "payloadType": "String", + "instances": [ + { + "id": "666dcb9b-49d1-4b94-041b-443ac419d417", + "payload": "String (Base64 encoded JSON)", + "lastModifiedDateTime": "String (timestamp)", + "createdDateTime": "String (timestamp)", + "expirationDateTime": "String (timestamp)" + } + ] + } + ] +} +``` +### Request + +The following example shows a filter by `roaming` settingType request. + + + +```http +GET https://graph.microsoft.com/beta/me/settings/windows?$filter=settingType eq 'roaming' +``` + +### Response + +The following example shows the response. + +> **Note:** The response object shown here might be shortened for readability. + + + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "id": "default$windows.data.fileexplorerclassic.shellstatesettings", + "settingType": "roaming", + "payloadType": "String", + "instances": [ + { + "id": "0b3af867-49d1-4b94-041b-443ac419d417", + "payload": "String (Base64 encoded JSON)", + "lastModifiedDateTime": "String (timestamp)", + "createdDateTime": "String (timestamp)", + "expirationDateTime": "String (timestamp)" + } + ] + }, + { + "id": "default$windows.data.fileexplorerclassic.cabinetstatesettings", + "settingType": "roaming", + "payloadType": "String", + "instances": [ + { + "id": "5038fa1b-49d1-4b94-041b-443ac419d417", + "payload": "String (Base64 encoded JSON)", + "lastModifiedDateTime": "String (timestamp)", + "createdDateTime": "String (timestamp)", + "expirationDateTime": "String (timestamp)" + } + ] + } + ] +} +``` +### Request + +The following example shows a filter by `backup` settingType request. + + + +```http +GET https://graph.microsoft.com/beta/me/settings/windows?$filter=settingType eq 'backup' +``` + +### Response + +The following example shows the response. + +> **Note:** The response object shown here might be shortened for readability. + + + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "id": "{67585f9f-ee4b-4dd8-808e-d88375d66ef7}$windows.data.apps.devicemetadata", + "windowsDeviceId": "String", + "settingType": "backup", + "payloadType": "String", + "instances": [ + { + "id": "14b50191-10e5-4da5-9099-8c909b8458bd", + "payload": "String (Base64 encoded JSON)", + "lastModifiedDateTime": "String (timestamp)", + "createdDateTime": "String (timestamp)", + "expirationDateTime": "String (timestamp)" + } + ] + }, + { + "id": "{55f26da7-5824-4937-9028-9bba274f049f}$windows.data.apps.devicemetadata", + "windowsDeviceId": "String", + "settingType": "backup", + "payloadType": "String", + "instances": [ + { + "id": "da2f0307-2a8d-4242-846f-56abd95f7213", + "payload": "String (Base64 encoded JSON)", + "lastModifiedDateTime": "String (timestamp)", + "createdDateTime": "String (timestamp)", + "expirationDateTime": "String (timestamp)" + } + ] + } + ] +} +``` +### Request + +The following example shows a filter by windowsDeviceId request. + + + +```http +GET https://graph.microsoft.com/beta/me/settings/windows?$filter=windowsDeviceId eq '67585f9f-ee4b-4dd8-808e-d88375d66ef7' +``` + +### Response + +The following example shows the response. + +> **Note:** The response object shown here might be shortened for readability. + + + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "id": "{67585f9f-ee4b-4dd8-808e-d88375d66ef7}$windows.data.apps.devicemetadata", + "windowsDeviceId": "67585f9f-ee4b-4dd8-808e-d88375d66ef7", + "settingType": "backup", + "payloadType": "String", + "instances": [ + { + "id": "14b50191-10e5-4da5-9099-8c909b8458bd", + "payload": "String (Base64 encoded JSON)", + "lastModifiedDateTime": "String (timestamp)", + "createdDateTime": "String (timestamp)", + "expirationDateTime": "String (timestamp)" + } + ] + } + ] +} +``` diff --git a/api-reference/beta/api/windowssetting-get.md b/api-reference/beta/api/windowssetting-get.md new file mode 100644 index 00000000000..e60e3e79b07 --- /dev/null +++ b/api-reference/beta/api/windowssetting-get.md @@ -0,0 +1,103 @@ +--- +title: "Get Windows setting" +description: "Read the properties and relationships of a windowsSetting object." +author: "MS-Arko" +ms.localizationpriority: medium +ms.prod: "cross-device-experiences" +doc_type: apiPageType +--- + +# Get Windows setting stored in cloud + +Namespace: microsoft.graph + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Read the properties and relationships of a [windowsSetting](../resources/windowssetting.md) object by passing id of the setting in the URL. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +[!INCLUDE [permissions-table](../includes/permissions/windowssetting-get-permissions.md)] + +## HTTP request + + +Get a particular Windows setting for the signed-in user. +``` http +GET /me/settings/windows/{windowsSettingId} +``` + +## Optional query parameters + +N/A + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a [windowsSetting](../resources/windowssetting.md) object in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/beta/me/settings/windows/{windowsSettingId} +``` + + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "id": "default$windows.data.fileexplorerclassic.searchsettings", + "windowsDeviceId": "String", + "settingType": "String", + "payloadType": "String", + "instances": [ + { + "id": "9715f1d9-49d1-4b94-041b-443ac419d417", + "payload": "String (Base64 encoded JSON)", + "lastModifiedDateTime": "String (timestamp)", + "createdDateTime": "String (timestamp)", + "expirationDateTime": "String (timestamp)" + } + ] +} +``` + diff --git a/api-reference/beta/api/windowssetting-list-instances.md b/api-reference/beta/api/windowssetting-list-instances.md new file mode 100644 index 00000000000..d4d8d276da1 --- /dev/null +++ b/api-reference/beta/api/windowssetting-list-instances.md @@ -0,0 +1,106 @@ +--- +title: "List Windows Setting Instances" +description: "Get a list of the windowsSettingInstance objects and their properties." +author: "MS-Arko" +ms.localizationpriority: medium +ms.prod: "cross-device-experiences" +doc_type: apiPageType +--- + +# List Windows setting instances stored in cloud + +Namespace: microsoft.graph + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Get a list of the [windowsSettingInstance](../resources/windowssettinginstance.md) objects and their properties. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +[!INCLUDE [permissions-table](../includes/permissions/windowssetting-list-instances-permissions.md)] + +## HTTP request + + +Get a particular Windows setting's instances for the signed-in user. +``` http +GET /me/settings/windows/{windowsSettingId}/instances +``` + +## Optional query parameters + +N/A + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [windowsSettingInstance](../resources/windowssettinginstance.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/beta/me/settings/windows/{windowsSettingId}/instances +``` + + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "id": "9715f1d9-49d1-4b94-041b-443ac419d417", + "payload": "String (Base64 encoded JSON)", + "lastModifiedDateTime": "String (timestamp)", + "createdDateTime": "String (timestamp)", + "expirationDateTime": "String (timestamp)" + }, + { + "id": "6984732f-86b0-8e31-dc02-37fce0df6d61", + "payload": "String (Base64 encoded JSON)", + "lastModifiedDateTime": "String (timestamp)", + "createdDateTime": "String (timestamp)", + "expirationDateTime": "String (timestamp)" + } + ] +} +``` + diff --git a/api-reference/beta/api/windowssettinginstance-get.md b/api-reference/beta/api/windowssettinginstance-get.md new file mode 100644 index 00000000000..e1bb8c7df8b --- /dev/null +++ b/api-reference/beta/api/windowssettinginstance-get.md @@ -0,0 +1,101 @@ +--- +title: "Get Windows setting instance" +description: "Read the properties and relationships of a windowsSettingInstance object." +author: "MS-Arko" +ms.localizationpriority: medium +ms.prod: "cross-device-experiences" +doc_type: apiPageType +--- + +# Get Windows setting instance stored in cloud + +Namespace: microsoft.graph + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Read the properties and relationships of a [windowsSettingInstance](../resources/windowssettinginstance.md) object by passing windows setting id and windows setting instance id in the URL. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + + +[!INCLUDE [permissions-table](../includes/permissions/windowssettinginstance-get-permissions.md)] + +## HTTP request + + + +Get a particular Windows setting instance for the signed-in user. + +```http +GET /me/settings/windows/{windowsSettingId}/instances/{windowsSettingInstanceId} +``` + +## Optional query parameters + +N/A + +## Request headers + +| Name | Description | +| :------------ | :-------------------------------------------------------------------------------------------------------- | +| Authorization | Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts). | + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a [windowsSettingInstance](../resources/windowssettinginstance.md) object in the response body. + +## Examples + +### Request + +The following example shows a request. + + + +```http +GET https://graph.microsoft.com/beta/me/settings/windows/{windowsSettingId}/instances/{windowsSettingInstanceId} +``` + +### Response + +The following example shows the response. + +> **Note:** The response object shown here might be shortened for readability. + + + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "id": "9715f1d9-49d1-4b94-041b-443ac419d417", + "payload": "String (Base64 encoded JSON)", + "lastModifiedDateTime": "String (timestamp)", + "createdDateTime": "String (timestamp)", + "expirationDateTime": "String (timestamp)" +} +``` diff --git a/api-reference/beta/changelog/Microsoft.PDRS.json b/api-reference/beta/changelog/Microsoft.PDRS.json new file mode 100644 index 00000000000..e53c87e83af --- /dev/null +++ b/api-reference/beta/changelog/Microsoft.PDRS.json @@ -0,0 +1,46 @@ +{ + "changelog": [ + { + "ChangeList": [ + { + "Id": "af6ceee7-aa8a-4965-80fa-8fa9fd460ad2", + "ApiChange": "Enumeration", + "ChangedApiName": "windowsSettingType", + "ChangeType": "Addition", + "Description": "Added the **windowsSettingType** enumeration type.", + "Target": "windowsSettingType" + }, + { + "Id": "af6ceee7-aa8a-4965-80fa-8fa9fd460ad2", + "ApiChange": "Resource", + "ChangedApiName": "userSettings", + "ChangeType": "Modification", + "Description": "Modified the [userSettings](https://learn.microsoft.com/en-us/graph/api/resources/userSettings?view=graph-rest-beta) resource.", + "Target": "userSettings" + }, + { + "Id": "af6ceee7-aa8a-4965-80fa-8fa9fd460ad2", + "ApiChange": "Resource", + "ChangedApiName": "windowsSetting", + "ChangeType": "Addition", + "Description": "Added the [windowsSetting](https://learn.microsoft.com/en-us/graph/api/resources/windowsSetting?view=graph-rest-beta) resource.", + "Target": "windowsSetting" + }, + { + "Id": "af6ceee7-aa8a-4965-80fa-8fa9fd460ad2", + "ApiChange": "Resource", + "ChangedApiName": "windowsSettingInstance", + "ChangeType": "Addition", + "Description": "Added the [windowsSettingInstance](https://learn.microsoft.com/en-us/graph/api/resources/windowsSettingInstance?view=graph-rest-beta) resource.", + "Target": "windowsSettingInstance" + } + ], + "Id": "af6ceee7-aa8a-4965-80fa-8fa9fd460ad2", + "Cloud": "Prod", + "Version": "beta", + "CreatedDateTime": "2024-02-08T17:50:40.810248Z", + "WorkloadArea": "Cross-device experiences", + "SubArea": "" + } + ] +} \ No newline at end of file diff --git a/api-reference/beta/includes/permissions/usersettings-list-windows-permissions.md b/api-reference/beta/includes/permissions/usersettings-list-windows-permissions.md new file mode 100644 index 00000000000..b488a5a3357 --- /dev/null +++ b/api-reference/beta/includes/permissions/usersettings-list-windows-permissions.md @@ -0,0 +1,13 @@ +--- +description: Automatically generated file. DO NOT MODIFY +ms.topic: include +ms.localizationpriority: medium +--- + +|Permission type|Least privileged permissions|Higher privileged permissions| +|:---|:---|:---| +|Delegated (work or school account)|UserWindowsSettings.Read|Not available.| +|Delegated (personal Microsoft account)|UserWindowsSettings.Read|Not available.| +|Application|Not supported.|Not supported.| + + diff --git a/api-reference/beta/includes/permissions/windowssetting-get-permissions.md b/api-reference/beta/includes/permissions/windowssetting-get-permissions.md new file mode 100644 index 00000000000..b488a5a3357 --- /dev/null +++ b/api-reference/beta/includes/permissions/windowssetting-get-permissions.md @@ -0,0 +1,13 @@ +--- +description: Automatically generated file. DO NOT MODIFY +ms.topic: include +ms.localizationpriority: medium +--- + +|Permission type|Least privileged permissions|Higher privileged permissions| +|:---|:---|:---| +|Delegated (work or school account)|UserWindowsSettings.Read|Not available.| +|Delegated (personal Microsoft account)|UserWindowsSettings.Read|Not available.| +|Application|Not supported.|Not supported.| + + diff --git a/api-reference/beta/includes/permissions/windowssetting-list-instances-permissions.md b/api-reference/beta/includes/permissions/windowssetting-list-instances-permissions.md new file mode 100644 index 00000000000..b488a5a3357 --- /dev/null +++ b/api-reference/beta/includes/permissions/windowssetting-list-instances-permissions.md @@ -0,0 +1,13 @@ +--- +description: Automatically generated file. DO NOT MODIFY +ms.topic: include +ms.localizationpriority: medium +--- + +|Permission type|Least privileged permissions|Higher privileged permissions| +|:---|:---|:---| +|Delegated (work or school account)|UserWindowsSettings.Read|Not available.| +|Delegated (personal Microsoft account)|UserWindowsSettings.Read|Not available.| +|Application|Not supported.|Not supported.| + + diff --git a/api-reference/beta/includes/permissions/windowssettinginstance-get-permissions.md b/api-reference/beta/includes/permissions/windowssettinginstance-get-permissions.md new file mode 100644 index 00000000000..b488a5a3357 --- /dev/null +++ b/api-reference/beta/includes/permissions/windowssettinginstance-get-permissions.md @@ -0,0 +1,13 @@ +--- +description: Automatically generated file. DO NOT MODIFY +ms.topic: include +ms.localizationpriority: medium +--- + +|Permission type|Least privileged permissions|Higher privileged permissions| +|:---|:---|:---| +|Delegated (work or school account)|UserWindowsSettings.Read|Not available.| +|Delegated (personal Microsoft account)|UserWindowsSettings.Read|Not available.| +|Application|Not supported.|Not supported.| + + diff --git a/api-reference/beta/resources/enums.md b/api-reference/beta/resources/enums.md index a3dedfe2b14..1105aefde16 100644 --- a/api-reference/beta/resources/enums.md +++ b/api-reference/beta/resources/enums.md @@ -1813,6 +1813,16 @@ Namespace: microsoft.graph |system |unknownFutureValue +### windowsSettingType values + +Possible types of Windows settings. + +| Member | Value | Description | +| :----------------- | :---- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| roaming | 0 | Windows setting is associated with a user account. It is consistent across all devices and any changes to the setting value are synced or applied to all Windows devices that the user owns. | +| backup | 1 | Windows setting is linked to a specific device of a user. This type of setting is not synced across all devices that the user owns. In other words, this type of setting is unique to each device. | +| unknownFutureValue | 2 | This is not a valid setting type. It is only a placeholder for any possible setting type that may be added in the future. | + ### workforceIntegrationEncryptionProtocol values | Member diff --git a/api-reference/beta/resources/usersettings.md b/api-reference/beta/resources/usersettings.md index e662e90433b..4651f8ecd24 100644 --- a/api-reference/beta/resources/usersettings.md +++ b/api-reference/beta/resources/usersettings.md @@ -40,6 +40,12 @@ Configure [contactMergeSuggestions](../resources/contactmergesuggestions.md): - Determining whether suggestion to merge duplicate contacts for a user is enabled. - Disabling or enabling suggestion to merge duplicate contacts for a user. +Export user's Windows settings and values stored in cloud. + - Get a list of the user's [windowsSetting](../resources/windowssetting.md) objects. + - Get a filtered list of the user's [windowsSetting](../resources/windowssetting.md) objects by passing, + - [windowssettingtype](../resources/enums.md#windowssettingtype-values) in filter query. + - [windowsDeviceId](../resources/windowssetting.md#properties) in filter query. + Inherits from [entity](entity.md). To learn how to get or update user settings, see [Get settings](../api/usersettings-get.md) and [Update settings](../api/usersettings-update.md). > [!NOTE] @@ -50,6 +56,7 @@ Inherits from [entity](entity.md). To learn how to get or update user settings, |:---------------|:--------|:----------| |[Get user settings](../api/usersettings-get.md) |[userSettings](../resources/usersettings.md)| Get the user and organization settings. | |[Update user settings](../api/usersettings-update.md) |[userSettings](../resources/usersettings.md)| Update the user current settings. | +|[List windows settings](../api/usersettings-list-windows.md)|[windowsSetting](../resources/windowssetting.md) collection|Get the windowsSetting resources from the windows navigation property.| ## Properties @@ -67,7 +74,7 @@ Inherits from [entity](entity.md). To learn how to get or update user settings, |itemInsights|[userInsightsSettings](userinsightssettings.md)| The user's settings for the visibility of meeting hour insights, and insights derived between a user and other items in Microsoft 365, such as documents or sites. [Get userInsightsSettings](../api/userinsightssettings-get.md) through this navigation property. | |regionalAndLanguageSettings|[regionalAndLanguageSettings](regionalandlanguagesettings.md)| The user's preferences for languages, regional locale and date/time formatting. | |shiftPreferences|[shiftPreferences](shiftpreferences.md)| The shift preferences for the user. | - +|windows|[windowsSetting](../resources/windowssetting.md) collection|The Windows settings of the user stored in cloud.| ## JSON representation diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md new file mode 100644 index 00000000000..f5f7baff56d --- /dev/null +++ b/api-reference/beta/resources/windowssetting.md @@ -0,0 +1,71 @@ +--- +title: "windowsSetting resource type" +description: "windowsSetting represents settings from Windows operating system." +author: "MS-Arko" +ms.localizationpriority: medium +ms.prod: "cross-device-experiences" +doc_type: resourcePageType +--- + +# windowsSetting resource type + +Namespace: microsoft.graph + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +**windowsSetting** represents settings from Windows operating system that are stored in the cloud for a given user. + +There are two types of **windowsSetting**: `roaming` and `backup`. More information about the types of **windowsSetting** can be found in the [windowsSettingType](enums.md) enum. A **windowsSetting** of type `backup` has a *windowsDeviceId* property that links the setting to a specific device. + +When getting a list of **windowsSetting** objects, the result can be filtered by *windowsDeviceId* and *settingType* properties. For more information, see [List Windows settings stored in cloud](../api/usersettings-list-windows.md). + +The *windowsDeviceId* is a unique identifier for a device. The device that a **windowsSetting** of type `backup` is associated with is indicated by the *windowsDeviceId*. However, it is a guid and does not help to identify the actual device by a friendly property like device name. To identify the device that the *windowsDeviceId* refers to, the following steps can be followed: + +- Use the [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API to list all the settings for the user. +- Find the id of the device profile setting. +- Use the [settings API](../api/windowssetting-get.md) to fetch the device profile setting with the id. +- The *instances* navigation property of the device profile setting will contain all the device profile setting values. +- Decode the *payload* of each setting value to find the *windowsDeviceId*, corresponding device name, and other details. + +Inherits from [entity](../resources/entity.md). + +## Methods +|Method|Return type|Description| +|:---|:---|:---| +|[List windowsSetting objects](../api/usersettings-list-windows.md)|[windowsSetting](../resources/windowssetting.md) collection|Get a list of the [windowsSetting](../resources/windowssetting.md) objects and their properties.| +|[Get windowsSetting](../api/windowssetting-get.md)|[windowsSetting](../resources/windowssetting.md)|Read the properties and relationships of a [windowsSetting](../resources/windowssetting.md) object.| +|[List instances](../api/windowssetting-list-instances.md)|[windowsSettingInstance](../resources/windowssettinginstance.md) collection|Get the windowsSettingInstance resources from the instances navigation property.| + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|id|String|The unique identifier of the object.| +|payloadType|String|The type of setting payloads contained in the *instances* navigation property.| +|settingType|windowsSettingType|The type of setting. Possible values are: `roaming`, `backup`, `unknownFutureValue`. `unknownFutureValue` is a future placeholder and not a real settingType.| +|windowsDeviceId|String|A unique identifier for the device the setting belongs to if it is of the settingType `backup`.| + +## Relationships +|Relationship|Type|Description| +|:---|:---|:---| +|instances|[windowsSettingInstance](../resources/windowssettinginstance.md) collection|A collection of setting values for a given **windowsSetting**.| + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.windowsSetting", + "id": "String (identifier)", + "windowsDeviceId": "String", + "settingType": "String", + "payloadType": "String" +} +``` + diff --git a/api-reference/beta/resources/windowssettinginstance.md b/api-reference/beta/resources/windowssettinginstance.md new file mode 100644 index 00000000000..2b574e76dd2 --- /dev/null +++ b/api-reference/beta/resources/windowssettinginstance.md @@ -0,0 +1,63 @@ +--- +title: "windowsSettingInstance resource type" +description: "windowsSettingInstance represents a setting instance from Windows operating system." +author: "MS-Arko" +ms.localizationpriority: medium +ms.prod: "cross-device-experiences" +doc_type: resourcePageType +--- + +# windowsSettingInstance resource type + +Namespace: microsoft.graph + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +**windowsSettingInstance** represents setting instances from Windows operating system that are stored in the cloud for a given user. + +A **windowsSettingInstance** belongs to a [**windowsSetting**](../resources/windowssetting.md) and represents a specific setting value for a given user. + +The *payload* property of a **windowsSettingInstance** contains the actual setting value. The *payload* is a string in base64 encoded format. The *payloadType* property of the [**windowsSetting**](../resources/windowssetting.md) object indicates the type of the setting value. The *payload* when decoded is a JSON object which differs from setting to setting and is specific to the *payloadType*. + + +Inherits from [entity](../resources/entity.md). + +## Methods +|Method|Return type|Description| +|:---|:---|:---| +|[List windowsSettingInstance objects](../api/windowssetting-list-instances.md)|[windowsSettingInstance](../resources/windowssettinginstance.md) collection|Get a list of the [windowsSettingInstance](../resources/windowssettinginstance.md) objects and their properties.| +|[Get windowsSettingInstance](../api/windowssettinginstance-get.md)|[windowsSettingInstance](../resources/windowssettinginstance.md)|Read the properties and relationships of a [windowsSettingInstance](../resources/windowssettinginstance.md) object.| + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|createdDateTime|DateTimeOffset|Set by the server. DateTime in UTC when the object was created on the server.| +|expirationDateTime|DateTimeOffset|Set by the server. DateTime in UTC when the object will expire after which it will no longer be available.| +|id|String|The unique identifier of the object. Inherited from [entity](../resources/entity.md).| +|lastModifiedDateTime|DateTimeOffset|Set by the server if not provided in Windows client device's request. DateTime in UTC when the object was modified by the user’s Windows device.| +|payload|String|Base64 encoded JSON setting value.| + +## Relationships +None. + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.windowsSettingInstance", + "id": "String (identifier)", + "payload": "String (Base64 encoded JSON)", + "lastModifiedDateTime": "String (timestamp)", + "createdDateTime": "String (timestamp)", + "expirationDateTime": "String (timestamp)" +} +``` + diff --git a/api-reference/beta/toc.yml b/api-reference/beta/toc.yml index ce25578f315..1c84331b58e 100644 --- a/api-reference/beta/toc.yml +++ b/api-reference/beta/toc.yml @@ -1599,6 +1599,19 @@ items: href: api/projectrome-put-historyitem.md - name: Delete a history item href: api/projectrome-delete-historyitem.md + - name: Roaming data + items: + - name: Windows settings + href: resources/windowssetting.md + items: + - name: List Windows settings + href: api/usersettings-list-windows.md + - name: Get Windows setting + href: api/windowssetting-get.md + - name: List Windows setting instances + href: api/windowssetting-list-instances.md + - name: Get Windows setting instance + href: api/windowssettinginstance-get.md - name: Customer booking displayName: Bookings, Microsoft Bookings items: From 0f7d2efa48be9efe5e5a493f2cc37ef2a1c194c9 Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Sat, 10 Feb 2024 00:19:45 -0700 Subject: [PATCH 02/54] Added odata.types and numbered usersettings-list examples --- .../beta/api/usersettings-list-windows.md | 15 +++++++++++---- api-reference/beta/api/windowssetting-get.md | 1 + .../beta/api/windowssetting-list-instances.md | 2 ++ .../beta/api/windowssettinginstance-get.md | 1 + 4 files changed, 15 insertions(+), 4 deletions(-) diff --git a/api-reference/beta/api/usersettings-list-windows.md b/api-reference/beta/api/usersettings-list-windows.md index ff6f8e5b046..6fae42d7451 100644 --- a/api-reference/beta/api/usersettings-list-windows.md +++ b/api-reference/beta/api/usersettings-list-windows.md @@ -67,7 +67,7 @@ The following example shows a request. @@ -95,6 +95,7 @@ Content-Type: application/json { "value": [ { + "@odata.type": "#microsoft.graph.windowsSetting", "id": "default$windows.data.fileexplorerclassic.searchsettings", "windowsDeviceId": "String", "settingType": "String", @@ -110,6 +111,7 @@ Content-Type: application/json ] }, { + "@odata.type": "#microsoft.graph.windowsSetting", "id": "default$windows.data.input.devices.pensyncedsettings", "windowsDeviceId": "String", "settingType": "String", @@ -133,7 +135,7 @@ The following example shows a filter by `roaming` settingType request. @@ -161,6 +163,7 @@ Content-Type: application/json { "value": [ { + "@odata.type": "#microsoft.graph.windowsSetting", "id": "default$windows.data.fileexplorerclassic.shellstatesettings", "settingType": "roaming", "payloadType": "String", @@ -175,6 +178,7 @@ Content-Type: application/json ] }, { + "@odata.type": "#microsoft.graph.windowsSetting", "id": "default$windows.data.fileexplorerclassic.cabinetstatesettings", "settingType": "roaming", "payloadType": "String", @@ -197,7 +201,7 @@ The following example shows a filter by `backup` settingType request. @@ -225,6 +229,7 @@ Content-Type: application/json { "value": [ { + "@odata.type": "#microsoft.graph.windowsSetting", "id": "{67585f9f-ee4b-4dd8-808e-d88375d66ef7}$windows.data.apps.devicemetadata", "windowsDeviceId": "String", "settingType": "backup", @@ -240,6 +245,7 @@ Content-Type: application/json ] }, { + "@odata.type": "#microsoft.graph.windowsSetting", "id": "{55f26da7-5824-4937-9028-9bba274f049f}$windows.data.apps.devicemetadata", "windowsDeviceId": "String", "settingType": "backup", @@ -263,7 +269,7 @@ The following example shows a filter by windowsDeviceId request. @@ -291,6 +297,7 @@ Content-Type: application/json { "value": [ { + "@odata.type": "#microsoft.graph.windowsSetting", "id": "{67585f9f-ee4b-4dd8-808e-d88375d66ef7}$windows.data.apps.devicemetadata", "windowsDeviceId": "67585f9f-ee4b-4dd8-808e-d88375d66ef7", "settingType": "backup", diff --git a/api-reference/beta/api/windowssetting-get.md b/api-reference/beta/api/windowssetting-get.md index e60e3e79b07..55df1aca41f 100644 --- a/api-reference/beta/api/windowssetting-get.md +++ b/api-reference/beta/api/windowssetting-get.md @@ -85,6 +85,7 @@ HTTP/1.1 200 OK Content-Type: application/json { + "@odata.type": "#microsoft.graph.windowsSetting", "id": "default$windows.data.fileexplorerclassic.searchsettings", "windowsDeviceId": "String", "settingType": "String", diff --git a/api-reference/beta/api/windowssetting-list-instances.md b/api-reference/beta/api/windowssetting-list-instances.md index d4d8d276da1..52152644ef5 100644 --- a/api-reference/beta/api/windowssetting-list-instances.md +++ b/api-reference/beta/api/windowssetting-list-instances.md @@ -87,6 +87,7 @@ Content-Type: application/json { "value": [ { + "@odata.type": "#microsoft.graph.windowsSettingInstance", "id": "9715f1d9-49d1-4b94-041b-443ac419d417", "payload": "String (Base64 encoded JSON)", "lastModifiedDateTime": "String (timestamp)", @@ -94,6 +95,7 @@ Content-Type: application/json "expirationDateTime": "String (timestamp)" }, { + "@odata.type": "#microsoft.graph.windowsSettingInstance", "id": "6984732f-86b0-8e31-dc02-37fce0df6d61", "payload": "String (Base64 encoded JSON)", "lastModifiedDateTime": "String (timestamp)", diff --git a/api-reference/beta/api/windowssettinginstance-get.md b/api-reference/beta/api/windowssettinginstance-get.md index e1bb8c7df8b..f71bd994b98 100644 --- a/api-reference/beta/api/windowssettinginstance-get.md +++ b/api-reference/beta/api/windowssettinginstance-get.md @@ -92,6 +92,7 @@ HTTP/1.1 200 OK Content-Type: application/json { + "@odata.type": "#microsoft.graph.windowsSettingInstance", "id": "9715f1d9-49d1-4b94-041b-443ac419d417", "payload": "String (Base64 encoded JSON)", "lastModifiedDateTime": "String (timestamp)", From e9288af50aca7021ab74ede4cae5c83e5da185e5 Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Sat, 10 Feb 2024 00:47:26 -0700 Subject: [PATCH 03/54] Removed typo error - extra line --- api-reference/beta/api/usersettings-list-windows.md | 1 - 1 file changed, 1 deletion(-) diff --git a/api-reference/beta/api/usersettings-list-windows.md b/api-reference/beta/api/usersettings-list-windows.md index 6fae42d7451..5c7551ec0d1 100644 --- a/api-reference/beta/api/usersettings-list-windows.md +++ b/api-reference/beta/api/usersettings-list-windows.md @@ -36,7 +36,6 @@ Choose the permission or permissions marked as least privileged for this API. Us Get a list of Windows settings for the signed-in user. -````http ``` http GET /me/settings/windows ```` From a992116f2eb2206f773cd19c3ac0a32b579558ec Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Mon, 12 Feb 2024 14:09:14 -0700 Subject: [PATCH 04/54] Addressed review comments --- .../beta/api/usersettings-list-windows.md | 97 +++++++++++-------- api-reference/beta/api/windowssetting-get.md | 18 ++-- .../beta/api/windowssetting-list-instances.md | 16 +-- .../beta/api/windowssettinginstance-get.md | 12 +-- .../beta/resources/windowssetting.md | 2 +- 5 files changed, 78 insertions(+), 67 deletions(-) diff --git a/api-reference/beta/api/usersettings-list-windows.md b/api-reference/beta/api/usersettings-list-windows.md index 5c7551ec0d1..3fbcc9436cd 100644 --- a/api-reference/beta/api/usersettings-list-windows.md +++ b/api-reference/beta/api/usersettings-list-windows.md @@ -42,13 +42,20 @@ GET /me/settings/windows ## Optional query parameters -This method supports $filter OData query parameter to help customize the response. The result can be filtered by `windowsDeviceId` and `settingType` properties. For general information, see [OData query parameters](/graph/query-parameters). +This method supports `$filter` OData query parameter to help customize the response. The result can be filtered by `windowsDeviceId` and `settingType` properties. For general information, see [OData query parameters](/graph/query-parameters). + +1. **`windowsDeviceId`**: A string value representing the unique identifier of a Windows device. This identifier can be found in the response body. By filtering with `WindowsDeviceId`, a filtered list of settings specific to that device can be retrieved. Only equality (`eq`) comparison is supported for this parameter. + +2. **`settingType`**: An enumeration with valid values: `roaming` and `backup`. The `settingType` parameter allows narrowing down the results to settings related to either roaming or backup. Only equality (`eq`) comparison is supported for this parameter. For more information on settingType, see [windowssettingtype](../resources/enums.md#windowssettingtype-values). + +Please refer to the [examples](./usersettings-list-windows.md#examples) section below for more information on how to use these query parameters. ## Request headers | Name | Description | | :------------ | :-------------------------------------------------------------------------------------------------------- | | Authorization | Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts). | +| Prefer |Optional. The API supports the *odata.maxpagesize* parameter through this header for pagination purposes. The minimum and maximum valid values for *odata.maxpagesize* are **1** and **200** respectively. If no value is passed, the default value is **110**.| ## Request body @@ -58,6 +65,9 @@ Don't supply a request body for this method. If successful, this method returns a `200 OK` response code and a collection of [windowsSetting](../resources/windowssetting.md) objects in the response body. +If the response contains more than one page of data, the response body will contain a `@odata.nextLink` property. This property will contain a URL that can be used to request the next page of data. The URL should be used without any modification. + + ## Examples ### Request @@ -96,36 +106,37 @@ Content-Type: application/json { "@odata.type": "#microsoft.graph.windowsSetting", "id": "default$windows.data.fileexplorerclassic.searchsettings", - "windowsDeviceId": "String", - "settingType": "String", - "payloadType": "String", + "windowsDeviceId": "c9e0f7d8-2b1a-4f6e-9b7c-8e3a1a3e5b0d", + "settingType": "backup", + "payloadType": "windows.data.fileexplorerclassic.searchsettings", "instances": [ { "id": "9715f1d9-49d1-4b94-041b-443ac419d417", - "payload": "String (Base64 encoded JSON)", - "lastModifiedDateTime": "String (timestamp)", - "createdDateTime": "String (timestamp)", - "expirationDateTime": "String (timestamp)" + "payload": "VGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUh", + "lastModifiedDateTime": "2024-10-31T23:30:41Z", + "createdDateTime": "2024-02-12T19:34:35.223Z", + "expirationDateTime": "2034-02-09T19:34:33.771Z" } ] }, { "@odata.type": "#microsoft.graph.windowsSetting", "id": "default$windows.data.input.devices.pensyncedsettings", - "windowsDeviceId": "String", - "settingType": "String", - "payloadType": "String", + "windowsDeviceId": "a4b9d6e7-8f3c-4d2a-b1e0-6c5f0e9a7d8b", + "settingType": "backup", + "payloadType": "windows.data.input.devices.pensyncedsettings", "instances": [ { "id": "666dcb9b-49d1-4b94-041b-443ac419d417", - "payload": "String (Base64 encoded JSON)", - "lastModifiedDateTime": "String (timestamp)", - "createdDateTime": "String (timestamp)", - "expirationDateTime": "String (timestamp)" + "payload": "VGhpcyBpcyBhbm90aGVyIGp1c3QgYW4gZXhhbXBsZSE=", + "lastModifiedDateTime": "2024-10-31T23:30:41Z", + "createdDateTime": "2024-02-12T19:34:35.223Z", + "expirationDateTime": "2034-02-09T19:34:33.771Z" } ] } - ] + ], + "@odata.nextLink": "https://graph.microsoft.com/beta/me/settings/windows?$skiptoken=eyJzZXRhZyI6ImJmY2I2ZjQwLWM5ZGQtMTFlZS05MTE3LTAxMDIwMzA1MDcwZCIsImlldGFnIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwiZW5kRVRhZyI6IjEwMDJkOGYwLWM2NTItMTRkYy05MTE3LTAxMDIwMzA1MDcwZCIsImV0YWciOiJjMDMzZjUxMC1jOWRkLTExZWUtOTExNy0wMTAyMDMwNTA3MGQiLCJsdHNsIjoiYzAzM2Y1MTAtYzlkZC0xMWVlLTkxMTctMDEwMjAzMDUwNzBkIiwibmV4dCI6dHJ1ZX0%3d" } ``` ### Request @@ -165,14 +176,14 @@ Content-Type: application/json "@odata.type": "#microsoft.graph.windowsSetting", "id": "default$windows.data.fileexplorerclassic.shellstatesettings", "settingType": "roaming", - "payloadType": "String", + "payloadType": "windows.data.fileexplorerclassic.shellstatesettings", "instances": [ { "id": "0b3af867-49d1-4b94-041b-443ac419d417", - "payload": "String (Base64 encoded JSON)", - "lastModifiedDateTime": "String (timestamp)", - "createdDateTime": "String (timestamp)", - "expirationDateTime": "String (timestamp)" + "payload": "VGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUh", + "lastModifiedDateTime": "2024-10-31T23:30:41Z", + "createdDateTime": "2024-02-12T19:34:35.223Z", + "expirationDateTime": "2034-02-09T19:34:33.771Z" } ] }, @@ -180,14 +191,14 @@ Content-Type: application/json "@odata.type": "#microsoft.graph.windowsSetting", "id": "default$windows.data.fileexplorerclassic.cabinetstatesettings", "settingType": "roaming", - "payloadType": "String", + "payloadType": "windows.data.fileexplorerclassic.cabinetstatesettings", "instances": [ { "id": "5038fa1b-49d1-4b94-041b-443ac419d417", - "payload": "String (Base64 encoded JSON)", - "lastModifiedDateTime": "String (timestamp)", - "createdDateTime": "String (timestamp)", - "expirationDateTime": "String (timestamp)" + "payload": "VGhpcyBpcyBhbm90aGVyIGp1c3QgYW4gZXhhbXBsZSE=", + "lastModifiedDateTime": "2024-10-31T23:30:41Z", + "createdDateTime": "2024-02-12T19:34:35.223Z", + "expirationDateTime": "2034-02-09T19:34:33.771Z" } ] } @@ -230,32 +241,32 @@ Content-Type: application/json { "@odata.type": "#microsoft.graph.windowsSetting", "id": "{67585f9f-ee4b-4dd8-808e-d88375d66ef7}$windows.data.apps.devicemetadata", - "windowsDeviceId": "String", + "windowsDeviceId": "67585f9f-ee4b-4dd8-808e-d88375d66ef7", "settingType": "backup", - "payloadType": "String", + "payloadType": "windows.data.apps.devicemetadata", "instances": [ { "id": "14b50191-10e5-4da5-9099-8c909b8458bd", - "payload": "String (Base64 encoded JSON)", - "lastModifiedDateTime": "String (timestamp)", - "createdDateTime": "String (timestamp)", - "expirationDateTime": "String (timestamp)" + "payload": "VGhpcyBpcyBhbm90aGVyIGp1c3QgYW4gZXhhbXBsZSE=", + "lastModifiedDateTime": "2024-10-31T23:30:41Z", + "createdDateTime": "2024-02-12T19:34:35.223Z", + "expirationDateTime": "2034-02-09T19:34:33.771Z" } ] }, { "@odata.type": "#microsoft.graph.windowsSetting", "id": "{55f26da7-5824-4937-9028-9bba274f049f}$windows.data.apps.devicemetadata", - "windowsDeviceId": "String", + "windowsDeviceId": "55f26da7-5824-4937-9028-9bba274f049f", "settingType": "backup", - "payloadType": "String", + "payloadType": "windows.data.apps.devicemetadata", "instances": [ { "id": "da2f0307-2a8d-4242-846f-56abd95f7213", - "payload": "String (Base64 encoded JSON)", - "lastModifiedDateTime": "String (timestamp)", - "createdDateTime": "String (timestamp)", - "expirationDateTime": "String (timestamp)" + "payload": "VGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUh", + "lastModifiedDateTime": "2024-10-31T23:30:41Z", + "createdDateTime": "2024-02-12T19:34:35.223Z", + "expirationDateTime": "2034-02-09T19:34:33.771Z" } ] } @@ -300,14 +311,14 @@ Content-Type: application/json "id": "{67585f9f-ee4b-4dd8-808e-d88375d66ef7}$windows.data.apps.devicemetadata", "windowsDeviceId": "67585f9f-ee4b-4dd8-808e-d88375d66ef7", "settingType": "backup", - "payloadType": "String", + "payloadType": "windows.data.apps.devicemetadata", "instances": [ { "id": "14b50191-10e5-4da5-9099-8c909b8458bd", - "payload": "String (Base64 encoded JSON)", - "lastModifiedDateTime": "String (timestamp)", - "createdDateTime": "String (timestamp)", - "expirationDateTime": "String (timestamp)" + "payload": "VGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUh", + "lastModifiedDateTime": "2024-10-31T23:30:41Z", + "createdDateTime": "2024-02-12T19:34:35.223Z", + "expirationDateTime": "2034-02-09T19:34:33.771Z" } ] } diff --git a/api-reference/beta/api/windowssetting-get.md b/api-reference/beta/api/windowssetting-get.md index 55df1aca41f..ca1c6d1d067 100644 --- a/api-reference/beta/api/windowssetting-get.md +++ b/api-reference/beta/api/windowssetting-get.md @@ -86,17 +86,17 @@ Content-Type: application/json { "@odata.type": "#microsoft.graph.windowsSetting", - "id": "default$windows.data.fileexplorerclassic.searchsettings", - "windowsDeviceId": "String", - "settingType": "String", - "payloadType": "String", + "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": "9715f1d9-49d1-4b94-041b-443ac419d417", - "payload": "String (Base64 encoded JSON)", - "lastModifiedDateTime": "String (timestamp)", - "createdDateTime": "String (timestamp)", - "expirationDateTime": "String (timestamp)" + "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" } ] } diff --git a/api-reference/beta/api/windowssetting-list-instances.md b/api-reference/beta/api/windowssetting-list-instances.md index 52152644ef5..d7e9b1b69b3 100644 --- a/api-reference/beta/api/windowssetting-list-instances.md +++ b/api-reference/beta/api/windowssetting-list-instances.md @@ -89,18 +89,18 @@ Content-Type: application/json { "@odata.type": "#microsoft.graph.windowsSettingInstance", "id": "9715f1d9-49d1-4b94-041b-443ac419d417", - "payload": "String (Base64 encoded JSON)", - "lastModifiedDateTime": "String (timestamp)", - "createdDateTime": "String (timestamp)", - "expirationDateTime": "String (timestamp)" + "payload": "VGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUh", + "lastModifiedDateTime": "2024-10-31T23:30:41Z", + "createdDateTime": "2024-02-12T19:34:35.223Z", + "expirationDateTime": "2034-02-09T19:34:33.771Z" }, { "@odata.type": "#microsoft.graph.windowsSettingInstance", "id": "6984732f-86b0-8e31-dc02-37fce0df6d61", - "payload": "String (Base64 encoded JSON)", - "lastModifiedDateTime": "String (timestamp)", - "createdDateTime": "String (timestamp)", - "expirationDateTime": "String (timestamp)" + "payload": "VGhpcyBpcyBhbm90aGVyIGp1c3QgYW4gZXhhbXBsZSE=", + "lastModifiedDateTime": "2024-10-31T23:30:41Z", + "createdDateTime": "2024-02-12T19:34:35.223Z", + "expirationDateTime": "2034-02-09T19:34:33.771Z" } ] } diff --git a/api-reference/beta/api/windowssettinginstance-get.md b/api-reference/beta/api/windowssettinginstance-get.md index f71bd994b98..fee0389c4ec 100644 --- a/api-reference/beta/api/windowssettinginstance-get.md +++ b/api-reference/beta/api/windowssettinginstance-get.md @@ -92,11 +92,11 @@ HTTP/1.1 200 OK Content-Type: application/json { - "@odata.type": "#microsoft.graph.windowsSettingInstance", - "id": "9715f1d9-49d1-4b94-041b-443ac419d417", - "payload": "String (Base64 encoded JSON)", - "lastModifiedDateTime": "String (timestamp)", - "createdDateTime": "String (timestamp)", - "expirationDateTime": "String (timestamp)" + "@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" } ``` diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index f5f7baff56d..da3f193ad86 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -41,7 +41,7 @@ Inherits from [entity](../resources/entity.md). |:---|:---|:---| |id|String|The unique identifier of the object.| |payloadType|String|The type of setting payloads contained in the *instances* navigation property.| -|settingType|windowsSettingType|The type of setting. Possible values are: `roaming`, `backup`, `unknownFutureValue`. `unknownFutureValue` is a future placeholder and not a real settingType.| +|settingType|windowsSettingType|The type of setting. Possible values are: `roaming`, `backup`, `unknownFutureValue`. *unknownFutureValue* is a future placeholder and not a real settingType.| |windowsDeviceId|String|A unique identifier for the device the setting belongs to if it is of the settingType `backup`.| ## Relationships From 1eabaac59e39465fcd64380a38b20c4f6e9f253e Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Mon, 12 Feb 2024 18:22:37 -0700 Subject: [PATCH 05/54] Added warning for payload structure --- api-reference/beta/resources/windowssettinginstance.md | 1 + 1 file changed, 1 insertion(+) diff --git a/api-reference/beta/resources/windowssettinginstance.md b/api-reference/beta/resources/windowssettinginstance.md index 2b574e76dd2..8a2b6b0b969 100644 --- a/api-reference/beta/resources/windowssettinginstance.md +++ b/api-reference/beta/resources/windowssettinginstance.md @@ -19,6 +19,7 @@ A **windowsSettingInstance** belongs to a [**windowsSetting**](../resources/wind The *payload* property of a **windowsSettingInstance** contains the actual setting value. The *payload* is a string in base64 encoded format. The *payloadType* property of the [**windowsSetting**](../resources/windowssetting.md) object indicates the type of the setting value. The *payload* when decoded is a JSON object which differs from setting to setting and is specific to the *payloadType*. +>Warning: The structure of the JSON object in the *payload* for a given *payloadType* is not guraranteed to be fixed and may change in the future. Inherits from [entity](../resources/entity.md). From fd40475247c6a316d6766a0716fd50ba01e8045b Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Wed, 14 Feb 2024 03:36:46 -0700 Subject: [PATCH 06/54] Added docs for deviceProfile --- .../beta/resources/windowssetting.md | 111 ++++++++++++++++-- .../beta/resources/windowssettinginstance.md | 2 - 2 files changed, 103 insertions(+), 10 deletions(-) diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index da3f193ad86..99925547b5d 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -15,18 +15,12 @@ Namespace: microsoft.graph **windowsSetting** represents settings from Windows operating system that are stored in the cloud for a given user. +>Warning: The structure of the id of a **windowsSetting** is not guranateed and the caller should not take any dependency on it. The id should be treated as an opaque string. + There are two types of **windowsSetting**: `roaming` and `backup`. More information about the types of **windowsSetting** can be found in the [windowsSettingType](enums.md) enum. A **windowsSetting** of type `backup` has a *windowsDeviceId* property that links the setting to a specific device. When getting a list of **windowsSetting** objects, the result can be filtered by *windowsDeviceId* and *settingType* properties. For more information, see [List Windows settings stored in cloud](../api/usersettings-list-windows.md). -The *windowsDeviceId* is a unique identifier for a device. The device that a **windowsSetting** of type `backup` is associated with is indicated by the *windowsDeviceId*. However, it is a guid and does not help to identify the actual device by a friendly property like device name. To identify the device that the *windowsDeviceId* refers to, the following steps can be followed: - -- Use the [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API to list all the settings for the user. -- Find the id of the device profile setting. -- Use the [settings API](../api/windowssetting-get.md) to fetch the device profile setting with the id. -- The *instances* navigation property of the device profile setting will contain all the device profile setting values. -- Decode the *payload* of each setting value to find the *windowsDeviceId*, corresponding device name, and other details. - Inherits from [entity](../resources/entity.md). ## Methods @@ -44,6 +38,107 @@ Inherits from [entity](../resources/entity.md). |settingType|windowsSettingType|The type of setting. Possible values are: `roaming`, `backup`, `unknownFutureValue`. *unknownFutureValue* is a future placeholder and not a real settingType.| |windowsDeviceId|String|A unique identifier for the device the setting belongs to if it is of the settingType `backup`.| +## About the *payloadType* property +### Introduction +The payloadType defines the structure of a [windowsSettingInstance](./windowssettinginstance.md) payload. There are numerous payloadTypes in Windows which represent distinct setting structures used by different experiences in the operating system. As Windows evolves, more payloadTypes are created and onboarded to the cloud. + +Following is an example of a windowsSetting from the API. + +```json +{ + "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" + } + ] +} +``` +The *payload* is a base64 encoded JSON string, which has the properties of given *payloadType* `windows.data.fileexplorerclassic.advancedsettings`. The decoded structure of the *payload* is shown below for example. + +```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 +} +``` +### Notable PayloadTypes + +There are several notable **payloadTypes** available in Windows that represent distinct setting structures used by distinguished features and experiences in the operating system. To learn more about them, see the list below. + +#### **Device Profile**: +This payloadType represents settings related to device profiles. A device profile contains additional information about the device on which the Windows operation system is hosted. If a user has multiple Windows devices, then multiple device profile **windowsSettings** will exist for the user. An example of a device profile **windowsSetting** is, + +```json +{ + "id": "{95b3a2c8-482a-4a06-7b3a-da2a5a4b2c0f}$windows.data.platform.backuprestore.deviceprofile$deviceprofiles", + "settingType": "backup", + "payloadType": "windows.data.platform.backuprestore.deviceprofile", + "windowsDeviceId": "95b3a2c8-482a-4a06-7b3a-da2a5a4b2c0f", + "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" + } + ] +} +``` +The payload after decoding is given below for example. + +```json +{ + "profileId": "{95b3a2c8-482a-4a06-7b3a-da2a5a4b2c0f}", + "deviceDisplayName": "EXAMPLEUSERDESKTOP", + "createdBy": "windows", + "sourceProfileId": "", + "createdTime": 1664680589, + "modifiedTime": 1698795040, + "isActive": true, + "lastFullBackupCompletedTime": 1698332137, + "osVersion": "18045.3750.vb_release" +} +``` + +Two notable properties in the decoded payload are *deviceDisplayName* and *profileId*. The *deviceDisplayName* is the name of the device and the *profileId* is the unique identifier of it. + +The significance of the *profileId* is that it correlates with the *windowsDeviceId* property of any **windowsSetting** of type `backup`. This helps to identify the device that a **windowsSetting** of type `backup` is associated with. + +Following are the step by step instructions on how to find the corresponding device for a given *windowsDeviceId*: + +- Use the [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API to list all the settings for the user. +- Find the device profile related settings. As shown in the example above, the *payloadType* property of such settings will be `windows.data.platform.backuprestore.deviceprofile`. +- Decode the *payload* of each setting instance to get the *profileIds* and corresponding *deviceDisplayNames*. +- Find the *profileId* matching with the *windowsDeviceId* of the **windowsSetting** of type `backup` to identify the corresponding device. + +#### **Service Driven Onboarding**: +This payloadType represents settings related to service-driven onboarding. + +**TODO** + + + ## Relationships |Relationship|Type|Description| |:---|:---|:---| diff --git a/api-reference/beta/resources/windowssettinginstance.md b/api-reference/beta/resources/windowssettinginstance.md index 8a2b6b0b969..f93c249b4dd 100644 --- a/api-reference/beta/resources/windowssettinginstance.md +++ b/api-reference/beta/resources/windowssettinginstance.md @@ -19,8 +19,6 @@ A **windowsSettingInstance** belongs to a [**windowsSetting**](../resources/wind The *payload* property of a **windowsSettingInstance** contains the actual setting value. The *payload* is a string in base64 encoded format. The *payloadType* property of the [**windowsSetting**](../resources/windowssetting.md) object indicates the type of the setting value. The *payload* when decoded is a JSON object which differs from setting to setting and is specific to the *payloadType*. ->Warning: The structure of the JSON object in the *payload* for a given *payloadType* is not guraranteed to be fixed and may change in the future. - Inherits from [entity](../resources/entity.md). ## Methods From d006cc1679d541971de1caef8e27d136fffcebe5 Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Wed, 14 Feb 2024 14:14:40 -0700 Subject: [PATCH 07/54] Addressed additional review comments. --- api-reference/beta/resources/enums.md | 4 ++-- api-reference/beta/resources/windowssetting.md | 15 +++++++-------- .../beta/resources/windowssettinginstance.md | 10 +++++----- 3 files changed, 14 insertions(+), 15 deletions(-) diff --git a/api-reference/beta/resources/enums.md b/api-reference/beta/resources/enums.md index 1105aefde16..4737caf2d9f 100644 --- a/api-reference/beta/resources/enums.md +++ b/api-reference/beta/resources/enums.md @@ -1819,8 +1819,8 @@ Possible types of Windows settings. | Member | Value | Description | | :----------------- | :---- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| roaming | 0 | Windows setting is associated with a user account. It is consistent across all devices and any changes to the setting value are synced or applied to all Windows devices that the user owns. | -| backup | 1 | Windows setting is linked to a specific device of a user. This type of setting is not synced across all devices that the user owns. In other words, this type of setting is unique to each device. | +| roaming | 0 | Windows setting is associated with a user's account. It is consistent across all devices and any changes to the setting value are synced or applied to all Windows devices that the user owns. | +| backup | 1 | Windows setting does not roam or sync accross devices. This type of setting is used in device backup and restore scenarios.| | unknownFutureValue | 2 | This is not a valid setting type. It is only a placeholder for any possible setting type that may be added in the future. | ### workforceIntegrationEncryptionProtocol values diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index 99925547b5d..87397b15078 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -17,7 +17,7 @@ Namespace: microsoft.graph >Warning: The structure of the id of a **windowsSetting** is not guranateed and the caller should not take any dependency on it. The id should be treated as an opaque string. -There are two types of **windowsSetting**: `roaming` and `backup`. More information about the types of **windowsSetting** can be found in the [windowsSettingType](enums.md) enum. A **windowsSetting** of type `backup` has a *windowsDeviceId* property that links the setting to a specific device. +There are two types of **windowsSetting**: `roaming` and `backup`. More information about the types of **windowsSetting** can be found in the [windowsSettingType](enums.md#windowssettingtype-values) enum. A **windowsSetting** of type `backup` may have a *windowsDeviceId* property that links the setting to a specific device. When getting a list of **windowsSetting** objects, the result can be filtered by *windowsDeviceId* and *settingType* properties. For more information, see [List Windows settings stored in cloud](../api/usersettings-list-windows.md). @@ -35,8 +35,8 @@ Inherits from [entity](../resources/entity.md). |:---|:---|:---| |id|String|The unique identifier of the object.| |payloadType|String|The type of setting payloads contained in the *instances* navigation property.| -|settingType|windowsSettingType|The type of setting. Possible values are: `roaming`, `backup`, `unknownFutureValue`. *unknownFutureValue* is a future placeholder and not a real settingType.| -|windowsDeviceId|String|A unique identifier for the device the setting belongs to if it is of the settingType `backup`.| +|settingType|windowsSettingType|The type of setting. Possible values are: `roaming`, `backup`, `unknownFutureValue`.
Note, *unknownFutureValue* is a future placeholder and not a real settingType.| +|windowsDeviceId|String|A unique identifier for the device the setting may belong to if it is of the settingType `backup`.| ## About the *payloadType* property ### Introduction @@ -86,14 +86,13 @@ The *payload* is a base64 encoded JSON string, which has the properties of given There are several notable **payloadTypes** available in Windows that represent distinct setting structures used by distinguished features and experiences in the operating system. To learn more about them, see the list below. #### **Device Profile**: -This payloadType represents settings related to device profiles. A device profile contains additional information about the device on which the Windows operation system is hosted. If a user has multiple Windows devices, then multiple device profile **windowsSettings** will exist for the user. An example of a device profile **windowsSetting** is, +This payloadType represents settings related to device profiles. A device profile contains additional information about the device on which the Windows operation system is hosted. If a user has multiple Windows devices, then multiple instances will exist for the user under the device profile **windowsSetting**. An example of a device profile **windowsSetting** is, ```json { - "id": "{95b3a2c8-482a-4a06-7b3a-da2a5a4b2c0f}$windows.data.platform.backuprestore.deviceprofile$deviceprofiles", + "id": "default$windows.data.platform.backuprestore.deviceprofile$deviceprofiles", "settingType": "backup", "payloadType": "windows.data.platform.backuprestore.deviceprofile", - "windowsDeviceId": "95b3a2c8-482a-4a06-7b3a-da2a5a4b2c0f", "instances": [ { "id": "73b1a0b8-262a-4804-592a-b82a3a2a0c0d", @@ -105,7 +104,7 @@ This payloadType represents settings related to device profiles. A device profil ] } ``` -The payload after decoding is given below for example. +The payload after decoding is shown below for example. ```json { @@ -128,7 +127,7 @@ The significance of the *profileId* is that it correlates with the *windowsDevic Following are the step by step instructions on how to find the corresponding device for a given *windowsDeviceId*: - Use the [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API to list all the settings for the user. -- Find the device profile related settings. As shown in the example above, the *payloadType* property of such settings will be `windows.data.platform.backuprestore.deviceprofile`. +- Find the device profile related setting. As shown in the example above, the *payloadType* property of device profile setting will be `windows.data.platform.backuprestore.deviceprofile`. - Decode the *payload* of each setting instance to get the *profileIds* and corresponding *deviceDisplayNames*. - Find the *profileId* matching with the *windowsDeviceId* of the **windowsSetting** of type `backup` to identify the corresponding device. diff --git a/api-reference/beta/resources/windowssettinginstance.md b/api-reference/beta/resources/windowssettinginstance.md index f93c249b4dd..6290116c87f 100644 --- a/api-reference/beta/resources/windowssettinginstance.md +++ b/api-reference/beta/resources/windowssettinginstance.md @@ -52,11 +52,11 @@ The following JSON representation shows the resource type. ``` json { "@odata.type": "#microsoft.graph.windowsSettingInstance", - "id": "String (identifier)", - "payload": "String (Base64 encoded JSON)", - "lastModifiedDateTime": "String (timestamp)", - "createdDateTime": "String (timestamp)", - "expirationDateTime": "String (timestamp)" + "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" } ``` From fca760b365424f4cad959236b298888b752a7d37 Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Thu, 15 Feb 2024 16:30:28 -0700 Subject: [PATCH 08/54] Update windowssetting.md --- .../beta/resources/windowssetting.md | 60 ++++++++++--------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index 87397b15078..39358371a5b 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -40,9 +40,9 @@ Inherits from [entity](../resources/entity.md). ## About the *payloadType* property ### Introduction -The payloadType defines the structure of a [windowsSettingInstance](./windowssettinginstance.md) payload. There are numerous payloadTypes in Windows which represent distinct setting structures used by different experiences in the operating system. As Windows evolves, more payloadTypes are created and onboarded to the cloud. +The *payloadType* defines the structure of a [windowsSettingInstance](./windowssettinginstance.md) payload. There are numerous payloadTypes in Windows which represent distinct setting structures used by different experiences in the operating system. As Windows evolves, more payloadTypes are created and onboarded to the cloud. Querying the API and exploring the settings available is the best way to learn about the various payloadTypes, but users and admins have control over which settings are uploaded to the cloud and most components do not upload default settings that the user has not customized. -Following is an example of a windowsSetting from the API. +Following is an example of a settingsInstance from the API. ```json { @@ -60,8 +60,10 @@ Following is an example of a windowsSetting from the API. ] } ``` -The *payload* is a base64 encoded JSON string, which has the properties of given *payloadType* `windows.data.fileexplorerclassic.advancedsettings`. The decoded structure of the *payload* is shown below for example. +In this example, the payloadType `windows.data.fileexplorerclassic.advancedsettings` represents some of the settings that the File Explorer backs up to the cloud. The base64 payload can be decoded to a UTF-8 string to see the JSON representation of this object. + +**Payload decoded:** ```json { "migratedFromSSF": false, @@ -81,12 +83,20 @@ The *payload* is a base64 encoded JSON string, which has the properties of given "showCompColor": false } ``` -### Notable PayloadTypes -There are several notable **payloadTypes** available in Windows that represent distinct setting structures used by distinguished features and experiences in the operating system. To learn more about them, see the list below. +It is common for the properties in the object to be a subset of those available in the component’s user experience as component owners decide which settings provide the most value when uploaded to the cloud. + +### PayloadTypes of particular interest + +Some payloadTypes have a special role in the Windows settings backup process. + +#### windows.data.platform.backuprestore.deviceprofile +Rather than being a setting the user has applied, this type records information about devices that have opted into settings backup features. Two properties in this object are useful for understanding the rest of the settings: deviceDisplayName and profileId. + +- *deviceDisplayName* is the name of the computer which can be seen on the Windows settings system page. +- *profileId* is an identifier used to link WindowsSettings items to the device that uploaded them. This property corresponds to **windowsSetting.windowsDeviceId** and can be used as a filter to get settings for a specific device from [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API. -#### **Device Profile**: -This payloadType represents settings related to device profiles. A device profile contains additional information about the device on which the Windows operation system is hosted. If a user has multiple Windows devices, then multiple instances will exist for the user under the device profile **windowsSetting**. An example of a device profile **windowsSetting** is, +Following is an example of this setting. ```json { @@ -104,7 +114,7 @@ This payloadType represents settings related to device profiles. A device profil ] } ``` -The payload after decoding is shown below for example. +**Payload decoded:** ```json { @@ -120,22 +130,9 @@ The payload after decoding is shown below for example. } ``` -Two notable properties in the decoded payload are *deviceDisplayName* and *profileId*. The *deviceDisplayName* is the name of the device and the *profileId* is the unique identifier of it. - -The significance of the *profileId* is that it correlates with the *windowsDeviceId* property of any **windowsSetting** of type `backup`. This helps to identify the device that a **windowsSetting** of type `backup` is associated with. - -Following are the step by step instructions on how to find the corresponding device for a given *windowsDeviceId*: - -- Use the [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API to list all the settings for the user. -- Find the device profile related setting. As shown in the example above, the *payloadType* property of device profile setting will be `windows.data.platform.backuprestore.deviceprofile`. -- Decode the *payload* of each setting instance to get the *profileIds* and corresponding *deviceDisplayNames*. -- Find the *profileId* matching with the *windowsDeviceId* of the **windowsSetting** of type `backup` to identify the corresponding device. - -#### **Service Driven Onboarding**: -This payloadType represents settings related to service-driven onboarding. - -**TODO** +#### windows.data.platform.settingsbackup.backupunitstore +Backupunitstore payloadType settings are unique in that the actual settings value is a blob in the data property. This is because backupunitstore settings are collected directly from the Windows registry, on disk files, or other at rest locations throughout Windows. These settings were not designed to be interoperable with experiences besides the components that created them, but they are included in this API for the sake of completeness. ## Relationships @@ -156,10 +153,19 @@ The following JSON representation shows the resource type. ``` json { "@odata.type": "#microsoft.graph.windowsSetting", - "id": "String (identifier)", - "windowsDeviceId": "String", - "settingType": "String", - "payloadType": "String" + "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" + } + ] } ``` From 2f6bfc21dc43ff9e03061364d30a222e462e7199 Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Thu, 15 Feb 2024 17:25:42 -0700 Subject: [PATCH 09/54] Address review comments on windowsSettings.md --- api-reference/beta/resources/windowssetting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index 39358371a5b..9ead1ff88f7 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -93,8 +93,8 @@ Some payloadTypes have a special role in the Windows settings backup process. #### windows.data.platform.backuprestore.deviceprofile Rather than being a setting the user has applied, this type records information about devices that have opted into settings backup features. Two properties in this object are useful for understanding the rest of the settings: deviceDisplayName and profileId. -- *deviceDisplayName* is the name of the computer which can be seen on the Windows settings system page. -- *profileId* is an identifier used to link WindowsSettings items to the device that uploaded them. This property corresponds to **windowsSetting.windowsDeviceId** and can be used as a filter to get settings for a specific device from [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API. +- *deviceDisplayName* is the name of the computer which can be seen in Windows system settings at "**Start** > **Settings** > **System**". +- *profileId* is an identifier used to link **WindowsSettings** items to the device that uploaded them. This property corresponds to **windowsSetting.windowsDeviceId** and can be used as a filter to get settings for a specific device from [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API. Following is an example of this setting. @@ -132,7 +132,7 @@ Following is an example of this setting. #### windows.data.platform.settingsbackup.backupunitstore -Backupunitstore payloadType settings are unique in that the actual settings value is a blob in the data property. This is because backupunitstore settings are collected directly from the Windows registry, on disk files, or other at rest locations throughout Windows. These settings were not designed to be interoperable with experiences besides the components that created them, but they are included in this API for the sake of completeness. +The **backupUnitStore** payloadType settings are unique in that the actual settings value is a **blob** in the data property. This is because **backupUnitStore** settings are collected directly from the Windows registry, on disk files, or other at rest locations throughout Windows. These settings were not designed to be interoperable with experiences besides the components that created them, but they are included in this API for the sake of completeness. ## Relationships From 322dcc0511cfbe8dcfe25623c245724716d8301f Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Thu, 15 Feb 2024 17:42:28 -0700 Subject: [PATCH 10/54] Update windowssetting.md --- api-reference/beta/resources/windowssetting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index 9ead1ff88f7..f27e57432ae 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -132,7 +132,7 @@ Following is an example of this setting. #### windows.data.platform.settingsbackup.backupunitstore -The **backupUnitStore** payloadType settings are unique in that the actual settings value is a **blob** in the data property. This is because **backupUnitStore** settings are collected directly from the Windows registry, on disk files, or other at rest locations throughout Windows. These settings were not designed to be interoperable with experiences besides the components that created them, but they are included in this API for the sake of completeness. +The **backupUnitStore** payloadType settings are unique in that the actual settings value is a **blob** in the data property. This is because **backupUnitStore** settings are collected directly from the Windows registry, on disk files, or other at rest locations throughout Windows. These settings were not designed to be interoperable with experiences besides the components that created them, but they have been included in this API for comprehensive coverage of all Windows settings in the cloud. ## Relationships From e6698719aa2676827abb3d62279d8d4ce3bae4d1 Mon Sep 17 00:00:00 2001 From: MS-Arko <159182581+MS-Arko@users.noreply.github.com> Date: Mon, 26 Feb 2024 17:34:42 -0700 Subject: [PATCH 11/54] Update api-reference/beta/resources/windowssetting.md Co-authored-by: Daniela Bonilla Montero <92937694+Danielabom@users.noreply.github.com> --- api-reference/beta/resources/windowssetting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index f27e57432ae..df1c5108fbc 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -1,6 +1,6 @@ --- title: "windowsSetting resource type" -description: "windowsSetting represents settings from Windows operating system." +description: "Represents settings from the Windows operating system." author: "MS-Arko" ms.localizationpriority: medium ms.prod: "cross-device-experiences" From 816bf9c50cc8e70ded059292125238408ccead04 Mon Sep 17 00:00:00 2001 From: MS-Arko <159182581+MS-Arko@users.noreply.github.com> Date: Mon, 26 Feb 2024 17:35:57 -0700 Subject: [PATCH 12/54] Update api-reference/beta/resources/windowssetting.md Co-authored-by: Daniela Bonilla Montero <92937694+Danielabom@users.noreply.github.com> --- api-reference/beta/resources/windowssetting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index df1c5108fbc..f4acbb385d1 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -13,7 +13,7 @@ Namespace: microsoft.graph [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -**windowsSetting** represents settings from Windows operating system that are stored in the cloud for a given user. +Represents settings from the Windows operating system that are stored in the cloud for a given user. >Warning: The structure of the id of a **windowsSetting** is not guranateed and the caller should not take any dependency on it. The id should be treated as an opaque string. From b68199814413aeb2b1e9fafdf697859d06e4e544 Mon Sep 17 00:00:00 2001 From: MS-Arko <159182581+MS-Arko@users.noreply.github.com> Date: Mon, 26 Feb 2024 17:37:02 -0700 Subject: [PATCH 13/54] Update api-reference/beta/resources/windowssetting.md Co-authored-by: Daniela Bonilla Montero <92937694+Danielabom@users.noreply.github.com> --- api-reference/beta/resources/windowssetting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index f4acbb385d1..56b69332a8d 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -15,7 +15,7 @@ Namespace: microsoft.graph Represents settings from the Windows operating system that are stored in the cloud for a given user. ->Warning: The structure of the id of a **windowsSetting** is not guranateed and the caller should not take any dependency on it. The id should be treated as an opaque string. +>Warning: The structure of the ID of a **windowsSetting** is not guaranteed and the caller should not take any dependency on it. The ID should be treated as an opaque string. There are two types of **windowsSetting**: `roaming` and `backup`. More information about the types of **windowsSetting** can be found in the [windowsSettingType](enums.md#windowssettingtype-values) enum. A **windowsSetting** of type `backup` may have a *windowsDeviceId* property that links the setting to a specific device. From e722a042af499e83883125f1baaa94f8cbae4d51 Mon Sep 17 00:00:00 2001 From: MS-Arko <159182581+MS-Arko@users.noreply.github.com> Date: Mon, 26 Feb 2024 17:44:13 -0700 Subject: [PATCH 14/54] Update api-reference/beta/changelog/Microsoft.PDRS.json Co-authored-by: Daniela Bonilla Montero <92937694+Danielabom@users.noreply.github.com> --- api-reference/beta/changelog/Microsoft.PDRS.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/beta/changelog/Microsoft.PDRS.json b/api-reference/beta/changelog/Microsoft.PDRS.json index e53c87e83af..6842f30e199 100644 --- a/api-reference/beta/changelog/Microsoft.PDRS.json +++ b/api-reference/beta/changelog/Microsoft.PDRS.json @@ -23,7 +23,7 @@ "ApiChange": "Resource", "ChangedApiName": "windowsSetting", "ChangeType": "Addition", - "Description": "Added the [windowsSetting](https://learn.microsoft.com/en-us/graph/api/resources/windowsSetting?view=graph-rest-beta) resource.", + "Description": "Added the [windowsSetting](https://learn.microsoft.com/en-us/graph/api/resources/windowsSetting?view=graph-rest-beta) resource and its methods.", "Target": "windowsSetting" }, { From 7a00f331e3ff6d4af1b6493365f299daed7439c1 Mon Sep 17 00:00:00 2001 From: MS-Arko <159182581+MS-Arko@users.noreply.github.com> Date: Mon, 26 Feb 2024 17:45:27 -0700 Subject: [PATCH 15/54] Update api-reference/beta/resources/windowssetting.md Co-authored-by: Daniela Bonilla Montero <92937694+Danielabom@users.noreply.github.com> --- api-reference/beta/resources/windowssetting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index 56b69332a8d..e88a4ce57e4 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -17,7 +17,7 @@ Represents settings from the Windows operating system that are stored in the clo >Warning: The structure of the ID of a **windowsSetting** is not guaranteed and the caller should not take any dependency on it. The ID should be treated as an opaque string. -There are two types of **windowsSetting**: `roaming` and `backup`. More information about the types of **windowsSetting** can be found in the [windowsSettingType](enums.md#windowssettingtype-values) enum. A **windowsSetting** of type `backup` may have a *windowsDeviceId* property that links the setting to a specific device. +There are two types of **windowsSetting**: `roaming` and `backup`. More information, see [windowsSettingType](enums.md#windowssettingtype-values) enum. A **windowsSetting** of type `backup` may have a *windowsDeviceId* property that links the setting to a specific device. When getting a list of **windowsSetting** objects, the result can be filtered by *windowsDeviceId* and *settingType* properties. For more information, see [List Windows settings stored in cloud](../api/usersettings-list-windows.md). From 98b816db0b81c19e47095ac8131e64e0608deb11 Mon Sep 17 00:00:00 2001 From: MS-Arko <159182581+MS-Arko@users.noreply.github.com> Date: Mon, 26 Feb 2024 17:52:44 -0700 Subject: [PATCH 16/54] Update api-reference/beta/resources/windowssettinginstance.md Co-authored-by: Daniela Bonilla Montero <92937694+Danielabom@users.noreply.github.com> --- api-reference/beta/resources/windowssettinginstance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/beta/resources/windowssettinginstance.md b/api-reference/beta/resources/windowssettinginstance.md index 6290116c87f..252164d4033 100644 --- a/api-reference/beta/resources/windowssettinginstance.md +++ b/api-reference/beta/resources/windowssettinginstance.md @@ -1,6 +1,6 @@ --- title: "windowsSettingInstance resource type" -description: "windowsSettingInstance represents a setting instance from Windows operating system." +description: "Represents a setting instance from the Windows operating system." author: "MS-Arko" ms.localizationpriority: medium ms.prod: "cross-device-experiences" From abefff9691dfe0748984f3e7355c59fc7edec35b Mon Sep 17 00:00:00 2001 From: MS-Arko <159182581+MS-Arko@users.noreply.github.com> Date: Mon, 26 Feb 2024 17:53:21 -0700 Subject: [PATCH 17/54] Update api-reference/beta/resources/windowssettinginstance.md Co-authored-by: Daniela Bonilla Montero <92937694+Danielabom@users.noreply.github.com> --- api-reference/beta/resources/windowssettinginstance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/beta/resources/windowssettinginstance.md b/api-reference/beta/resources/windowssettinginstance.md index 252164d4033..8116bb50ec5 100644 --- a/api-reference/beta/resources/windowssettinginstance.md +++ b/api-reference/beta/resources/windowssettinginstance.md @@ -13,7 +13,7 @@ Namespace: microsoft.graph [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -**windowsSettingInstance** represents setting instances from Windows operating system that are stored in the cloud for a given user. +*"Represents a setting instance from the Windows operating system that is stored in the cloud for a given user. A **windowsSettingInstance** belongs to a [**windowsSetting**](../resources/windowssetting.md) and represents a specific setting value for a given user. From 9507af396447e24a58db5e7376fe9f995883a82e Mon Sep 17 00:00:00 2001 From: MS-Arko <159182581+MS-Arko@users.noreply.github.com> Date: Mon, 26 Feb 2024 18:10:55 -0700 Subject: [PATCH 18/54] Update api-reference/beta/resources/windowssettinginstance.md Co-authored-by: Daniela Bonilla Montero <92937694+Danielabom@users.noreply.github.com> --- api-reference/beta/resources/windowssettinginstance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/beta/resources/windowssettinginstance.md b/api-reference/beta/resources/windowssettinginstance.md index 8116bb50ec5..cc43fa10d13 100644 --- a/api-reference/beta/resources/windowssettinginstance.md +++ b/api-reference/beta/resources/windowssettinginstance.md @@ -24,7 +24,7 @@ Inherits from [entity](../resources/entity.md). ## Methods |Method|Return type|Description| |:---|:---|:---| -|[List windowsSettingInstance objects](../api/windowssetting-list-instances.md)|[windowsSettingInstance](../resources/windowssettinginstance.md) collection|Get a list of the [windowsSettingInstance](../resources/windowssettinginstance.md) objects and their properties.| +|[List windowsSettingInstance](../api/windowssetting-list-instances.md)|[windowsSettingInstance](../resources/windowssettinginstance.md) collection|Get a list of the [windowsSettingInstance](../resources/windowssettinginstance.md) objects and their properties.| |[Get windowsSettingInstance](../api/windowssettinginstance-get.md)|[windowsSettingInstance](../resources/windowssettinginstance.md)|Read the properties and relationships of a [windowsSettingInstance](../resources/windowssettinginstance.md) object.| ## Properties From 740fd8dd4e10107b173f1abb4cc0d45da7b57cf4 Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Mon, 26 Feb 2024 18:21:45 -0700 Subject: [PATCH 19/54] Addressed review comments --- .../beta/changelog/Microsoft.PDRS.json | 22 ++++++++++++++++--- api-reference/beta/resources/enums.md | 12 +++++----- .../beta/resources/windowssetting.md | 13 ++++++++--- .../beta/resources/windowssettinginstance.md | 4 ++-- api-reference/beta/toc.yml | 3 +++ 5 files changed, 39 insertions(+), 15 deletions(-) diff --git a/api-reference/beta/changelog/Microsoft.PDRS.json b/api-reference/beta/changelog/Microsoft.PDRS.json index e53c87e83af..002d3c5d8ae 100644 --- a/api-reference/beta/changelog/Microsoft.PDRS.json +++ b/api-reference/beta/changelog/Microsoft.PDRS.json @@ -12,10 +12,18 @@ }, { "Id": "af6ceee7-aa8a-4965-80fa-8fa9fd460ad2", - "ApiChange": "Resource", + "ApiChange": "Relationship", "ChangedApiName": "userSettings", - "ChangeType": "Modification", - "Description": "Modified the [userSettings](https://learn.microsoft.com/en-us/graph/api/resources/userSettings?view=graph-rest-beta) resource.", + "ChangeType": "Addition", + "Description": "Added the **windows** navigation property to the [userSettings](https://learn.microsoft.com/en-us/graph/api/resources/userSettings?view=graph-rest-beta) resource.", + "Target": "userSettings" + }, + { + "Id": "af6ceee7-aa8a-4965-80fa-8fa9fd460ad2", + "ApiChange": "Method", + "ChangedApiName": "GET", + "ChangeType": "Addition", + "Description": "Added the [list](https://learn.microsoft.com/en-us/graph/api/usersettings-list-windows?view=graph-rest-beta) operation to the [userSettings](https://learn.microsoft.com/en-us/graph/api/resources/userSettings?view=graph-rest-beta) resource.", "Target": "userSettings" }, { @@ -26,6 +34,14 @@ "Description": "Added the [windowsSetting](https://learn.microsoft.com/en-us/graph/api/resources/windowsSetting?view=graph-rest-beta) resource.", "Target": "windowsSetting" }, + { + "Id": "af6ceee7-aa8a-4965-80fa-8fa9fd460ad2", + "ApiChange": "Method", + "ChangedApiName": "GET", + "ChangeType": "Addition", + "Description": "Added the [list](https://learn.microsoft.com/en-us/graph/api/windowssetting-list-instances?view=graph-rest-beta) operation to the [windowsSetting](https://learn.microsoft.com/en-us/graph/api/resources/windowsSetting?view=graph-rest-beta) resource.", + "Target": "windowsSetting" + }, { "Id": "af6ceee7-aa8a-4965-80fa-8fa9fd460ad2", "ApiChange": "Resource", diff --git a/api-reference/beta/resources/enums.md b/api-reference/beta/resources/enums.md index 4737caf2d9f..0ff440085e7 100644 --- a/api-reference/beta/resources/enums.md +++ b/api-reference/beta/resources/enums.md @@ -1815,13 +1815,11 @@ Namespace: microsoft.graph ### windowsSettingType values -Possible types of Windows settings. - -| Member | Value | Description | -| :----------------- | :---- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| roaming | 0 | Windows setting is associated with a user's account. It is consistent across all devices and any changes to the setting value are synced or applied to all Windows devices that the user owns. | -| backup | 1 | Windows setting does not roam or sync accross devices. This type of setting is used in device backup and restore scenarios.| -| unknownFutureValue | 2 | This is not a valid setting type. It is only a placeholder for any possible setting type that may be added in the future. | +| Member | +| :----------------- | +| roaming | +| backup | +| unknownFutureValue | ### workforceIntegrationEncryptionProtocol values diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index f27e57432ae..5d5ea9225a9 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -17,7 +17,14 @@ Namespace: microsoft.graph >Warning: The structure of the id of a **windowsSetting** is not guranateed and the caller should not take any dependency on it. The id should be treated as an opaque string. -There are two types of **windowsSetting**: `roaming` and `backup`. More information about the types of **windowsSetting** can be found in the [windowsSettingType](enums.md#windowssettingtype-values) enum. A **windowsSetting** of type `backup` may have a *windowsDeviceId* property that links the setting to a specific device. +There are two types of **windowsSetting**: `roaming` and `backup`. The settingType property of a **windowsSetting** object indicates the type of the setting. + +| settingType | Description | +| :----------------- | :--------------------------------- | +| roaming | Windows setting is associated with a user's account. It is consistent across all devices and any changes to the setting value are synced or applied to all Windows devices that the user owns.| +| backup | Windows setting does not roam or sync accross devices. This type of setting is used in device backup and restore scenarios.| + + A **windowsSetting** of type `backup` may have a *windowsDeviceId* property that links the setting to a specific device. When getting a list of **windowsSetting** objects, the result can be filtered by *windowsDeviceId* and *settingType* properties. For more information, see [List Windows settings stored in cloud](../api/usersettings-list-windows.md). @@ -35,7 +42,7 @@ Inherits from [entity](../resources/entity.md). |:---|:---|:---| |id|String|The unique identifier of the object.| |payloadType|String|The type of setting payloads contained in the *instances* navigation property.| -|settingType|windowsSettingType|The type of setting. Possible values are: `roaming`, `backup`, `unknownFutureValue`.
Note, *unknownFutureValue* is a future placeholder and not a real settingType.| +|settingType|[windowsSettingType](enums.md#windowssettingtype-values)|The type of setting. Possible values are: `roaming`, `backup`, `unknownFutureValue`.
Note, *unknownFutureValue* is a future placeholder and not a real settingType.| |windowsDeviceId|String|A unique identifier for the device the setting may belong to if it is of the settingType `backup`.| ## About the *payloadType* property @@ -96,7 +103,7 @@ Rather than being a setting the user has applied, this type records information - *deviceDisplayName* is the name of the computer which can be seen in Windows system settings at "**Start** > **Settings** > **System**". - *profileId* is an identifier used to link **WindowsSettings** items to the device that uploaded them. This property corresponds to **windowsSetting.windowsDeviceId** and can be used as a filter to get settings for a specific device from [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API. -Following is an example of this setting. +The following example shows this resource type. ```json { diff --git a/api-reference/beta/resources/windowssettinginstance.md b/api-reference/beta/resources/windowssettinginstance.md index 6290116c87f..bb25e9d1a67 100644 --- a/api-reference/beta/resources/windowssettinginstance.md +++ b/api-reference/beta/resources/windowssettinginstance.md @@ -13,9 +13,9 @@ Namespace: microsoft.graph [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -**windowsSettingInstance** represents setting instances from Windows operating system that are stored in the cloud for a given user. +**windowsSettingInstance** represents setting instances from the Windows operating system that are stored in the cloud for a given user. -A **windowsSettingInstance** belongs to a [**windowsSetting**](../resources/windowssetting.md) and represents a specific setting value for a given user. +A **windowsSettingInstance** belongs to a [**windowsSetting**](../resources/windowssetting.md). The *payload* property of a **windowsSettingInstance** contains the actual setting value. The *payload* is a string in base64 encoded format. The *payloadType* property of the [**windowsSetting**](../resources/windowssetting.md) object indicates the type of the setting value. The *payload* when decoded is a JSON object which differs from setting to setting and is specific to the *payloadType*. diff --git a/api-reference/beta/toc.yml b/api-reference/beta/toc.yml index 7aeb60e72c6..a20311ed0f9 100644 --- a/api-reference/beta/toc.yml +++ b/api-reference/beta/toc.yml @@ -1608,6 +1608,9 @@ items: href: api/usersettings-list-windows.md - name: Get Windows setting href: api/windowssetting-get.md + - name: Windows setting instances + href: resources/windowssettinginstance.md + items: - name: List Windows setting instances href: api/windowssetting-list-instances.md - name: Get Windows setting instance From 28e8ece4f2a83225150de088bdf00162c74e46ae Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Mon, 26 Feb 2024 18:42:13 -0700 Subject: [PATCH 20/54] Addressed review comment --- api-reference/beta/resources/windowssetting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index d826d8ac15c..547182357a2 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -42,7 +42,7 @@ Inherits from [entity](../resources/entity.md). |:---|:---|:---| |id|String|The unique identifier of the object.| |payloadType|String|The type of setting payloads contained in the *instances* navigation property.| -|settingType|[windowsSettingType](enums.md#windowssettingtype-values)|The type of setting. Possible values are: `roaming`, `backup`, `unknownFutureValue`.
Note, *unknownFutureValue* is a future placeholder and not a real settingType.| +|settingType|[windowsSettingType](enums.md#windowssettingtype-values)|The type of setting. Possible values are: `roaming`, `backup`, `unknownFutureValue`.| |windowsDeviceId|String|A unique identifier for the device the setting may belong to if it is of the settingType `backup`.| ## About the *payloadType* property From fa9e383ff914efbb7367b83bf7b21c03fa32229f Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Wed, 28 Feb 2024 00:59:27 -0700 Subject: [PATCH 21/54] Created conceptualPage for settings and moved content from other files --- .../resources/windows-setting-api-overview.md | 189 ++++++++++++++++++ .../beta/resources/windowssetting.md | 108 +--------- .../beta/resources/windowssettinginstance.md | 2 - api-reference/beta/toc.yml | 2 + 4 files changed, 192 insertions(+), 109 deletions(-) create mode 100644 api-reference/beta/resources/windows-setting-api-overview.md diff --git a/api-reference/beta/resources/windows-setting-api-overview.md b/api-reference/beta/resources/windows-setting-api-overview.md new file mode 100644 index 00000000000..ba66977578c --- /dev/null +++ b/api-reference/beta/resources/windows-setting-api-overview.md @@ -0,0 +1,189 @@ +--- +title: "Microsoft Graph Windows Setting APIs to retrive Windows OS settings stored in cloud" +description: "The Windows Setting APIs enable users and authorized third parties to access users’ Windows operating system settings data that is stored in Microsoft cloud. The APIs facilitate sharing and exporting of the data in a secure and compliant manner, ensuring that data is only shared with explicit user consent. The APIs demonstrate Microsoft’s dedication to user privacy and adherence to the EU Digital Markets Act, offering a clear and user-focused way of data portability." +ms.localizationpriority: medium +doc_type: conceptualPageType +author: "MS-Arko" +ms.prod: "cross-device-experiences" +--- + +# Microsoft Graph Windows Setting APIs to retrive Windows OS settings stored in cloud + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +The Windows Setting APIs enable users and authorized third parties to access users’ Windows operating system settings data that is stored in Microsoft cloud. The APIs facilitate sharing and exporting of the data in a secure and compliant manner, ensuring that data is only shared with explicit user consent. The APIs demonstrate Microsoft’s dedication to user privacy and adherence to the EU Digital Markets Act, offering a clear and user-focused way of Windows settings data portability. + +## Windows Settings + +A [**windowsSetting**](../resources/windowssetting.md) represents various settings from the Windows operating system that are stored in the cloud for a given user. + +There are two types of [windowsSetting](../resources/windowssetting.md): `roaming` and `backup`. The *settingType* property of a [windowsSetting](../resources/windowssetting.md) object indicates the type of the setting. + +| settingType | Description | +| :----------------- | :--------------------------------- | +| roaming | Windows setting is associated with a user's account. It is consistent across all devices and any changes to the setting value are synced or applied to all Windows devices that the user owns.| +| backup | Windows setting does not roam or sync accross devices. This type of setting is used in device backup and restore scenarios.| + + A [windowsSetting](../resources/windowssetting.md) of type `backup` may have a *windowsDeviceId* property that links the setting to a specific device. + + The [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API returns a collection of [windowsSetting](../resources/windowssetting.md) objects and their properties. The result can be filtered by *windowsDeviceId* and *settingType* properties. + +The [Get Windows setting stored in cloud](../api/windowssetting-get.md) API allows to pass the ID of a [windowsSetting](../resources/windowssetting.md) in the URL to read a specific Windows setting object. + +The following JSON representation shows an example Windows setting. The instances collection in it represents **Windows setting instances**, elaborated in the next section. + + +``` json +{ + "@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" + } + ] +} +``` + +>Warning: The structure of the **ID** of a [**windowsSetting**](../resources/windowssetting.md) is not guaranteed and the caller should not take any dependency on it. The ID should be treated as an opaque string. + +## Windows Setting Instances + +A [**windowsSettingInstance**](../resources/windowssettinginstance.md) represents a setting instance from the Windows operating system that is stored in the cloud for a given user. A [windowsSettingInstance](../resources/windowssettinginstance.md) belongs to a [windowsSetting](../resources/windowssetting.md). + +The following JSON representation shows an example windows setting instance. + + +``` json +{ + "@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" +} +``` + +The [List Windows setting instances stored in cloud](../api/windowssetting-list-instances.md) API returns a collection of [windowsSettingInstance](../resources/windowssettinginstance.md) objects and their properties. The API requires the ID of a [windowsSetting](../resources/windowssetting.md) in the URL to read the setting instances. + +The [Get Windows setting instance stored in cloud](../api/windowssettinginstance-get.md) API allows to pass the ID of a [windowsSetting](../resources/windowssetting.md) and [windowsSettingInstance](../resources/windowssettinginstance.md) in the URL to read a specific windows setting instance object. + +The *payload* property of a [**windowsSettingInstance**](../resources/windowssettinginstance.md) contains the actual setting value. The *payload* is a string in Base64 encoded format. The *payloadType* property of the [**windowsSetting**](../resources/windowssetting.md) object indicates the type of the setting value. The *payload* when decoded is a JSON object which differs from setting to setting and is specific to the *payloadType*. + +## About the *payloadType* property +### Introduction +The *payloadType* defines the structure of a [windowsSettingInstance](./windowssettinginstance.md) payload. There are numerous payloadTypes in Windows which represent distinct setting structures used by different experiences in the operating system. As Windows evolves, more payloadTypes are created and onboarded to the cloud. Querying the API and exploring the settings available is the best way to learn about the various payloadTypes, but users and admins have control over which settings are uploaded to the cloud and most components do not upload default settings that the user has not customized. + +Following is an example of a settingsInstance from the API. + +```json +{ + "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 this example, the payloadType `windows.data.fileexplorerclassic.advancedsettings` represents some of the settings that the File Explorer backs up to the cloud. The Base64 payload can be decoded to a UTF-8 string to see the JSON representation of this object. + +**Payload decoded:** +```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 +} +``` + +It is common for the properties in the object to be a subset of those available in the component’s user experience as component owners decide which settings provide the most value when uploaded to the cloud. + +### PayloadTypes of particular interest + +Some payloadTypes have a special role in the Windows settings backup process. + +#### windows.data.platform.backuprestore.deviceprofile +Rather than being a setting the user has applied, this type records information about devices that have opted into settings backup features. Two properties in this object are useful for understanding the rest of the settings: *deviceDisplayName* and *profileId*. + +- *deviceDisplayName* is the name of the computer which can be seen in Windows system settings at "**Start** > **Settings** > **System**". +- *profileId* is an identifier used to link [**windowsSetting**](../resources/windowssetting.md) items to the device that uploaded them. This property corresponds to **windowsSetting.windowsDeviceId** and can be used as a filter to get settings for a specific device from [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API. + +The following example shows this resource type. + +```json +{ + "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" + } + ] +} +``` +**Payload decoded:** + +```json +{ + "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 + +The **backupUnitStore** payloadType settings are unique in that the actual settings value is a **blob** in the data property. This is because **backupUnitStore** settings are collected directly from the Windows registry, on disk files, or other at rest locations throughout Windows. These settings were not designed to be interoperable with experiences besides the components that created them, but they have been included in this API for comprehensive coverage of all Windows settings stored in the cloud. \ No newline at end of file diff --git a/api-reference/beta/resources/windowssetting.md b/api-reference/beta/resources/windowssetting.md index 547182357a2..d33f5cde466 100644 --- a/api-reference/beta/resources/windowssetting.md +++ b/api-reference/beta/resources/windowssetting.md @@ -17,16 +17,7 @@ Represents settings from the Windows operating system that are stored in the clo >Warning: The structure of the ID of a **windowsSetting** is not guaranteed and the caller should not take any dependency on it. The ID should be treated as an opaque string. -There are two types of **windowsSetting**: `roaming` and `backup`. More information, see [windowsSettingType](enums.md#windowssettingtype-values) enum. The settingType property of a **windowsSetting** object indicates the type of the setting. - -| settingType | Description | -| :----------------- | :--------------------------------- | -| roaming | Windows setting is associated with a user's account. It is consistent across all devices and any changes to the setting value are synced or applied to all Windows devices that the user owns.| -| backup | Windows setting does not roam or sync accross devices. This type of setting is used in device backup and restore scenarios.| - - A **windowsSetting** of type `backup` may have a *windowsDeviceId* property that links the setting to a specific device. - -When getting a list of **windowsSetting** objects, the result can be filtered by *windowsDeviceId* and *settingType* properties. For more information, see [List Windows settings stored in cloud](../api/usersettings-list-windows.md). +There are two types of **windowsSetting**: `roaming` and `backup`. More information, see [windowsSettingType](enums.md#windowssettingtype-values) enum. Inherits from [entity](../resources/entity.md). @@ -45,103 +36,6 @@ Inherits from [entity](../resources/entity.md). |settingType|[windowsSettingType](enums.md#windowssettingtype-values)|The type of setting. Possible values are: `roaming`, `backup`, `unknownFutureValue`.| |windowsDeviceId|String|A unique identifier for the device the setting may belong to if it is of the settingType `backup`.| -## About the *payloadType* property -### Introduction -The *payloadType* defines the structure of a [windowsSettingInstance](./windowssettinginstance.md) payload. There are numerous payloadTypes in Windows which represent distinct setting structures used by different experiences in the operating system. As Windows evolves, more payloadTypes are created and onboarded to the cloud. Querying the API and exploring the settings available is the best way to learn about the various payloadTypes, but users and admins have control over which settings are uploaded to the cloud and most components do not upload default settings that the user has not customized. - -Following is an example of a settingsInstance from the API. - -```json -{ - "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 this example, the payloadType `windows.data.fileexplorerclassic.advancedsettings` represents some of the settings that the File Explorer backs up to the cloud. The base64 payload can be decoded to a UTF-8 string to see the JSON representation of this object. - -**Payload decoded:** -```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 -} -``` - -It is common for the properties in the object to be a subset of those available in the component’s user experience as component owners decide which settings provide the most value when uploaded to the cloud. - -### PayloadTypes of particular interest - -Some payloadTypes have a special role in the Windows settings backup process. - -#### windows.data.platform.backuprestore.deviceprofile -Rather than being a setting the user has applied, this type records information about devices that have opted into settings backup features. Two properties in this object are useful for understanding the rest of the settings: deviceDisplayName and profileId. - -- *deviceDisplayName* is the name of the computer which can be seen in Windows system settings at "**Start** > **Settings** > **System**". -- *profileId* is an identifier used to link **WindowsSettings** items to the device that uploaded them. This property corresponds to **windowsSetting.windowsDeviceId** and can be used as a filter to get settings for a specific device from [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API. - -The following example shows this resource type. - -```json -{ - "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" - } - ] -} -``` -**Payload decoded:** - -```json -{ - "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 - -The **backupUnitStore** payloadType settings are unique in that the actual settings value is a **blob** in the data property. This is because **backupUnitStore** settings are collected directly from the Windows registry, on disk files, or other at rest locations throughout Windows. These settings were not designed to be interoperable with experiences besides the components that created them, but they have been included in this API for comprehensive coverage of all Windows settings in the cloud. - - ## Relationships |Relationship|Type|Description| |:---|:---|:---| diff --git a/api-reference/beta/resources/windowssettinginstance.md b/api-reference/beta/resources/windowssettinginstance.md index 3fcdfc755ed..4a3e7938882 100644 --- a/api-reference/beta/resources/windowssettinginstance.md +++ b/api-reference/beta/resources/windowssettinginstance.md @@ -17,8 +17,6 @@ Represents a setting instance from the Windows operating system that is stored i A **windowsSettingInstance** belongs to a [**windowsSetting**](../resources/windowssetting.md). -The *payload* property of a **windowsSettingInstance** contains the actual setting value. The *payload* is a string in base64 encoded format. The *payloadType* property of the [**windowsSetting**](../resources/windowssetting.md) object indicates the type of the setting value. The *payload* when decoded is a JSON object which differs from setting to setting and is specific to the *payloadType*. - Inherits from [entity](../resources/entity.md). ## Methods diff --git a/api-reference/beta/toc.yml b/api-reference/beta/toc.yml index 927ef729fa8..29a3187f4b2 100644 --- a/api-reference/beta/toc.yml +++ b/api-reference/beta/toc.yml @@ -1601,6 +1601,8 @@ items: href: api/projectrome-delete-historyitem.md - name: Roaming data items: + - name: Overview + href: resources/windows-setting-api-overview.md - name: Windows settings href: resources/windowssetting.md items: From cf0afc65af2a1e0fe3e1c36dcc7e62eb6934b295 Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Wed, 28 Feb 2024 01:12:47 -0700 Subject: [PATCH 22/54] Rectified Acrolinx scorecard issues --- api-reference/beta/resources/windowssettinginstance.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api-reference/beta/resources/windowssettinginstance.md b/api-reference/beta/resources/windowssettinginstance.md index 4a3e7938882..39ab90cf24e 100644 --- a/api-reference/beta/resources/windowssettinginstance.md +++ b/api-reference/beta/resources/windowssettinginstance.md @@ -29,10 +29,10 @@ Inherits from [entity](../resources/entity.md). |Property|Type|Description| |:---|:---|:---| |createdDateTime|DateTimeOffset|Set by the server. DateTime in UTC when the object was created on the server.| -|expirationDateTime|DateTimeOffset|Set by the server. DateTime in UTC when the object will expire after which it will no longer be available.| +|expirationDateTime|DateTimeOffset|Set by the server. The object expires at the DateTime in UTC, after which it becomes unavailable.| |id|String|The unique identifier of the object. Inherited from [entity](../resources/entity.md).| -|lastModifiedDateTime|DateTimeOffset|Set by the server if not provided in Windows client device's request. DateTime in UTC when the object was modified by the user’s Windows device.| -|payload|String|Base64 encoded JSON setting value.| +|lastModifiedDateTime|DateTimeOffset|Set by the server if not provided in Windows client device's request. The user’s Windows device modified the object at the DateTime in UTC.| +|payload|String|Base 64 encoded JSON setting value.| ## Relationships None. From ff414bb25ec45af530deba26f3c494c4fa5313b1 Mon Sep 17 00:00:00 2001 From: Daniela Bonilla Montero <92937694+Danielabom@users.noreply.github.com> Date: Wed, 28 Feb 2024 09:14:54 -0600 Subject: [PATCH 23/54] Apply suggestions from code review --- api-reference/beta/api/usersettings-list-windows.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/api-reference/beta/api/usersettings-list-windows.md b/api-reference/beta/api/usersettings-list-windows.md index 3fbcc9436cd..0dfc86ddf55 100644 --- a/api-reference/beta/api/usersettings-list-windows.md +++ b/api-reference/beta/api/usersettings-list-windows.md @@ -1,5 +1,5 @@ --- -title: "List Windows Settings" +title: "List Windows settings" description: "Get a list of the windowsSetting objects and their properties." author: "MS-Arko" ms.localizationpriority: medium @@ -7,7 +7,7 @@ ms.prod: "cross-device-experiences" doc_type: apiPageType --- -# List Windows settings stored in cloud +# List Windows settings stored in a cloud Namespace: microsoft.graph @@ -42,11 +42,11 @@ GET /me/settings/windows ## Optional query parameters -This method supports `$filter` OData query parameter to help customize the response. The result can be filtered by `windowsDeviceId` and `settingType` properties. For general information, see [OData query parameters](/graph/query-parameters). +This method supports the `$filter` OData query parameter to help customize the response. The result can be filtered by `windowsDeviceId` and `settingType` properties. For general information, see [OData query parameters](/graph/query-parameters). -1. **`windowsDeviceId`**: A string value representing the unique identifier of a Windows device. This identifier can be found in the response body. By filtering with `WindowsDeviceId`, a filtered list of settings specific to that device can be retrieved. Only equality (`eq`) comparison is supported for this parameter. +1. **`windowsDeviceId`**: A string value that represents the unique identifier of a Windows device. This identifier can be found in the response body. By filtering with `windowsDeviceId`, a filtered list of settings specific to that device can be retrieved. Only equality (`eq`) comparison is supported for this parameter. -2. **`settingType`**: An enumeration with valid values: `roaming` and `backup`. The `settingType` parameter allows narrowing down the results to settings related to either roaming or backup. Only equality (`eq`) comparison is supported for this parameter. For more information on settingType, see [windowssettingtype](../resources/enums.md#windowssettingtype-values). +2. **`settingType`**: An enumeration with valid values: `roaming` and `backup`. The `settingType` parameter allows narrowing down the results to settings related to either roaming or backup. Only equality (`eq`) comparison is supported for this parameter. For more information, see [windowssettingtype](../resources/enums.md#windowssettingtype-values). Please refer to the [examples](./usersettings-list-windows.md#examples) section below for more information on how to use these query parameters. From 334d9ad0d990d150082c805311ac74a180bb208c Mon Sep 17 00:00:00 2001 From: Daniela Bonilla Montero <92937694+Danielabom@users.noreply.github.com> Date: Wed, 28 Feb 2024 09:25:05 -0600 Subject: [PATCH 24/54] Apply suggestions from code review --- api-reference/beta/api/windowssetting-get.md | 4 ++-- api-reference/beta/api/windowssetting-list-instances.md | 4 ++-- api-reference/beta/api/windowssettinginstance-get.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/api-reference/beta/api/windowssetting-get.md b/api-reference/beta/api/windowssetting-get.md index ca1c6d1d067..8735d57959d 100644 --- a/api-reference/beta/api/windowssetting-get.md +++ b/api-reference/beta/api/windowssetting-get.md @@ -7,13 +7,13 @@ ms.prod: "cross-device-experiences" doc_type: apiPageType --- -# Get Windows setting stored in cloud +# Get Windows setting stored in a cloud Namespace: microsoft.graph [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -Read the properties and relationships of a [windowsSetting](../resources/windowssetting.md) object by passing id of the setting in the URL. +Read the properties and relationships of a [windowsSetting](../resources/windowssetting.md) object by passing the ID of the setting in the URL. ## Permissions diff --git a/api-reference/beta/api/windowssetting-list-instances.md b/api-reference/beta/api/windowssetting-list-instances.md index d7e9b1b69b3..8553d1528df 100644 --- a/api-reference/beta/api/windowssetting-list-instances.md +++ b/api-reference/beta/api/windowssetting-list-instances.md @@ -1,5 +1,5 @@ --- -title: "List Windows Setting Instances" +title: "List Windows setting instances" description: "Get a list of the windowsSettingInstance objects and their properties." author: "MS-Arko" ms.localizationpriority: medium @@ -7,7 +7,7 @@ ms.prod: "cross-device-experiences" doc_type: apiPageType --- -# List Windows setting instances stored in cloud +# List Windows setting instances stored in a cloud Namespace: microsoft.graph diff --git a/api-reference/beta/api/windowssettinginstance-get.md b/api-reference/beta/api/windowssettinginstance-get.md index fee0389c4ec..e20d48183d1 100644 --- a/api-reference/beta/api/windowssettinginstance-get.md +++ b/api-reference/beta/api/windowssettinginstance-get.md @@ -13,7 +13,7 @@ Namespace: microsoft.graph [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -Read the properties and relationships of a [windowsSettingInstance](../resources/windowssettinginstance.md) object by passing windows setting id and windows setting instance id in the URL. +Read the properties and relationships of a [windowsSettingInstance](../resources/windowssettinginstance.md) object by passing the Windows setting ID and Windows setting instance ID in the URL. ## Permissions From 1e5c4bfe8449130081863f00a5368a6c3b95b673 Mon Sep 17 00:00:00 2001 From: Daniela Bonilla Montero <92937694+Danielabom@users.noreply.github.com> Date: Wed, 28 Feb 2024 09:28:19 -0600 Subject: [PATCH 25/54] Apply suggestions from code review --- api-reference/beta/resources/usersettings.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api-reference/beta/resources/usersettings.md b/api-reference/beta/resources/usersettings.md index 52f7484eb91..03a6a2ead75 100644 --- a/api-reference/beta/resources/usersettings.md +++ b/api-reference/beta/resources/usersettings.md @@ -41,11 +41,11 @@ Configure [contactMergeSuggestions](../resources/contactmergesuggestions.md): - Determining whether suggestion to merge duplicate contacts for a user is enabled. - Disabling or enabling suggestion to merge duplicate contacts for a user. -Export user's Windows settings and values stored in cloud. +Export user's Windows settings and values stored in a cloud. - Get a list of the user's [windowsSetting](../resources/windowssetting.md) objects. - Get a filtered list of the user's [windowsSetting](../resources/windowssetting.md) objects by passing, - - [windowssettingtype](../resources/enums.md#windowssettingtype-values) in filter query. - - [windowsDeviceId](../resources/windowssetting.md#properties) in filter query. + - [windowssettingtype](../resources/enums.md#windowssettingtype-values) in the filter query. + - [windowsDeviceId](../resources/windowssetting.md#properties) in the filter query. Inherits from [entity](entity.md). To learn how to get or update user settings, see [Get settings](../api/usersettings-get.md) and [Update settings](../api/usersettings-update.md). From 87ef49a48fb0825e4afbfea3d3aade39f7706f56 Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Wed, 28 Feb 2024 17:03:52 -0700 Subject: [PATCH 26/54] Addressed Acrolinx score issues --- .../resources/windows-setting-api-overview.md | 26 +++++++++---------- .../beta/resources/windowssettinginstance.md | 2 +- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/api-reference/beta/resources/windows-setting-api-overview.md b/api-reference/beta/resources/windows-setting-api-overview.md index ba66977578c..65ef9eab4ff 100644 --- a/api-reference/beta/resources/windows-setting-api-overview.md +++ b/api-reference/beta/resources/windows-setting-api-overview.md @@ -1,5 +1,5 @@ --- -title: "Microsoft Graph Windows Setting APIs to retrive Windows OS settings stored in cloud" +title: "Microsoft Graph Windows Setting APIs to retrieve Windows OS settings stored in cloud" description: "The Windows Setting APIs enable users and authorized third parties to access users’ Windows operating system settings data that is stored in Microsoft cloud. The APIs facilitate sharing and exporting of the data in a secure and compliant manner, ensuring that data is only shared with explicit user consent. The APIs demonstrate Microsoft’s dedication to user privacy and adherence to the EU Digital Markets Act, offering a clear and user-focused way of data portability." ms.localizationpriority: medium doc_type: conceptualPageType @@ -7,11 +7,11 @@ author: "MS-Arko" ms.prod: "cross-device-experiences" --- -# Microsoft Graph Windows Setting APIs to retrive Windows OS settings stored in cloud +# Microsoft Graph Windows Setting APIs to retrieve Windows OS settings stored in cloud [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -The Windows Setting APIs enable users and authorized third parties to access users’ Windows operating system settings data that is stored in Microsoft cloud. The APIs facilitate sharing and exporting of the data in a secure and compliant manner, ensuring that data is only shared with explicit user consent. The APIs demonstrate Microsoft’s dedication to user privacy and adherence to the EU Digital Markets Act, offering a clear and user-focused way of Windows settings data portability. +The Windows Setting APIs enable users and authorized third parties to access users’ Windows operating system settings data that is stored in Microsoft cloud. The APIs facilitate sharing and exporting of the data in a secure and compliant manner by ensuring that data is only shared with explicit user consent. The APIs demonstrate Microsoft’s dedication to user privacy and adherence to the EU Digital Markets Act by offering a clear and user-focused way of Windows settings data portability. ## Windows Settings @@ -21,14 +21,14 @@ There are two types of [windowsSetting](../resources/windowssetting.md): `roamin | settingType | Description | | :----------------- | :--------------------------------- | -| roaming | Windows setting is associated with a user's account. It is consistent across all devices and any changes to the setting value are synced or applied to all Windows devices that the user owns.| -| backup | Windows setting does not roam or sync accross devices. This type of setting is used in device backup and restore scenarios.| +| roaming | Windows setting is associated with a user's account. It's consistent across all devices and any changes to the setting value are synced or applied to all Windows devices that the user owns.| +| backup | Windows setting doesn't roam or sync across devices. This type of setting is used in device backup and restore scenarios.| A [windowsSetting](../resources/windowssetting.md) of type `backup` may have a *windowsDeviceId* property that links the setting to a specific device. - The [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API returns a collection of [windowsSetting](../resources/windowssetting.md) objects and their properties. The result can be filtered by *windowsDeviceId* and *settingType* properties. + The [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API returns a collection of [windowsSetting](../resources/windowssetting.md) objects and their properties. You can filter the results by *windowsDeviceId* and *settingType* properties. -The [Get Windows setting stored in cloud](../api/windowssetting-get.md) API allows to pass the ID of a [windowsSetting](../resources/windowssetting.md) in the URL to read a specific Windows setting object. +The [Get Windows setting stored in cloud](../api/windowssetting-get.md) API allows you to pass the ID of a [windowsSetting](../resources/windowssetting.md) in the URL to read a specific Windows setting object. The following JSON representation shows an example Windows setting. The instances collection in it represents **Windows setting instances**, elaborated in the next section. @@ -88,13 +88,13 @@ The following JSON representation shows an example windows setting instance. The [List Windows setting instances stored in cloud](../api/windowssetting-list-instances.md) API returns a collection of [windowsSettingInstance](../resources/windowssettinginstance.md) objects and their properties. The API requires the ID of a [windowsSetting](../resources/windowssetting.md) in the URL to read the setting instances. -The [Get Windows setting instance stored in cloud](../api/windowssettinginstance-get.md) API allows to pass the ID of a [windowsSetting](../resources/windowssetting.md) and [windowsSettingInstance](../resources/windowssettinginstance.md) in the URL to read a specific windows setting instance object. +The [Get Windows setting instance stored in cloud](../api/windowssettinginstance-get.md) API allows you to pass the ID of a [windowsSetting](../resources/windowssetting.md) and [windowsSettingInstance](../resources/windowssettinginstance.md) in the URL to read a specific windows setting instance object. -The *payload* property of a [**windowsSettingInstance**](../resources/windowssettinginstance.md) contains the actual setting value. The *payload* is a string in Base64 encoded format. The *payloadType* property of the [**windowsSetting**](../resources/windowssetting.md) object indicates the type of the setting value. The *payload* when decoded is a JSON object which differs from setting to setting and is specific to the *payloadType*. +The *payload* property of a [**windowsSettingInstance**](../resources/windowssettinginstance.md) contains the actual setting value. The *payload* is a string in Base64 encoded format. The *payloadType* property of the [**windowsSetting**](../resources/windowssetting.md) object indicates the type of the setting value. The *payload* when decoded is a JSON object, which differs from setting to setting and is specific to the *payloadType*. ## About the *payloadType* property ### Introduction -The *payloadType* defines the structure of a [windowsSettingInstance](./windowssettinginstance.md) payload. There are numerous payloadTypes in Windows which represent distinct setting structures used by different experiences in the operating system. As Windows evolves, more payloadTypes are created and onboarded to the cloud. Querying the API and exploring the settings available is the best way to learn about the various payloadTypes, but users and admins have control over which settings are uploaded to the cloud and most components do not upload default settings that the user has not customized. +The *payloadType* defines the structure of a [windowsSettingInstance](./windowssettinginstance.md) payload. There are numerous payloadTypes in Windows, which represent distinct setting structures used by different experiences in the operating system. As Windows evolves, more payloadTypes are created and onboarded to the cloud. Querying the API and exploring the settings available is the best way to learn about the various payloadTypes. The users and admins have control over which settings are uploaded to the cloud and most components don't upload default settings that the user hasn't customized. Following is an example of a settingsInstance from the API. @@ -138,7 +138,7 @@ In this example, the payloadType `windows.data.fileexplorerclassic.advancedsetti } ``` -It is common for the properties in the object to be a subset of those available in the component’s user experience as component owners decide which settings provide the most value when uploaded to the cloud. +It is common for the properties in the object to be a subset of those that are available in the component’s user experience as component owners decide which settings provide the most value when uploaded to the cloud. ### PayloadTypes of particular interest @@ -147,7 +147,7 @@ Some payloadTypes have a special role in the Windows settings backup process. #### windows.data.platform.backuprestore.deviceprofile Rather than being a setting the user has applied, this type records information about devices that have opted into settings backup features. Two properties in this object are useful for understanding the rest of the settings: *deviceDisplayName* and *profileId*. -- *deviceDisplayName* is the name of the computer which can be seen in Windows system settings at "**Start** > **Settings** > **System**". +- *deviceDisplayName* is the name of the computer, which can be seen in Windows system settings at "**Start** > **Settings** > **System**". - *profileId* is an identifier used to link [**windowsSetting**](../resources/windowssetting.md) items to the device that uploaded them. This property corresponds to **windowsSetting.windowsDeviceId** and can be used as a filter to get settings for a specific device from [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API. The following example shows this resource type. @@ -186,4 +186,4 @@ The following example shows this resource type. #### windows.data.platform.settingsbackup.backupunitstore -The **backupUnitStore** payloadType settings are unique in that the actual settings value is a **blob** in the data property. This is because **backupUnitStore** settings are collected directly from the Windows registry, on disk files, or other at rest locations throughout Windows. These settings were not designed to be interoperable with experiences besides the components that created them, but they have been included in this API for comprehensive coverage of all Windows settings stored in the cloud. \ No newline at end of file +The **backupUnitStore** payloadType settings are unique in that the actual settings value is a **blob** in the data property. This is because **backupUnitStore** settings are collected directly from the Windows registry, on disk files, or other at rest locations throughout Windows. These settings weren't designed to be interoperable with experiences besides the components that created them. However, they have been included in this API for comprehensive coverage of all Windows settings that are stored in the cloud. \ No newline at end of file diff --git a/api-reference/beta/resources/windowssettinginstance.md b/api-reference/beta/resources/windowssettinginstance.md index 39ab90cf24e..0f793fe1bb0 100644 --- a/api-reference/beta/resources/windowssettinginstance.md +++ b/api-reference/beta/resources/windowssettinginstance.md @@ -32,7 +32,7 @@ Inherits from [entity](../resources/entity.md). |expirationDateTime|DateTimeOffset|Set by the server. The object expires at the DateTime in UTC, after which it becomes unavailable.| |id|String|The unique identifier of the object. Inherited from [entity](../resources/entity.md).| |lastModifiedDateTime|DateTimeOffset|Set by the server if not provided in Windows client device's request. The user’s Windows device modified the object at the DateTime in UTC.| -|payload|String|Base 64 encoded JSON setting value.| +|payload|String|Base64 encoded JSON setting value.| ## Relationships None. From 111f5b983ac6847a183fdebb816b07eb57db148e Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Thu, 29 Feb 2024 18:58:27 -0700 Subject: [PATCH 27/54] Addressed review comments --- .../beta/api/usersettings-list-windows.md | 2 +- api-reference/beta/api/windowssetting-get.md | 2 +- .../beta/api/windowssetting-list-instances.md | 2 +- .../beta/api/windowssettinginstance-get.md | 2 +- .../beta/resources/windows-setting-api-overview.md | 14 +++++++------- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/api-reference/beta/api/usersettings-list-windows.md b/api-reference/beta/api/usersettings-list-windows.md index 0dfc86ddf55..b17b66c7f43 100644 --- a/api-reference/beta/api/usersettings-list-windows.md +++ b/api-reference/beta/api/usersettings-list-windows.md @@ -7,7 +7,7 @@ ms.prod: "cross-device-experiences" doc_type: apiPageType --- -# List Windows settings stored in a cloud +# List Windows settings Namespace: microsoft.graph diff --git a/api-reference/beta/api/windowssetting-get.md b/api-reference/beta/api/windowssetting-get.md index 8735d57959d..bd9c545c835 100644 --- a/api-reference/beta/api/windowssetting-get.md +++ b/api-reference/beta/api/windowssetting-get.md @@ -7,7 +7,7 @@ ms.prod: "cross-device-experiences" doc_type: apiPageType --- -# Get Windows setting stored in a cloud +# Get Windows setting Namespace: microsoft.graph diff --git a/api-reference/beta/api/windowssetting-list-instances.md b/api-reference/beta/api/windowssetting-list-instances.md index 8553d1528df..131d458b3a7 100644 --- a/api-reference/beta/api/windowssetting-list-instances.md +++ b/api-reference/beta/api/windowssetting-list-instances.md @@ -7,7 +7,7 @@ ms.prod: "cross-device-experiences" doc_type: apiPageType --- -# List Windows setting instances stored in a cloud +# List Windows setting instances Namespace: microsoft.graph diff --git a/api-reference/beta/api/windowssettinginstance-get.md b/api-reference/beta/api/windowssettinginstance-get.md index e20d48183d1..5812eb9664e 100644 --- a/api-reference/beta/api/windowssettinginstance-get.md +++ b/api-reference/beta/api/windowssettinginstance-get.md @@ -7,7 +7,7 @@ ms.prod: "cross-device-experiences" doc_type: apiPageType --- -# Get Windows setting instance stored in cloud +# Get Windows setting instance Namespace: microsoft.graph diff --git a/api-reference/beta/resources/windows-setting-api-overview.md b/api-reference/beta/resources/windows-setting-api-overview.md index 65ef9eab4ff..60ff70b9b4d 100644 --- a/api-reference/beta/resources/windows-setting-api-overview.md +++ b/api-reference/beta/resources/windows-setting-api-overview.md @@ -1,6 +1,6 @@ --- title: "Microsoft Graph Windows Setting APIs to retrieve Windows OS settings stored in cloud" -description: "The Windows Setting APIs enable users and authorized third parties to access users’ Windows operating system settings data that is stored in Microsoft cloud. The APIs facilitate sharing and exporting of the data in a secure and compliant manner, ensuring that data is only shared with explicit user consent. The APIs demonstrate Microsoft’s dedication to user privacy and adherence to the EU Digital Markets Act, offering a clear and user-focused way of data portability." +description: "The Windows Setting APIs enable users and authorized third parties, on behalf of the users, to access their Windows operating system settings data stored in Microsoft cloud. Windows settings data is available in Microsoft cloud only when users enable the feature. The data present for each user varies based on what they choose to backup from the settings. Notably, default values for any given setting remain local and are not uploaded to the cloud. The APIs share only those setting data that has been uploaded to the cloud for the user." ms.localizationpriority: medium doc_type: conceptualPageType author: "MS-Arko" @@ -11,7 +11,7 @@ ms.prod: "cross-device-experiences" [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -The Windows Setting APIs enable users and authorized third parties to access users’ Windows operating system settings data that is stored in Microsoft cloud. The APIs facilitate sharing and exporting of the data in a secure and compliant manner by ensuring that data is only shared with explicit user consent. The APIs demonstrate Microsoft’s dedication to user privacy and adherence to the EU Digital Markets Act by offering a clear and user-focused way of Windows settings data portability. +The Windows Setting APIs enable users and authorized third parties, on behalf of the users, to access their Windows operating system settings data stored in Microsoft cloud. Windows settings data is available in Microsoft cloud only when users enable the feature. The data present for each user varies based on what they choose to backup from the settings. Notably, default values for any given setting remain local and are not uploaded to the cloud. The APIs share only those setting data that has been uploaded to the cloud for the user. ## Windows Settings @@ -26,9 +26,9 @@ There are two types of [windowsSetting](../resources/windowssetting.md): `roamin A [windowsSetting](../resources/windowssetting.md) of type `backup` may have a *windowsDeviceId* property that links the setting to a specific device. - The [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API returns a collection of [windowsSetting](../resources/windowssetting.md) objects and their properties. You can filter the results by *windowsDeviceId* and *settingType* properties. + The [List Windows settings](../api/usersettings-list-windows.md) API returns a collection of [windowsSetting](../resources/windowssetting.md) objects and their properties. You can filter the results by *windowsDeviceId* and *settingType* properties. -The [Get Windows setting stored in cloud](../api/windowssetting-get.md) API allows you to pass the ID of a [windowsSetting](../resources/windowssetting.md) in the URL to read a specific Windows setting object. +The [Get Windows setting](../api/windowssetting-get.md) API allows you to pass the ID of a [windowsSetting](../resources/windowssetting.md) in the URL to read a specific Windows setting object. The following JSON representation shows an example Windows setting. The instances collection in it represents **Windows setting instances**, elaborated in the next section. @@ -86,9 +86,9 @@ The following JSON representation shows an example windows setting instance. } ``` -The [List Windows setting instances stored in cloud](../api/windowssetting-list-instances.md) API returns a collection of [windowsSettingInstance](../resources/windowssettinginstance.md) objects and their properties. The API requires the ID of a [windowsSetting](../resources/windowssetting.md) in the URL to read the setting instances. +The [List Windows setting instances](../api/windowssetting-list-instances.md) API returns a collection of [windowsSettingInstance](../resources/windowssettinginstance.md) objects and their properties. The API requires the ID of a [windowsSetting](../resources/windowssetting.md) in the URL to read the setting instances. -The [Get Windows setting instance stored in cloud](../api/windowssettinginstance-get.md) API allows you to pass the ID of a [windowsSetting](../resources/windowssetting.md) and [windowsSettingInstance](../resources/windowssettinginstance.md) in the URL to read a specific windows setting instance object. +The [Get Windows setting instance](../api/windowssettinginstance-get.md) API allows you to pass the ID of a [windowsSetting](../resources/windowssetting.md) and [windowsSettingInstance](../resources/windowssettinginstance.md) in the URL to read a specific windows setting instance object. The *payload* property of a [**windowsSettingInstance**](../resources/windowssettinginstance.md) contains the actual setting value. The *payload* is a string in Base64 encoded format. The *payloadType* property of the [**windowsSetting**](../resources/windowssetting.md) object indicates the type of the setting value. The *payload* when decoded is a JSON object, which differs from setting to setting and is specific to the *payloadType*. @@ -148,7 +148,7 @@ Some payloadTypes have a special role in the Windows settings backup process. Rather than being a setting the user has applied, this type records information about devices that have opted into settings backup features. Two properties in this object are useful for understanding the rest of the settings: *deviceDisplayName* and *profileId*. - *deviceDisplayName* is the name of the computer, which can be seen in Windows system settings at "**Start** > **Settings** > **System**". -- *profileId* is an identifier used to link [**windowsSetting**](../resources/windowssetting.md) items to the device that uploaded them. This property corresponds to **windowsSetting.windowsDeviceId** and can be used as a filter to get settings for a specific device from [List Windows settings stored in cloud](../api/usersettings-list-windows.md) API. +- *profileId* is an identifier used to link [**windowsSetting**](../resources/windowssetting.md) items to the device that uploaded them. This property corresponds to **windowsSetting.windowsDeviceId** and can be used as a filter to get settings for a specific device from [List Windows settings](../api/usersettings-list-windows.md) API. The following example shows this resource type. From 23f022f9b6b5678abf2441b2f743ca1046aa3a6c Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Thu, 29 Feb 2024 19:04:57 -0700 Subject: [PATCH 28/54] Acrolinx score issues addressed --- .../beta/resources/windows-setting-api-overview.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api-reference/beta/resources/windows-setting-api-overview.md b/api-reference/beta/resources/windows-setting-api-overview.md index 60ff70b9b4d..5f9c3a49346 100644 --- a/api-reference/beta/resources/windows-setting-api-overview.md +++ b/api-reference/beta/resources/windows-setting-api-overview.md @@ -1,6 +1,6 @@ --- title: "Microsoft Graph Windows Setting APIs to retrieve Windows OS settings stored in cloud" -description: "The Windows Setting APIs enable users and authorized third parties, on behalf of the users, to access their Windows operating system settings data stored in Microsoft cloud. Windows settings data is available in Microsoft cloud only when users enable the feature. The data present for each user varies based on what they choose to backup from the settings. Notably, default values for any given setting remain local and are not uploaded to the cloud. The APIs share only those setting data that has been uploaded to the cloud for the user." +description: "The Windows Setting APIs enable users and authorized third parties, on behalf of the users, to access their Windows operating system settings data stored in Microsoft cloud. Windows settings data is available in Microsoft cloud only when users enable the feature. The data present for each user varies based on what they choose to backup from the settings. Notably, default values for any given setting remain local and aren't uploaded to the cloud. The APIs share only those setting data that has been uploaded to the cloud for the user." ms.localizationpriority: medium doc_type: conceptualPageType author: "MS-Arko" @@ -11,7 +11,7 @@ ms.prod: "cross-device-experiences" [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -The Windows Setting APIs enable users and authorized third parties, on behalf of the users, to access their Windows operating system settings data stored in Microsoft cloud. Windows settings data is available in Microsoft cloud only when users enable the feature. The data present for each user varies based on what they choose to backup from the settings. Notably, default values for any given setting remain local and are not uploaded to the cloud. The APIs share only those setting data that has been uploaded to the cloud for the user. +The Windows Setting APIs enable users and authorized third parties, on behalf of the users, to access their Windows operating system settings data stored in Microsoft cloud. Windows settings data is available in Microsoft cloud only when users enable the feature. The data present for each user varies based on what they choose to backup from the settings. Notably, default values for any given setting remain local and aren't uploaded to the cloud. The APIs share only those setting data that has been uploaded to the cloud for the user. ## Windows Settings @@ -138,7 +138,7 @@ In this example, the payloadType `windows.data.fileexplorerclassic.advancedsetti } ``` -It is common for the properties in the object to be a subset of those that are available in the component’s user experience as component owners decide which settings provide the most value when uploaded to the cloud. +It's common for the properties in the object to be a subset of those that are available in the component’s user experience as component owners decide which settings provide the most value when uploaded to the cloud. ### PayloadTypes of particular interest From 454966a8e4037c4c6ee0a2755a30d9b9b2acbfdf Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Thu, 29 Feb 2024 19:08:38 -0700 Subject: [PATCH 29/54] Update windows-setting-api-overview.md --- api-reference/beta/resources/windows-setting-api-overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/beta/resources/windows-setting-api-overview.md b/api-reference/beta/resources/windows-setting-api-overview.md index 5f9c3a49346..c452d0cd8f5 100644 --- a/api-reference/beta/resources/windows-setting-api-overview.md +++ b/api-reference/beta/resources/windows-setting-api-overview.md @@ -1,6 +1,6 @@ --- title: "Microsoft Graph Windows Setting APIs to retrieve Windows OS settings stored in cloud" -description: "The Windows Setting APIs enable users and authorized third parties, on behalf of the users, to access their Windows operating system settings data stored in Microsoft cloud. Windows settings data is available in Microsoft cloud only when users enable the feature. The data present for each user varies based on what they choose to backup from the settings. Notably, default values for any given setting remain local and aren't uploaded to the cloud. The APIs share only those setting data that has been uploaded to the cloud for the user." +description: "The Windows Setting APIs enable users and authorized third parties, on behalf of the users, to access their Windows operating system settings data stored in Microsoft cloud. Windows settings data is available in Microsoft cloud only when users enable the feature. The data present for each user varies based on what they choose to back up from the settings. Notably, default values for any given setting remain local and aren't uploaded to the cloud. The APIs share only those setting data that has been uploaded to the cloud for the user." ms.localizationpriority: medium doc_type: conceptualPageType author: "MS-Arko" @@ -11,7 +11,7 @@ ms.prod: "cross-device-experiences" [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -The Windows Setting APIs enable users and authorized third parties, on behalf of the users, to access their Windows operating system settings data stored in Microsoft cloud. Windows settings data is available in Microsoft cloud only when users enable the feature. The data present for each user varies based on what they choose to backup from the settings. Notably, default values for any given setting remain local and aren't uploaded to the cloud. The APIs share only those setting data that has been uploaded to the cloud for the user. +The Windows Setting APIs enable users and authorized third parties, on behalf of the users, to access their Windows operating system settings data stored in Microsoft cloud. Windows settings data is available in Microsoft cloud only when users enable the feature. The data present for each user varies based on what they choose to back up from the settings. Notably, default values for any given setting remain local and aren't uploaded to the cloud. The APIs share only those setting data that has been uploaded to the cloud for the user. ## Windows Settings From 3ff64456057affd2a85a9bd1397ba2b2dad5389b Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Thu, 29 Feb 2024 19:23:11 -0700 Subject: [PATCH 30/54] Addressed example numbering review comments --- .../beta/api/usersettings-list-windows.md | 35 ++++++++----------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/api-reference/beta/api/usersettings-list-windows.md b/api-reference/beta/api/usersettings-list-windows.md index b17b66c7f43..0511c6fd223 100644 --- a/api-reference/beta/api/usersettings-list-windows.md +++ b/api-reference/beta/api/usersettings-list-windows.md @@ -70,9 +70,9 @@ If the response contains more than one page of data, the response body will cont ## Examples -### Request +### Example 1: Request without any filter -The following example shows a request. +#### Request - -Get a list of Windows settings for the signed-in user. - ``` http GET /me/settings/windows ```` ## Optional query parameters -This method supports the `$filter` OData query parameter to help customize the response. The result can be filtered by `windowsDeviceId` and `settingType` properties. For general information, see [OData query parameters](/graph/query-parameters). +This method supports the `$filter` OData query parameter to help customize the response. For general information, see [OData query parameters](/graph/query-parameters). -1. **`windowsDeviceId`**: A string value that represents the unique identifier of a Windows device. This identifier can be found in the response body. By filtering with `windowsDeviceId`, a filtered list of settings specific to that device can be retrieved. Only equality (`eq`) comparison is supported for this parameter. +You can filter the results by the following properties: -2. **`settingType`**: An enumeration with valid values: `roaming` and `backup`. The `settingType` parameter allows narrowing down the results to settings related to either roaming or backup. Only equality (`eq`) comparison is supported for this parameter. For more information, see [windowssettingtype](../resources/enums.md#windowssettingtype-values). +- **windowsDeviceId**: A string value that represents the unique identifier of a Windows device. This identifier can be found in the response body. When you filter on **windowsDeviceId**, you can get a list of settings specific to that device. Only the equality (`eq`) comparison is supported for this parameter. +- **settingType**: An enumeration with the following valid values: `roaming` and `backup`. The **settingType** property allows you to narrow down the results to settings related to either roaming or backup. Only the equality (`eq`) comparison is supported for this parameter. For more information, see [windowsSettingType](../resources/enums.md#windowssettingtype-values). -Please refer to the [examples](./usersettings-list-windows.md#examples) section below for more information on how to use these query parameters. +For more details about how to use this query parameter, see the [Examples](./usersettings-list-windows.md#examples) section. ## Request headers | Name | Description | | :------------ | :-------------------------------------------------------------------------------------------------------- | | Authorization | Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts). | -| Prefer |Optional. The API supports the *odata.maxpagesize* parameter through this header for pagination purposes. The minimum and maximum valid values for *odata.maxpagesize* are **1** and **200** respectively. If no value is passed, the default value is **110**.| +| Prefer |Optional. This API supports the *odata.maxpagesize* parameter through this header for pagination purposes. The minimum and maximum valid values for *odata.maxpagesize* are **1** and **200** respectively. If no value is passed, the default value is **110**.| ## Request body @@ -65,7 +63,7 @@ Don't supply a request body for this method. If successful, this method returns a `200 OK` response code and a collection of [windowsSetting](../resources/windowssetting.md) objects in the response body. -If the response contains more than one page of data, the response body will contain a `@odata.nextLink` property. This property will contain a URL that can be used to request the next page of data. The URL should be used without any modification. +If the response contains more than one page of data, the response body will contain an `@odata.nextLink` property. This property will contain a URL that can be used to request the next page of data. The URL should be used without any modification. ## Examples @@ -73,7 +71,7 @@ If the response contains more than one page of data, the response body will cont ### Example 1: Request without any filter #### Request - +The following example shows a request. -Get a particular Windows setting for the signed-in user. ``` http GET /me/settings/windows/{windowsSettingId} ``` ## Optional query parameters -N/A +This method doesn't support OData query parameters to customize the response. For general information, see [OData query parameters](/graph/query-parameters). ## Request headers From 860cf832c2f212265252921bf180b90fab2fdd87 Mon Sep 17 00:00:00 2001 From: Laura Graham Date: Tue, 5 Mar 2024 14:05:46 -0800 Subject: [PATCH 40/54] Edits. --- api-reference/beta/api/windowssetting-list-instances.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/api-reference/beta/api/windowssetting-list-instances.md b/api-reference/beta/api/windowssetting-list-instances.md index 131d458b3a7..b46fc99f45a 100644 --- a/api-reference/beta/api/windowssetting-list-instances.md +++ b/api-reference/beta/api/windowssetting-list-instances.md @@ -1,6 +1,6 @@ --- title: "List Windows setting instances" -description: "Get a list of the windowsSettingInstance objects and their properties." +description: "Get a list of windowsSettingInstance objects and their properties." author: "MS-Arko" ms.localizationpriority: medium ms.prod: "cross-device-experiences" @@ -13,7 +13,7 @@ Namespace: microsoft.graph [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -Get a list of the [windowsSettingInstance](../resources/windowssettinginstance.md) objects and their properties. +Get a list of [windowsSettingInstance](../resources/windowssettinginstance.md) objects and their properties for the signed-in user. ## Permissions @@ -32,14 +32,13 @@ Choose the permission or permissions marked as least privileged for this API. Us "blockType": "ignored" } --> -Get a particular Windows setting's instances for the signed-in user. ``` http GET /me/settings/windows/{windowsSettingId}/instances ``` ## Optional query parameters -N/A +This method doesn't support OData query parameters to customize the response. For general information, see [OData query parameters](/graph/query-parameters). ## Request headers From 5a232c9777be698280f5ab23eb89a41fae12532d Mon Sep 17 00:00:00 2001 From: Arkajyoti Paul Date: Tue, 5 Mar 2024 15:07:01 -0700 Subject: [PATCH 41/54] Removed settings api overview page --- .../resources/windows-setting-api-overview.md | 188 ------------------ 1 file changed, 188 deletions(-) delete mode 100644 api-reference/beta/resources/windows-setting-api-overview.md diff --git a/api-reference/beta/resources/windows-setting-api-overview.md b/api-reference/beta/resources/windows-setting-api-overview.md deleted file mode 100644 index cd03374782e..00000000000 --- a/api-reference/beta/resources/windows-setting-api-overview.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: "Microsoft Graph's Windows Setting APIs stored in the cloud" -description: "The Windows setting APIs enable users and authorized third parties, acting on behalf of the users, to retrieve their Windows operating system settings data stored in the Microsoft cloud. The Windows settings data is available in the Microsoft cloud only when users activate the feature. The scope of data available for each user depends on their selections for backup within the settings. The default values for any setting remain local and aren't transferred to the cloud. These APIs only share setting data that has been uploaded to the cloud by the user." -ms.localizationpriority: medium -doc_type: conceptualPageType -author: "MS-Arko" -ms.prod: "cross-device-experiences" ---- - -# Microsoft Graph Windows Setting APIs to retrieve Windows OS settings stored in cloud - -[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] - -The Windows setting APIs enable users and authorized third parties, acting on behalf of the users, to retrieve their Windows operating system settings data stored in the Microsoft cloud. The Windows settings data is available in the Microsoft cloud only when users activate the feature. The scope of data available for each user depends on their selections for backup within the settings. The default values for any setting remain local and aren't transferred to the cloud. These APIs only share setting data that has been uploaded to the cloud by the user." - -## Windows settings - -A [**windowsSetting**](../resources/windowssetting.md) represents various settings from the Windows operating system that are stored in the cloud for a given user. - -There are two types of [windowsSetting](../resources/windowssetting.md): `roaming` and `backup`. The *settingType* property of a [windowsSetting](../resources/windowssetting.md) object indicates the type of the setting. - -| settingType | Description | -| :----------------- | :--------------------------------- | -| roaming | The Windows setting is associated with a user's account. It's consistent across all devices and any changes to the setting value are synced or applied to all Windows devices that the user owns.| -| backup | The Windows setting doesn't roam or sync across devices. This type of setting is used in device backup and restore scenarios.| - - A [windowsSetting](../resources/windowssetting.md) of type `backup` may have a *windowsDeviceId* property that links the setting to a specific device. - - The [List Windows settings](../api/usersettings-list-windows.md) API returns a collection of [windowsSetting](../resources/windowssetting.md) objects and their properties. You can filter the results by *windowsDeviceId* and *settingType* properties. - -The [Get Windows setting](../api/windowssetting-get.md) API allows you to pass the ID of a [windowsSetting](../resources/windowssetting.md) in the URL to read a specific Windows setting object. - -The following JSON representation shows an example of a Windows setting. The instances collection in it represents **Windows setting instances**, elaborated in the next section. - - -``` json -{ - "@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" - } - ] -} -``` - -> Warning:
The structure of the ID of a [**windowsSetting**](../resources/windowssetting.md) is not guaranteed and the caller should not take any dependency on it. The ID should be treated as an opaque string. - -## Windows setting instances - -A [**windowsSettingInstance**](../resources/windowssettinginstance.md) represents a setting instance from the Windows operating system that is stored in the cloud for a given user. A [windowsSettingInstance](../resources/windowssettinginstance.md) belongs to a [windowsSetting](../resources/windowssetting.md). - -The following JSON representation shows an example of a Windows setting instance. - - -``` json -{ - "@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" -} -``` - -The [List Windows setting instances](../api/windowssetting-list-instances.md) API returns a collection of [windowsSettingInstance](../resources/windowssettinginstance.md) objects and their properties. The API requires the ID of a [windowsSetting](../resources/windowssetting.md) in the URL to read the setting instances. - -The [Get Windows setting instance](../api/windowssettinginstance-get.md) API allows you to pass the ID of a [windowsSetting](../resources/windowssetting.md) and [windowsSettingInstance](../resources/windowssettinginstance.md) in the URL to read a specific windows setting instance object. - -The *payload* property of a [**windowsSettingInstance**](../resources/windowssettinginstance.md) contains the actual setting value. The *payload* is a string in Base64 encoded format. The *payloadType* property of the [**windowsSetting**](../resources/windowssetting.md) object indicates the type of the setting value. The *payload* when decoded is a JSON object, which differs from setting to setting and is specific to the *payloadType*. - -## About the *payloadType* property -The *payloadType* defines the structure of a [windowsSettingInstance](./windowssettinginstance.md) payload. There are numerous payloadTypes in Windows, which represent distinct setting structures used by different experiences in the operating system. As Windows evolves, more payloadTypes are created and onboarded to the cloud. Querying the API and exploring the settings available is the best way to learn about the various payloadTypes. The users and admins have control over which settings are uploaded to the cloud and most components don't upload default settings that the user hasn't customized. - -the following example shows a settingsInstance from the API. - -```json -{ - "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 this example, the payloadType `windows.data.fileexplorerclassic.advancedsettings` represents some of the settings that the File Explorer backs up to the cloud. The Base64 payload can be decoded to a UTF-8 string to see the JSON representation of this object. - -**Payload decoded:** -```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 -} -``` - -It's common for the properties in the object to be a subset of those that are available in the component’s user experience as component owners decide which settings provide the most value when uploaded to the cloud. - -### PayloadTypes of particular interest - -Some payloadTypes have a special role in the Windows settings backup process. - -#### windows.data.platform.backuprestore.deviceprofile -Rather than being a setting the user has applied, this type records information about devices that have opted into settings backup features. Two properties in this object are useful for understanding the rest of the settings: *deviceDisplayName* and *profileId*. - -- *deviceDisplayName* is the name of the computer, which can be seen in Windows system settings at "**Start** > **Settings** > **System**". -- *profileId* is an identifier used to link [**windowsSetting**](../resources/windowssetting.md) items to the device that uploaded them. This property corresponds to **windowsSetting.windowsDeviceId** and can be used as a filter to get settings for a specific device from [List Windows settings](../api/usersettings-list-windows.md) API. - -The following example shows this resource type. - -```json -{ - "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" - } - ] -} -``` -**Payload decoded:** - -```json -{ - "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 - -The **backupUnitStore** payloadType settings are unique in that the actual settings value is a **blob** in the data property. This is because **backupUnitStore** settings are collected directly from the Windows registry, on disk files, or other at rest locations throughout Windows. These settings weren't designed to be interoperable with experiences besides the components that created them. However, they have been included in this API for comprehensive coverage of all Windows settings that are stored in the cloud. \ No newline at end of file From e28947017771c4560aa653b8e49f309934656fa9 Mon Sep 17 00:00:00 2001 From: Laura Graham Date: Tue, 5 Mar 2024 14:07:07 -0800 Subject: [PATCH 42/54] Edits. --- api-reference/beta/api/windowssettinginstance-get.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/api-reference/beta/api/windowssettinginstance-get.md b/api-reference/beta/api/windowssettinginstance-get.md index 5812eb9664e..06b26e7b972 100644 --- a/api-reference/beta/api/windowssettinginstance-get.md +++ b/api-reference/beta/api/windowssettinginstance-get.md @@ -1,5 +1,5 @@ --- -title: "Get Windows setting instance" +title: "Get windowsSettingInstance" description: "Read the properties and relationships of a windowsSettingInstance object." author: "MS-Arko" ms.localizationpriority: medium @@ -7,13 +7,13 @@ ms.prod: "cross-device-experiences" doc_type: apiPageType --- -# Get Windows setting instance +# Get windowsSettingInstance Namespace: microsoft.graph [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] -Read the properties and relationships of a [windowsSettingInstance](../resources/windowssettinginstance.md) object by passing the Windows setting ID and Windows setting instance ID in the URL. +Read the properties and relationships of a [windowsSettingInstance](../resources/windowssettinginstance.md) object by passing the Windows setting ID and Windows setting instance ID in the URL. This method gets a **windowsSettingInstance** for the signed-in user. ## Permissions @@ -33,9 +33,6 @@ Choose the permission or permissions marked as least privileged for this API. Us "blockType": "ignored" } --> - -Get a particular Windows setting instance for the signed-in user. - ```http GET /me/settings/windows/{windowsSettingId}/instances/{windowsSettingInstanceId} ``` From 247bea48f559ccf958409397377b1d41b40fa09a Mon Sep 17 00:00:00 2001 From: Laura Graham Date: Tue, 5 Mar 2024 14:08:13 -0800 Subject: [PATCH 43/54] Updated date. --- api-reference/beta/changelog/Microsoft.PDRS.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/beta/changelog/Microsoft.PDRS.json b/api-reference/beta/changelog/Microsoft.PDRS.json index 22730452fab..93c0db7b0f8 100644 --- a/api-reference/beta/changelog/Microsoft.PDRS.json +++ b/api-reference/beta/changelog/Microsoft.PDRS.json @@ -54,9 +54,9 @@ "Id": "af6ceee7-aa8a-4965-80fa-8fa9fd460ad2", "Cloud": "Prod", "Version": "beta", - "CreatedDateTime": "2024-02-08T17:50:40.810248Z", + "CreatedDateTime": "2024-03-05T17:50:40.810248Z", "WorkloadArea": "Cross-device experiences", "SubArea": "" } ] -} \ No newline at end of file +} From 7551f5d3cd92f7b72d30c947fb41724100f28f6f Mon Sep 17 00:00:00 2001 From: Laura Graham Date: Tue, 5 Mar 2024 14:16:03 -0800 Subject: [PATCH 44/54] Edits. --- api-reference/beta/resources/usersettings.md | 44 ++++++++++---------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/api-reference/beta/resources/usersettings.md b/api-reference/beta/resources/usersettings.md index 03a6a2ead75..a57207dde76 100644 --- a/api-reference/beta/resources/usersettings.md +++ b/api-reference/beta/resources/usersettings.md @@ -19,35 +19,37 @@ Settings that represent a user’s preferences for the following: - [Item insights](../resources/officegraphinsights.md) - [Regional locale and languages](../resources/regionalandlanguagesettings.md) - [Shift scheduling](../resources/shiftpreferences.md) -- [Suggestions to merge duplicate contacts](../resources/contactmergesuggestions.md). +- [Suggestions to merge duplicate contacts](../resources/contactmergesuggestions.md) + +This resource type provides access to the following operations. Manage Delve accessibility: - - Checking whether a user and the user's organization have access to Office Delve. - - Disabling or enabling documents in Office Delve for specific users. + - Determine whether a user and the user's organization have access to Office Delve. + - Disable or enable documents in Office Delve for specific users. -Configure the visibility of [itemInsights](../resources/iteminsights.md) and [meeting hours insights](https://support.microsoft.com/office/update-your-meeting-hours-using-the-profile-card-0613d113-d7c1-4faa-bb11-c8ba30a78ef1). ItemInsights are derived between users and other items (such as documents or sites) in Microsoft 365: - - Checking whether a user's item and meeting hours insights are enabled. - - Disabling or enabling item and meeting hours insights for specific user. +Configure the visibility of [itemInsights](../resources/iteminsights.md) and [meeting hours insights](https://support.microsoft.com/office/update-your-meeting-hours-using-the-profile-card-0613d113-d7c1-4faa-bb11-c8ba30a78ef1). Item insights are derived between users and other items (such as documents or sites) in Microsoft 365: + - Determine whether a user's item and meeting hours insights are enabled. + - Disable or enable item and meeting hours insights for specific user. Manage user's locale-based preferences: - - Determining what language and regional formatting a user prefers to view applications with. - - Updating a user's language and regional formatting preferences. + - Determine what language and regional formatting a user prefers to view applications with. + - Update a user's language and regional formatting preferences. -Manage user's work shift preferences: - - Checking whether a user can be assigned to shifts in a schedule. - - Updating a user's shift preferences. +Manage users' work shift preferences: + - Determine whether a user can be assigned to shifts in a schedule. + - Update a user's shift preferences. Configure [contactMergeSuggestions](../resources/contactmergesuggestions.md): - - Determining whether suggestion to merge duplicate contacts for a user is enabled. - - Disabling or enabling suggestion to merge duplicate contacts for a user. + - Determine whether suggestions to merge duplicate contacts for a user is enabled. + - Disable or enable suggestions to merge duplicate contacts for a user. -Export user's Windows settings and values stored in a cloud. +Export users' Windows settings and values stored in a cloud: - Get a list of the user's [windowsSetting](../resources/windowssetting.md) objects. - - Get a filtered list of the user's [windowsSetting](../resources/windowssetting.md) objects by passing, - - [windowssettingtype](../resources/enums.md#windowssettingtype-values) in the filter query. - - [windowsDeviceId](../resources/windowssetting.md#properties) in the filter query. + - Get a filtered list of the user's [windowsSetting](../resources/windowssetting.md) objects by passing one of the following in the filter query: + - [windowssettingtype](../resources/enums.md#windowssettingtype-values) + - [windowsDeviceId](../resources/windowssetting.md#properties) -Inherits from [entity](entity.md). To learn how to get or update user settings, see [Get settings](../api/usersettings-get.md) and [Update settings](../api/usersettings-update.md). +Inherits from [entity](entity.md). > [!NOTE] > This endpoint works only with the [user](user.md) resource. @@ -57,7 +59,7 @@ Inherits from [entity](entity.md). To learn how to get or update user settings, |:---------------|:--------|:----------| |[Get user settings](../api/usersettings-get.md) |[userSettings](../resources/usersettings.md)| Get the user and organization settings. | |[Update user settings](../api/usersettings-update.md) |[userSettings](../resources/usersettings.md)| Update the user current settings. | -|[List windows settings](../api/usersettings-list-windows.md)|[windowsSetting](../resources/windowssetting.md) collection|Get the windowsSetting resources from the windows navigation property.| +|[List Windows settings](../api/usersettings-list-windows.md)|[windowsSetting](../resources/windowssetting.md) collection|Get the **windowsSetting** objects and their properties for the signed in user.| ## Properties @@ -75,12 +77,12 @@ Inherits from [entity](entity.md). To learn how to get or update user settings, |itemInsights|[userInsightsSettings](userinsightssettings.md)| The user's settings for the visibility of meeting hour insights, and insights derived between a user and other items in Microsoft 365, such as documents or sites. [Get userInsightsSettings](../api/userinsightssettings-get.md) through this navigation property. | |regionalAndLanguageSettings|[regionalAndLanguageSettings](regionalandlanguagesettings.md)| The user's preferences for languages, regional locale and date/time formatting. | |shiftPreferences|[shiftPreferences](shiftpreferences.md)| The shift preferences for the user. | -|windows|[windowsSetting](../resources/windowssetting.md) collection|The Windows settings of the user stored in cloud.| +|windows|[windowsSetting](../resources/windowssetting.md) collection|The Windows settings of the user stored in the cloud.| ## JSON representation -Here is a JSON representation of the resource. +The following JSON representation shows the resource type.