Permission resource type
Namespace: microsoft.graph
The Permission resource provides information about a sharing permission granted for a DriveItem resource.
Sharing permissions have many different forms. The permission resource represents these different forms through facets on the resource.
OneDrive for Business and SharePoint document libraries don't return the inheritedFrom property. grantedTo and grantedToIdentities are deprecated going forward and the response will be migrated to grantedToV2 and grantedToIdentitiesV2 respectively under appropriate property names.
JSON representation
The following JSON representation shows the resource type.
{
"id": "string (identifier)",
"grantedTo": {"@odata.type": "microsoft.graph.identitySet"},
"grantedToIdentities": [{"@odata.type": "microsoft.graph.identitySet"}],
"grantedToV2": {"@odata.type": "microsoft.graph.sharePointIdentitySet"},
"grantedToIdentitiesV2": [{"@odata.type": "microsoft.graph.sharePointIdentitySet"}],
"inheritedFrom": {"@odata.type": "microsoft.graph.itemReference"},
"invitation": {"@odata.type": "microsoft.graph.sharingInvitation"},
"link": {"@odata.type": "microsoft.graph.sharingLink"},
"roles": ["string"],
"shareId": "string",
"expirationDateTime": "string (timestamp)",
"hasPassword": "boolean"
}
Properties
Property | Type | Description |
---|---|---|
expirationDateTime | DateTimeOffset | A format of yyyy-MM-ddTHH:mm:ssZ of DateTimeOffset indicates the expiration time of the permission. DateTime.MinValue indicates there's no expiration set for this permission. Optional. |
id | String | The unique identifier of the permission among all permissions on the item. Read-only. |
hasPassword | Boolean | Indicates whether the password is set for this permission. This property only appears in the response. Optional. Read-only. For OneDrive Personal only.. |
grantedTo (deprecated) | IdentitySet | For user type permissions, the details of the users and applications for this permission. Read-only. |
grantedToIdentities (deprecated) | Collection(IdentitySet) | For type permissions, the details of the users to whom permission was granted. Read-only. |
grantedToIdentitiesV2 | Collection(SharePointIdentitySet) | For link type permissions, the details of the users to whom permission was granted. Read-only. |
grantedToV2 | SharePointIdentitySet | For user type permissions, the details of the users and applications for this permission. Read-only. |
inheritedFrom | ItemReference | Provides a reference to the ancestor of the current permission, if it's inherited from an ancestor. Read-only. |
invitation | SharingInvitation | Details of any associated sharing invitation for this permission. Read-only. |
link | SharingLink | Provides the link details of the current permission, if it's a link type permission. Read-only. |
roles | Collection of String | The type of permission, for example, read . See below for the full list of roles. Read-only. |
shareId | String | A unique token that can be used to access this shared item via the shares API. Read-only. |
The permission resource uses facets to provide information about the kind of permission represented by the resource.
Permissions with a link facet represent sharing links created on the item. Sharing links contain a unique token that provides access to the item for anyone with the link.
Permissions with an invitation facet represent permissions added by inviting specific users or groups to have access to the file.
Roles property values
Value | Description |
---|---|
read | Provides the ability to read the metadata and contents of the item. |
write | Provides the ability to read and modify the metadata and contents of the item. |
owner | For SharePoint and OneDrive for Business this represents the owner role. |
Sharing links
The most common type of permissions is sharing links. Sharing links provide a unique URL that includes both the resource being shared and an authentication token that provides access to the resource. Users don't need to sign-in to access the content shared with a sharing link. Users can share a link that gives read-only access to the content or writable access to the content.
View Link
A view link provides read-only access to an item.
{
"id": "1",
"roles": ["read"],
"link": {
"type": "view",
"webUrl": "https://onedrive.live.com/redir?resid=5D33DD65C6932946!70859&authkey=!AL7N1QAfSWcjNU8&ithint=folder%2cgif",
"application": { "id": "1234", "displayName": "Sample Application" }
},
"shareId": "!LKj1lkdlals90j1nlkascl",
"expirationDateTime": "0001-01-01T00:00:00Z"
}
Edit link
An edit link provides read and write access to an item.
{
"id": "2",
"roles": ["write"],
"link": {
"type": "edit",
"webUrl": "https://onedrive.live.com/redir?resid=5D33DD65C6932946!70859&authkey=!AL7N1QAfSWcjNU8&ithint=folder%2cgif",
"application": { "id": "1234", "displayName": "Sample Application" }
},
"shareId": "!LKj1lkdlals90j1nlkascl",
"expirationDateTime": "0001-01-01T00:00:00Z"
}
Specific people link
This link provides read and write access to the specific people in the grantedToIdentities
collection.
{
"id": "3",
"grantedToIdentities": [
{
"user": {
"id": "35fij1974gb8832",
"displayName": "Misty Suarez"
}
},
{
"user": {
"id": "9397721fh4hgh73",
"displayName": "Judith Clemons"
}
}
],
"grantedToIdentitiesV2": [
{
"user": {
"id": "35fij1974gb8832",
"displayName": "Misty Suarez"
},
"siteUser": {
"id": "1",
"displayName": "Misty Suarez",
"loginName": "Misty Suarez"
}
},
{
"user": {
"id": "9397721fh4hgh73",
"displayName": "Judith Clemons"
},
"siteUser": {
"id": "2",
"displayName": "Judith Clemons",
"loginName": "Judith Clemons"
}
}
],
"roles": ["write"],
"link": {
"webUrl": "https://contoso.sharepoint.com/:w:/t/design/a577ghg9hgh737613bmbjf839026561fmzhsr85ng9f3hjck2t5s",
"application": { "id": "1234", "displayName": "Sample Application" }
},
"shareId": "!LKj1lkdlals90j1nlkascl",
"expirationDateTime": "0001-01-01T00:00:00Z"
}
Existing access link
This link doesn't grant any extra privileges to the user.
{
"id": "00000000-0000-0000-0000-000000000000",
"roles": ["read"],
"link": {
"scope": "existingAccess",
"type": "view",
"webUrl": "https://contoso.sharepoint.com/:w:/t/design/Shared%20Documents/SampleDoc.docx?d=w12345",
},
"expirationDateTime": "0001-01-01T00:00:00Z"
}
Sharing Invitation
In addition to creating sharing links, a user can be invited by e-mail address. In this scenario, the permission creates an invitation that is sent to the user's email.
Invitation to an email address
If the permission was sent via an email address to a recipient who doesn't have a matching account, the grantedTo property may not be set until the invitation is redeemed, which occurs the first time a user select the link and signs in.
{
"id": "1",
"roles": ["write"],
"invitation": {
"email": "jd@contoso.com",
"signInRequired": true
},
"shareId": "FWxc1lasfdbEAGM5fI7B67aB5ZMPDMmQ11U",
"expirationDateTime": "0001-01-01T00:00:00Z"
}
After the sharing invitation has been redeemed by a user, the grantedTo property will contain the information about the account that redeemed the permissions:
{
"id": "1",
"roles": ["write"],
"grantedTo": {
"user": {
"id": "5D33DD65C6932946",
"displayName": "Robin Danielsen"
}
},
"grantedToV2": {
"user": {
"id": "5D33DD65C6932946",
"displayName": "Robin Danielsen"
},
"siteUser": {
"id": "1",
"displayName": "Robin Danielsen",
"loginName": "Robin Danielsen"
}
},
"invitation": {
"email": "rd@contoso.com",
"signInRequired": true
},
"shareId": "FWxc1lasfdbEAGM5fI7B67aB5ZMPDMmQ11U",
"expirationDateTime": "0001-01-01T00:00:00Z"
}
Methods
Method | REST Path |
---|---|
List permissions | GET /drive/items/{item-id}/permissions |
Get permission | GET /drive/items/{item-id}/permissions/{id} |
Add permissions | POST /drive/items/{item-id}/invite |
Update permission | PATCH /drive/items/{item-id}/permissions/{id} |
Delete permission | DELETE /drive/items/{item-id}/permissions/{id} |
Grant access to sharing link | POST /shares/{encoded-sharing-url}/permission/grant |
Palaute
https://aka.ms/ContentUserFeedback.
Tulossa pian: Vuoden 2024 aikana poistamme asteittain GitHub Issuesin käytöstä sisällön palautemekanismina ja korvaamme sen uudella palautejärjestelmällä. Lisätietoja on täällä:Lähetä ja näytä palaute kohteelle