按名称获取特殊文件夹

命名空间：microsoft.graph

使用特殊集合可以按名称访问特殊文件夹。

特殊文件夹可以提供简单别名来访问 OneDrive 中的已知文件夹，无需按路径查找（需要本地化）或通过 ID 引用文件夹。如果特殊文件夹被重命名或移到驱动器中的其他位置，此语法将继续查找该文件夹。

应用程序第一次尝试向特殊文件夹中写入内容时，如果特殊文件夹不存在，系统会自动创建特殊文件夹。如果用户删除某个特殊文件夹，再次向其写入内容时会重新创建特殊文件夹。

全局服务	美国政府 L4	美国政府 L5 (DOD)	由世纪互联运营的中国
✅	✅	✅	✅

权限

为此 API 选择标记为最低特权的权限。只有在应用需要它时，才使用更高的特权权限。有关委派权限和应用程序权限的详细信息，请参阅权限类型。要了解有关这些权限的详细信息，请参阅权限参考。

权限类型	最低特权权限	更高特权权限
委派（工作或学校帐户）	Files.Read	Files.Read.All、Files.ReadWrite、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All
委派（个人 Microsoft 帐户）	Files.ReadWrite.AppFolder	Files.Read、Files.Read.All、Files.ReadWrite、Files.ReadWrite.All、Sites.Read.All
应用程序	不支持。	不支持。

HTTP 请求

GET /me/drive/special/{name}

特殊文件夹名称

以下是 OneDrive 和 OneDrive for Business 中可用的特殊文件夹名称。

名称	文件夹 ID	说明
Documents	`documents`	“文档”文件夹。
Photos	`photos`	“照片”文件夹。
Camera Roll	`cameraroll`	“本机照片备份”文件夹。
App Root	`approot`	应用程序的个人文件夹。路径通常为 `/Apps/{Application Name}`
Music	`music`	“音乐”文件夹。
录音	`recordings`	“录制”文件夹。此选项仅在 OneDrive for Business 和 SharePoint Online 中可用。

可选的查询参数

此方法支持 $expand 和 $selectOData 查询参数来自定义响应。

请求标头

名称	说明
Authorization	持有者 {token}。必填。详细了解身份验证和授权。

响应

此方法在响应正文中返回 200 OK 响应代码和 driveItem 对象。

可以将此处理特殊文件夹内联的方法与对 driveItem 上的属性或关系的其他调用结合使用。

示例

示例 1：按名称获取特殊文件夹

请求

GET /me/drive/special/{name}


// 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.Drives["{drive-id}"].Special["{driveItem-id}"].GetAsync();



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

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


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
special, err := graphClient.Drives().ByDriveId("drive-id").Special().ByDriveItemId("driveItem-id").Get(context.Background(), nil)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DriveItem result = graphClient.drives().byDriveId("{drive-id}").special().byDriveItemId("{driveItem-id}").get();


const options = {
	authProvider,
};

const client = Client.init(options);

let driveItem = await client.api('/me/drive/special/{name}')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


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


$result = $graphServiceClient->drives()->byDriveId('drive-id')->special()->byDriveItemId('driveItem-id')->get()->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveSpecial -DriveId $driveId -DriveItemId $driveItemId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph 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.drives.by_drive_id('drive-id').special.by_drive_item_id('driveItem-id').get()

响应

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "0123456789abc",
  "name": "Documents",
  "eTag": "012345819293.1",
  "specialFolder": {
    "name": "documents"
  }
}

示例 2：获取特殊文件夹的子级

若要请求获取特殊文件夹的子项，可以请求获取 children 集合，或使用 expand 选项扩展子集合。

请求

GET /me/drive/special/{special-folder-name}/children

Snippet not available

Snippet not available

Snippet not available


const options = {
	authProvider,
};

const client = Client.init(options);

let children = await client.api('/me/drive/special/{special-folder-name}/children')
	.get();

Snippet not available

Snippet not available

Snippet not available

响应

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {"name": "myfile.jpg", "size": 2048 },
    {"name": "Documents", "folder": { "childCount": 4} },
    {"name": "Photos", "folder": { "childCount": 203} },
    {"name": "my sheet(1).xlsx", "size": 197 }
  ]
}

说明

如果应用拥有只读权限，且特殊文件夹尚不存在，那么可能无法请求获取特殊文件夹或其子项，响应为 404 Not Found 或 403 Forbidden 错误。

反馈

此页面是否有帮助？

Last updated on 2025-07-24