Работа с сайтами SharePoint в Microsoft Graph

Статья
04/15/2023

API SharePoint в Microsoft Graph поддерживает следующие основные сценарии:

доступ к ресурсам site, list и drive (библиотекам документов) в SharePoint;
доступ к ресурсам site только для чтения (без возможности создавать сайты);
доступ на чтение и запись к ресурсам list, listItem и driveItem;
Поддержка чтения и записи для SharePointSettings на уровне клиента
обращение к ресурсам по идентификатору SharePoint, URL-адресу или относительному пути.

API SharePoint предоставляет три основных типа ресурсов:

Site(объект верхнего уровня)
List
ListItem

Ниже показан пример ресурса listItem.

{
  "fields": {
    "Title": "Access card",
    "Employee": "Ryan Gregg",
    "EmployeeId": "10",
    "CardSerial": "01235492",
    "Alias": "RGregg",
    "ID": 1,
    "ContentType": "Item",
    "Modified": "2016-09-19T23:15:25-07:00",
    "Created": "2016-09-19T23:15:25-07:00"
  },
  "createdBy": {
    "user": {
      "id": "b757fdcb-0271-4807-b243-504139e4ba04",
      "displayName": "Ryan Gregg"
    }
  },
  "createdDateTime": "2016-09-20T06:15:25Z",
  "eTag": "48e941c3-9515-4c48-9760-c07c90c79d48,1",
  "id": "4",
  "lastModifiedBy": {
    "user": {
      "id": "b757fdcb-0271-4807-b243-504139e4ba04",
      "displayName": "Ryan Gregg"
    }
  },
  "lastModifiedDateTime": "2016-09-20T06:15:25Z",
}

Ресурсы предоставляют данные тремя разными способами:

Свойства (например, id и name) предоставляют простые значения.
Аспекты (например, fields и createdBy) предоставляют сложные значения.
Ссылки (например, items) указывают на коллекции других ресурсов.

Вы можете расширить ссылки в URL-адресе с помощью параметра запроса expand, например ?expand=fields. Вы можете запросить определенные свойства и аспекты с помощью параметра запроса select, например ?select=id,name. По умолчанию возвращается большая часть свойств и аспектов, при этом все ссылки скрыты. Для повышения эффективности мы рекомендуем указывать операторы select и expand, чтобы возвращать только важные для вас данные.

Корневые ресурсы API SharePoint

Приведенные ниже примеры относятся к https://graph.microsoft.com/beta.

Путь	Описание
/sites/root	Ресурс site по умолчанию для организации.
/sites/{site-id}	Доступ к определенному ресурсу site с использованием его идентификатора.
/sites/{site-id}/drive	Доступ к ресурсу drive (библиотеке документов) для указанного ресурса site, заданному по умолчанию.
/sites/{site-id}/drives	Перечисление ресурсов drive (библиотек документов) для site.
/sites/{site-id}/sites	Перечисление дочерних сайтов для ресурса site.
/sites/{site-id}/lists	Перечисление ресурсов lists для ресурса site.
/sites/{site-id}/lists/{list-id}/items	Перечисление ресурсов listItem для ресурса list.
/groups/{group-id}/sites/root	Доступ к сайту группы для группы.
/admin/sharepoint/settings	Получите доступ к параметрам уровня администратора организации.

Сайты также можно адресовать по пути, используя имя узла SharePoint, за которым следует двоеточие и относительный путь к сайту. При необходимости можно вернуться к модели ресурсов, поместив в конец еще один двоеточие.

Путь	Описание
/sites/contoso.sharepoint.com:/teams/hr	Сайт, связанный с https://contoso.sharepoint.com/teams/hr
/sites/contoso.sharepoint.com:/teams/hr:/drive	Доступ к ресурсу drive, заданному по умолчанию.

Примечание, касающееся разработки решений для SharePoint

API SharePoint в Microsoft Graph имеет ряд ключевых отличий от API CSOM. Ресурс site сопоставляется с SPWeb. Корневой ресурс site (SPWeb) в семействе веб-сайтов имеет аспект siteCollection, содержащий сведения о SPSite. Идентификаторы сайтов уникальны только в пределах одного семейства веб-сайтов. Поэтому чтобы обратиться к сайту по его идентификатору, необходимо указать два идентификатора — для семейства веб-сайтов и для самого сайта.

GET https://graph.microsoft.com/beta/sites/{hostname},{spsite-id},{spweb-id}/

URL-адрес, созданный только с именем узла, указывает на корневой сайт (SPWeb) в семействе веб-сайтов по умолчанию.

GET https://graph.microsoft.com/beta/sites/{hostname}

URL-адрес, созданный только с именем узла и идентификатором siteCollection (SPSite) указывает на корневой сайт (SPWeb) в данном семействе веб-сайтов.

GET https://graph.microsoft.com/beta/sites/{hostname},{spsite-id}

URL-адрес, созданный только с идентификатором siteCollection (SPSite) указывает на корневой сайт (SPWeb) в данном семействе веб-сайтов.

GET https://graph.microsoft.com/beta/sites/{spsite-id}

Сопоставление URL-адресов API REST версии 1 для SharePoint с URL-адресами Microsoft API Graph

Следующие примеры помогут разработчикам, знакомым с шаблонами URL-адресов REST API SharePoint версии 1, адаптировать свои варианты использования к аналогичным шаблонам URL-адресов Microsoft API Graph.

Шаблон 1

Доступ к сайту, связанному с указанным SPWeb URL-адресом.

GET https://graph.microsoft.com/beta/sites/{hostname}:/{site-server-relative-url}

Пример 1

В следующем примере возвращаются сведения о сайте, связанном с URL-адресом SPWebhttps://contoso.sharepoint.com/teams/hr/benefits. Обратите внимание, что benefits является в SPWeb семействе веб-сайтов (SPSite) по адресу https://contoso.sharepoint.com/teams/hr.

GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com:/teams/hr/benefits

Шаблон 2

Получите доступ к элементу списка, связанному со следующими компонентами.

Компонент	Описание
{hostname}	Имя узла сайта.
{site-server-relative-url}	URL-адрес сайта(`SPWeb`).
{list-id}	Идентификатор GUID списка (`SPList`) на сайте.
{item-id}	Идентификатор GUID или целочисленный идентификатор элемента списка (`SPListItem`) в списке.

В следующем примере показан запрос, содержащий предыдущие компоненты.

GET https://graph.microsoft.com/beta/sites/{hostname}:/{site-server-relative-url}:/lists/{list-id}/items/{item-id}

Пример 2

В следующем примере возвращаются сведения о объекте SPListItem с целочисленным идентификатором 42 , который принадлежит к списку с идентификатором 5771e865-4e91-48b8-a0de-35a25d4e52feGUID . Этот список относится к сайту, связанному с URL-адресом SPWebhttps://contoso.sharepoint.com/teams/hr/benefits.

GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com:/teams/hr/benefits:/lists/5771e865-4e91-48b8-a0de-35a25d4e52fe/items/42