author | description | ms.date | title | ms.localizationpriority | doc_type | ms.subservice |
---|---|---|---|---|---|---|
spgraph-docs-team |
Access a shared DriveItem or a collection of shared items by using a shareId or sharing URL. |
09/10/2017 |
Access shared items |
medium |
apiPageType |
onedrive |
Namespace: microsoft.graph
Access a shared DriveItem or a collection of shared items by using a shareId or sharing URL.
To use a sharing URL with this API, your app needs to transform the URL into a sharing token.
[!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]
GET /shares/{shareIdOrEncodedSharingUrl}
Parameter Name | Value | Description |
---|---|---|
shareIdOrEncodedSharingUrl | string |
Required. A sharing token as returned by the API or a properly encoded sharing URL. |
To encode a sharing URL, use the following logic:
- First, use base64 encode the URL.
- Convert the base64 encoded result to unpadded base64url format by removing
=
characters from the end of the value, replacing/
with_
and+
with-
.) - Append
u!
to be beginning of the string.
As an example, to encode a URL in C#:
string sharingUrl = "https://onedrive.live.com/redir?resid=1231244193912!12&authKey=1201919!12921!1";
string base64Value = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(sharingUrl));
string encodedUrl = "u!" + base64Value.TrimEnd('=').Replace('/','_').Replace('+','-');
Name | Type | Description |
---|---|---|
Prefer | string | Optional. Set to one of the prefer values documented below. |
Name | Description |
---|---|
redeemSharingLink | If the shareIdOrEncodedSharingUrl is a sharing link, grant the caller durable access to the item |
redeemSharingLinkIfNecessary | Same as redeemSharingLink, but access is only guaranteed to be granted for the duration of this request |
redeemSharingLink should be considered equivalent to the caller navigating to the sharing link the browser (accepting the sharing gesture), whereas redeemSharingLinkIfNecessary is intended for scenarios where the intention is simply to peek at the link's metadata.
If successful, this method returns a 200 OK
response code and a sharedDriveItem resource in the response body.
The following example shows a request to retrieve a shared item:
GET /shares/{shareIdOrEncodedSharingUrl}
[!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]
The following example shows the response.
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "B64397C8-07AE-43E4-920E-32BFB4331A5B",
"name": "contoso project.docx",
"owner": {
"user": {
"id": "98E88F1C-F8DC-47CC-A406-C090248B30E5",
"displayName": "Ryan Gregg"
}
}
}
While the SharedDriveItem contains some useful information, most apps will want to directly access the shared DriveItem. The SharedDriveItem resource includes a root and items relationships that can access content within the scope of the shared item.
By requesting the driveItem relationship, the DriveItem that was shared will be returned.
GET /shares/{shareIdOrUrl}/driveItem
[!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 200 OK
Content-Type: application/json
{
"id": "9FFFDB3C-5B87-4062-9606-1B008CA88E44",
"name": "contoso project.docx",
"eTag": "2246BD2D-7811-4660-BD0F-1CF36133677B,1",
"file": {},
"size": 109112
}
By requesting the driveItem relationship and expanding the children collection, the DriveItem that was shared will be returned along with the files within the shared folder.
GET /shares/{shareIdOrUrl}/driveItem?$expand=children
[!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 200 OK
Content-Type: application/json
{
"id": "9FFFDB3C-5B87-4062-9606-1B008CA88E44",
"name": "Contoso Project",
"eTag": "2246BD2D-7811-4660-BD0F-1CF36133677B,1",
"folder": {},
"size": 10911212,
"children": [
{
"id": "AFBBDD79-868E-452D-AD4D-24697D4A4044",
"name": "Propsoal.docx",
"file": {},
"size": 19001
},
{
"id": "A91FE90A-2F2C-4EE6-B412-C4FFBA3F71A6",
"name": "Update to Proposal.docx",
"file": {},
"size": 91001
}
]
}
Read the Error Responses article for more information about how errors are returned.
- For OneDrive for Business and SharePoint, the Shares API always requires authentication and can't be used to access anonymously shared content without a user context.