Получение доступа к специальной папке по ее имени

Пространство имен: microsoft.graph

Используйте специальную коллекцию для доступа к специальной папке по имени.

Применение специальных папок обеспечивает доступ к известным папкам в OneDrive с помощью простых псевдонимов, благодаря чему можно не искать папку по пути (что потребует локализации) и не ссылаться на нее с использованием идентификатора. Если специальная папка будет переименована или перемещена в другое расположение на диске, такой синтаксис по-прежнему позволит найти ее.

Когда приложение впервые пробует записать что-то в специальную папку, она создается автоматически, если не была создана ранее. Если пользователь удалил такую папку, она создается повторно при записи в нее.

Заметка: Если у вас есть разрешения только для чтения и вы запрашиваете специальную папку, которая не существует, вы получите сообщение об ошибке 403 Forbidden .

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба	Правительство США L4	Правительство США L5 (DOD)	Китай управляется 21Vianet
✅	✅	✅	✅

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения	Разрешения с наименьшими привилегиями	Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись)	Files.Read	Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Делегированные (личная учетная запись Майкрософт)	Files.ReadWrite.AppFolder	Files.Read, Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All
Для приложений	Не поддерживается.	Не поддерживается.

HTTP-запрос

GET /me/drive/special/{name}

Имена специальных папок

Указанные ниже имена специальных папок доступны в OneDrive и OneDrive для бизнеса.

Имя	Идентификатор папки	Описание
Документы	documents	Папка "Документы".
Фотографии	photos	Папка "Фотографии".
Альбом камеры	cameraroll	Папка для резервных копий альбома камеры.
Корневая папка приложения	approot	Личная папка приложения. Обычно расположена в папке /Apps/{Application Name}
Музыка	music	Папка "Музыка".
Записи	recordings	Папка Recordings. Этот параметр доступен только в OneDrive для бизнеса и SharePoint Online.

Необязательные параметры запросов

Этот метод поддерживает $expandпараметры запроса OData и $select для настройки ответа.

Заголовки запросов

Имя	Описание
Авторизация	Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.

Отклик

Этот метод возвращает код ответа 200 OK и объект driveItem в теле ответа.

Вы можете использовать этот метод обращения к специальной папке наряду с дополнительными вызовами к свойствам или связям в ресурсе driveItem.

Примеры

Пример 1. Получение специальной папки по имени

Запрос

HTTP

GET /me/drive/special/{name}

C#

// 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();

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Go

// 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)

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Java

// 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();

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PowerShell

Import-Module Microsoft.Graph.Files

Get-MgDriveSpecial -DriveId $driveId -DriveItemId $driveItemId

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Python

# 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()

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

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

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

Пример 2. Получение дочерних элементов специальной папки

Чтобы получить список дочерних элементов для специальной папки, можно запросить коллекцию children или с помощью параметра expand развернуть этот список.

Запрос

HTTP

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

C#

Snippet not available

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Go

Snippet not available

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Java

Snippet not available

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PHP

Snippet not available

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PowerShell

Snippet not available

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Python

Snippet not available

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

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

Примечания

Примечание. Элементы DriveItem с аспектом specialFolder указывают, что элемент представляет собой специальную папку, и доступ к нему можно получить через коллекцию special.

Если у вашего приложения есть разрешения только для чтения, то запрос на получение специальной папки или ее дочерних элементов может завершиться ошибкой 404 Not Found или 403 Forbidden, если специальная папка еще не существует.