Accessing shared DriveItems

Article
2023-08-23

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.

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	✅

Permissions

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.

Permission type	Least privileged permissions	Higher privileged permissions
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.

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('+','-');

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

The following example shows a request to retrieve a shared item:

GET /shares/{shareIdOrEncodedSharingUrl}


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Shares["{sharedDriveItem-id}"].GetAsync();

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

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



mgc-beta shares get --shared-drive-item-id {sharedDriveItem-id}

Important

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



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
shares, err := graphClient.Shares().BySharedDriveItemId("sharedDriveItem-id").Get(context.Background(), nil)

Important

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


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

SharedDriveItem result = graphClient.shares().bySharedDriveItemId("{sharedDriveItem-id}").get();

Important

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


const options = {
	authProvider,
};

const client = Client.init(options);

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

Important

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


<?php
use Microsoft\Graph\Beta\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->shares()->bySharedDriveItemId('sharedDriveItem-id')->get()->wait();

Important

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


Import-Module Microsoft.Graph.Beta.Files

Get-MgBetaShareSharedDriveItemSharedDriveItem -SharedDriveItemId $sharedDriveItemId

Important

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


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.shares.by_shared_drive_item_id('sharedDriveItem-id').get()

Important

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

Response

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

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 that 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.

GET /shares/{shareIdOrUrl}/driveItem


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Shares["{sharedDriveItem-id}"].DriveItem.GetAsync();

Important

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



mgc-beta shares drive-item get --shared-drive-item-id {sharedDriveItem-id}

Important

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



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
driveItem, err := graphClient.Shares().BySharedDriveItemId("sharedDriveItem-id").DriveItem().Get(context.Background(), nil)

Important

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


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DriveItem result = graphClient.shares().bySharedDriveItemId("{sharedDriveItem-id}").driveItem().get();

Important

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


const options = {
	authProvider,
};

const client = Client.init(options);

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

Important

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


<?php
use Microsoft\Graph\Beta\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->shares()->bySharedDriveItemId('sharedDriveItem-id')->driveItem()->get()->wait();

Important

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


Import-Module Microsoft.Graph.Beta.Files

Get-MgBetaShareDriveItem -SharedDriveItemId $sharedDriveItemId

Important

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


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.shares.by_shared_drive_item_id('sharedDriveItem-id').drive_item.get()

Important

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.

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Shares["{sharedDriveItem-id}"].DriveItem.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Expand = new string []{ "children" };
});

Important

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



mgc-beta shares drive-item get --shared-drive-item-id {sharedDriveItem-id} --expand "children"

Important

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



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphshares "github.com/microsoftgraph/msgraph-beta-sdk-go/shares"
	  //other-imports
)

requestParameters := &graphshares.ItemDriveItemRequestBuilderGetQueryParameters{
	Expand: [] string {"children"},
}
configuration := &graphshares.ItemDriveItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
driveItem, err := graphClient.Shares().BySharedDriveItemId("sharedDriveItem-id").DriveItem().Get(context.Background(), configuration)

Important

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


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DriveItem result = graphClient.shares().bySharedDriveItemId("{sharedDriveItem-id}").driveItem().get(requestConfiguration -> {
	requestConfiguration.queryParameters.expand = new String []{"children"};
});

Important

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


const options = {
	authProvider,
};

const client = Client.init(options);

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

Important

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


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Shares\Item\DriveItem\DriveItemRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DriveItemRequestBuilderGetRequestConfiguration();
$queryParameters = DriveItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->expand = ["children"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->shares()->bySharedDriveItemId('sharedDriveItem-id')->driveItem()->get($requestConfiguration)->wait();

Important

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


Import-Module Microsoft.Graph.Beta.Files

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

Important

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


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.shares.item.drive_item.drive_item_request_builder import DriveItemRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = DriveItemRequestBuilder.DriveItemRequestBuilderGetQueryParameters(
		expand = ["children"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.shares.by_shared_drive_item_id('sharedDriveItem-id').drive_item.get(request_configuration = request_configuration)

Important

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 article for more information about how errors are returned.

Remarks

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.

Share via

Accessing shared DriveItems

Permissions

HTTP request

Path parameters

Encoding sharing URLs

Optional request headers

Prefer header values

Response

Example

Request

Response

Access the shared item directly

Example (single file)

Request

Response

Example (shared folder)

Request

Response

Error Responses

Remarks

Feedback

Additional resources