Accessing shared DriveItems

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.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type	Permissions (from least to most privileged)
Delegated (work or school account)	Files.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.All
Delegated (personal Microsoft account)	Files.ReadWrite, Files.ReadWrite.All
Application	Files.ReadWrite.All, Sites.ReadWrite.All

HTTP request

GET /shares/{shareIdOrEncodedSharingUrl}

Path parameters

Parameter Name	Value	Description
shareIdOrEncodedSharingUrl	string	Required. A sharing token as returned by the API or a properly encoded sharing URL.

Encoding sharing URLs

To encode a sharing URL, use the following logic:

1. First, use base64 encode the URL.
2. Convert the base64 encoded result to unpadded base64url format by removing = characters from the end of the value, replacing / with _ and + with -.)
3. 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('+','-');

Optional request headers

Name	Type	Description
Prefer	string	Optional. Set to one of the prefer values documented below.

Prefer header values

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.

Response

If successful, this method returns a 200 OK response code and a sharedDriveItem resource in the response body.

Example

Request

Here is an example of the request to retrieve a shared item:

HTTP

GET /shares/{shareIdOrEncodedSharingUrl}

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var sharedDriveItem = await graphClient.Shares["{sharedDriveItem-id}"]
	.Request()
	.GetAsync();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let sharedDriveItem = await client.api('/shares/{shareIdOrEncodedSharingUrl}')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

SharedDriveItem sharedDriveItem = graphClient.shares("{shareIdOrEncodedSharingUrl}")
	.buildRequest()
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)


result, err := graphClient.SharesById("sharedDriveItem-id").Get(context.Background(), nil)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Files

Get-MgShareSharedDriveItemSharedDriveItem -SharedDriveItemId $sharedDriveItemId

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);


$requestResult = $graphServiceClient->sharesById('sharedDriveItem-id')->get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Here is an example of 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"
    }
  }
}

Access the shared item directly

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 which can access content within the scope of the shared item.

Example (single file)

Request

By requesting the driveItem relationship, the DriveItem that was shared will be returned.

HTTP

GET /shares/{shareIdOrUrl}/driveItem

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var driveItem = await graphClient.Shares["{sharedDriveItem-id}"].DriveItem
	.Request()
	.GetAsync();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let driveItem = await client.api('/shares/{shareIdOrUrl}/driveItem')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

DriveItem driveItem = graphClient.shares("{shareIdOrUrl}").driveItem()
	.buildRequest()
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)


result, err := graphClient.SharesById("sharedDriveItem-id").DriveItem().Get(context.Background(), nil)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Files

Get-MgShareDriveItem -SharedDriveItemId $sharedDriveItemId

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);


$requestResult = $graphServiceClient->sharesById('sharedDriveItem-id')->driveItem()->get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

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
}

Example (shared folder)

Request

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.

HTTP

GET /shares/{shareIdOrUrl}/driveItem?$expand=children

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var driveItem = await graphClient.Shares["{sharedDriveItem-id}"].DriveItem
	.Request()
	.Expand("children")
	.GetAsync();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let driveItem = await client.api('/shares/{shareIdOrUrl}/driveItem')
	.expand('children')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

DriveItem driveItem = graphClient.shares("{shareIdOrUrl}").driveItem()
	.buildRequest()
	.expand("children")
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &graphconfig.DriveItemRequestBuilderGetQueryParameters{
	Expand: [] string {"children"},
}
configuration := &graphconfig.DriveItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.SharesById("sharedDriveItem-id").DriveItem().Get(context.Background(), configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Files

Get-MgShareDriveItem -SharedDriveItemId $sharedDriveItemId -ExpandProperty "children" 

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new DriveItemRequestBuilderGetRequestConfiguration();

$queryParameters = new DriveItemRequestBuilderGetQueryParameters();
$queryParameters->expand = ["children"];

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->sharesById('sharedDriveItem-id')->driveItem()->get($requestConfiguration);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

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
    }
  ]
}

Error Responses

Read the Error Responses topic for more information about how errors are returned.

Remarks

• For OneDrive for Business and SharePoint, the Shares API always requires authentication and cannot be used to access anonymously shared content without a user context.