github.com/rclone/rclone@v1.66.1-0.20240517100346-7b89735ae726/backend/onedrive/metadata.md (about)

     1  OneDrive supports System Metadata (not User Metadata, as of this writing) for
     2  both files and directories. Much of the metadata is read-only, and there are some
     3  differences between OneDrive Personal and Business (see table below for
     4  details).
     5  
     6  Permissions are also supported, if `--onedrive-metadata-permissions` is set. The
     7  accepted values for `--onedrive-metadata-permissions` are "`read`", "`write`",
     8  "`read,write`", and "`off`" (the default). "`write`" supports adding new permissions,
     9  updating the "role" of existing permissions, and removing permissions. Updating
    10  and removing require the Permission ID to be known, so it is recommended to use
    11  "`read,write`" instead of "`write`" if you wish to update/remove permissions.
    12  
    13  Permissions are read/written in JSON format using the same schema as the
    14  [OneDrive API](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/resources/permission?view=odsp-graph-online),
    15  which differs slightly between OneDrive Personal and Business.
    16  
    17  Example for OneDrive Personal:
    18  ```json
    19  [
    20  	{
    21  		"id": "1234567890ABC!123",
    22  		"grantedTo": {
    23  			"user": {
    24  				"id": "ryan@contoso.com"
    25  			},
    26  			"application": {},
    27  			"device": {}
    28  		},
    29  		"invitation": {
    30  			"email": "ryan@contoso.com"
    31  		},
    32  		"link": {
    33  			"webUrl": "https://1drv.ms/t/s!1234567890ABC"
    34  		},
    35  		"roles": [
    36  			"read"
    37  		],
    38  		"shareId": "s!1234567890ABC"
    39  	}
    40  ]
    41  ```
    42  
    43  Example for OneDrive Business:
    44  ```json
    45  [
    46  	{
    47  		"id": "48d31887-5fad-4d73-a9f5-3c356e68a038",
    48  		"grantedToIdentities": [
    49  			{
    50  				"user": {
    51  					"displayName": "ryan@contoso.com"
    52  				},
    53  				"application": {},
    54  				"device": {}
    55  			}
    56  		],
    57  		"link": {
    58  			"type": "view",
    59  			"scope": "users",
    60  			"webUrl": "https://contoso.sharepoint.com/:w:/t/design/a577ghg9hgh737613bmbjf839026561fmzhsr85ng9f3hjck2t5s"
    61  		},
    62  		"roles": [
    63  			"read"
    64  		],
    65  		"shareId": "u!LKj1lkdlals90j1nlkascl"
    66  	},
    67  	{
    68  		"id": "5D33DD65C6932946",
    69  		"grantedTo": {
    70  			"user": {
    71  				"displayName": "John Doe",
    72  				"id": "efee1b77-fb3b-4f65-99d6-274c11914d12"
    73  			},
    74  			"application": {},
    75  			"device": {}
    76  		},
    77  		"roles": [
    78  			"owner"
    79  		],
    80  		"shareId": "FWxc1lasfdbEAGM5fI7B67aB5ZMPDMmQ11U"
    81  	}
    82  ]
    83  ```
    84  
    85  To write permissions, pass in a "permissions" metadata key using this same
    86  format. The [`--metadata-mapper`](https://rclone.org/docs/#metadata-mapper) tool can
    87  be very helpful for this.
    88  
    89  When adding permissions, an email address can be provided in the `User.ID` or
    90  `DisplayName` properties of `grantedTo` or `grantedToIdentities`. Alternatively,
    91  an ObjectID can be provided in `User.ID`. At least one valid recipient must be
    92  provided in order to add a permission for a user. Creating a Public Link is also
    93  supported, if `Link.Scope` is set to `"anonymous"`.
    94  
    95  Example request to add a "read" permission with `--metadata-mapper`:
    96  
    97  ```json
    98  {
    99      "Metadata": {
   100          "permissions": "[{\"grantedToIdentities\":[{\"user\":{\"id\":\"ryan@contoso.com\"}}],\"roles\":[\"read\"]}]"
   101      }
   102  }
   103  ```
   104  
   105  Note that adding a permission can fail if a conflicting permission already
   106  exists for the file/folder.
   107  
   108  To update an existing permission, include both the Permission ID and the new
   109  `roles` to be assigned. `roles` is the only property that can be changed.
   110  
   111  To remove permissions, pass in a blob containing only the permissions you wish
   112  to keep (which can be empty, to remove all.) Note that the `owner` role will be
   113  ignored, as it cannot be removed.
   114  
   115  Note that both reading and writing permissions requires extra API calls, so if
   116  you don't need to read or write permissions it is recommended to omit
   117  `--onedrive-metadata-permissions`.
   118  
   119  Metadata and permissions are supported for Folders (directories) as well as
   120  Files. Note that setting the `mtime` or `btime` on a Folder requires one extra
   121  API call on OneDrive Business only.
   122  
   123  OneDrive does not currently support User Metadata. When writing metadata, only
   124  writeable system properties will be written -- any read-only or unrecognized keys
   125  passed in will be ignored.
   126  
   127  TIP: to see the metadata and permissions for any file or folder, run:
   128  
   129  ```
   130  rclone lsjson remote:path --stat -M --onedrive-metadata-permissions read
   131  ```