title | description | author | ms.localizationpriority | ms.subservice | doc_type |
---|---|---|---|---|---|
listItem: createLink |
Create a link to share a listItem |
learafa |
medium |
sharepoint |
apiPageType |
Namespace: microsoft.graph
[!INCLUDE beta-disclaimer]
Create a sharing link for a listItem.
The createLink action creates a new sharing link if the specified link type doesn't already exist for the calling application. If a sharing link of the specified type already exists for the app, this action returns the existing sharing link.
listItem resources inherit sharing permissions from the list the item resides in.
[!INCLUDE national-cloud-support]
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. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
[!INCLUDE permissions-table]
POST /sites/{siteId}/lists/{listId}/items/{itemId}/createLink
Name | Description |
---|---|
Authorization | Bearer {token}. Required. Learn more about authentication and authorization. |
Content-Type | application/json. Required. |
In the request body, provide a JSON representation of the parameters.
The following table shows the parameters that can be used with this action.
Property | Type | Description |
---|---|---|
type | String | The type of sharing link to create. Optional. |
scope | String | The scope of link to create. Either anonymous , organization or users . Optional. |
expirationDateTime | DateTimeOffset | A string with format of yyyy-MM-ddTHH:mm:ssZ of DateTime indicates the expiration time of the permission. Optional. |
password | String | The password of the sharing link that is set by the creator. Optional. |
recipients | driveRecipient collection | A collection of recipients who will receive access to the sharing link. Optional. |
retainInheritedPermissions | Boolean | Optional. If true (default), any existing inherited permissions are retained on the shared item when sharing this item for the first time. If false , all existing permissions are removed when sharing for the first time. |
sendNotification | Boolean | If true , this method sends a sharing link in an email to users specified in recipients . Applicable to OneDrive for Business and SharePoint. The default value is false . Optional. |
The following values are allowed for the type parameter.
Type value | Description |
---|---|
view | Creates a read-only link to the item. |
review | Creates a review link to the item. This option is only available for files in OneDrive for Business and SharePoint. |
edit | Creates a read-write link to the item. |
embed | Creates an embeddable link to the item. |
blocksDownload | Creates a read-only link that blocks download to the item. This option is only available for files in OneDrive for Business and SharePoint. |
createOnly | Creates an upload-only link to the item. This option is only available for folders in OneDrive for Business and SharePoint. |
addressBar | Creates the default link that is shown in the browser address bars for newly created files. Only available in OneDrive for Business and SharePoint. The organization admin configures whether this link type is supported, and what features are supported by this link type. |
adminDefault | Creates the default link to the item as determined by the administrator of the organization. Only available in OneDrive for Business and SharePoint. The policy is enforced for the organization by the admin |
The following values are allowed for the scope parameter.
Value | Description |
---|---|
anonymous | Anyone with the link has access, without needing to sign in. This may include people outside of your organization. Anonymous link support may be disabled by an administrator. |
organization | Anyone signed into your organization (tenant) can use the link to get access. Only available in OneDrive for Business and SharePoint. |
users | Specific people in the recipients collection can use the link to get access. Only available in OneDrive for Business and SharePoint. |
If successful, this method returns a single permission resource in the response body that represents the requested sharing permissions.
The response is 201 Created
if a new sharing link is created for the listItem or 200 OK
if an existing link is returned.
The following example requests a sharing link to be created for the listItem specified by {itemId} in the list specified {listId}.
The sharing link is configured to be read-only and usable by anyone with the link.
For OneDrive for Business and SharePoint users, use the sendNotification
parameter to create a sharing link. The sharingLink
is then sent to recipients via email.
All existing permissions are removed when sharing for the first time if retainInheritedPermissions
is false.
POST https://graph.microsoft.com/beta/sites/{siteId}/lists/{listId}/items/{itemId}/createLink
Content-Type: application/json
{
"type": "view",
"scope": "anonymous",
"password": "String",
"recipients": [
{
"@odata.type": "microsoft.graph.driveRecipient"
}
],
"sendNotification": true,
"retainInheritedPermissions": false
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "123ABC",
"roles": ["write"],
"link": {
"type": "view",
"scope": "anonymous",
"webUrl": "https://1drv.ms/A6913278E564460AA616C71B28AD6EB6",
"application": {
"id": "1234",
"displayName": "Sample Application"
},
},
"hasPassword": true
}
OneDrive for Business and SharePoint support company sharable links.
These links are similar to anonymous links, except they only work for members of the owning organization.
To create a company sharable link, use the scope parameter with a value of organization
.
POST https://graph.microsoft.com/beta/sites/{siteId}/lists/{listId}/items/{itemId}/createLink
Content-Type: application/json
{
"type": "edit",
"scope": "organization"
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "123ABC",
"roles": ["write"],
"link": {
"type": "edit",
"scope": "organization",
"webUrl": "https://contoso-my.sharepoint.com/personal/ellen_contoso_com/...",
"application": {
"id": "1234",
"displayName": "Sample Application"
},
}
}
When you use the embed
link type, the webUrl returned can be embedded in an <iframe>
HTML element.
When an embed link is created, the webHtml
property contains the HTML code for an <iframe>
to host the content.
Note: Embed links are only supported for OneDrive personal.
POST https://graph.microsoft.com/beta/sites/{siteId}/lists/{listId}/items/{itemId}/createLink
Content-Type: application/json
{
"type": "embed"
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "123ABC",
"roles": ["read"],
"link": {
"type": "embed",
"webHtml": "<IFRAME src=\"https://onedrive.live.com/...\"></IFRAME>",
"webUrl": "https://onedive.live.com/...",
"application": {
"id": "1234",
"displayName": "Sample Application"
},
}
}
- To create a link based on the organization's default policy and the caller's permissions on the listItem, omit the scope and type parameters
- Links created using this action don't expire unless a default expiration policy is enforced for the organization.
- Links are visible in the sharing permissions for the listItem and can be removed by an owner of the listItem.
- Links always point to the current version of a listItem unless the listItem is checked out (SharePoint only).