Создание ссылки для доступа к ресурсу DriveItem

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

Используя действие createLink, вы можете поделиться ресурсом DriveItem с помощью ссылки для совместного доступа.

Действие createLink создает ссылку для совместного доступа, если ссылка указанного типа еще не существует для приложения, совершающего вызов. Если для приложения уже создана такая ссылка указанного типа, возвращается она.

Ресурсы DriveItem наследуют разрешения совместного доступа от своих предков.

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

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

Разрешения

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

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

HTTP-запрос

POST /drives/{driveId}/items/{itemId}/createLink
POST /groups/{groupId}/drive/items/{itemId}/createLink
POST /me/drive/items/{itemId}/createLink
POST /sites/{siteId}/drive/items/{itemId}/createLink
POST /users/{userId}/drive/items/{itemId}/createLink

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

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

Тело запроса

В теле запроса определяются свойства ссылки для совместного доступа, запрашиваемой приложением. Запрос должен быть объектом JSON с указанными ниже свойствами.

Имя Тип Описание
type string Тип создаваемой ссылки для совместного доступа. Возможные значения: view, edit или embed.
password string Пароль ссылки для общего доступа, заданной создателем. Необязательный параметр и только OneDrive Personal.
expirationDateTime string Строка в формате yyyy-MM-ddTHH:mm:ssZ элемента DateTime указывает время окончания срока действия разрешения.
retainInheritedPermissions Boolean Необязательное свойство. Если true (по умолчанию) все существующие унаследованные разрешения сохраняются для общего элемента при первом предоставлении общего доступа к этому элементу. Если falseзадано значение , все существующие разрешения удаляются при первом предоставлении общего доступа.
scope string Необязательный параметр. Область создаваемой ссылки. Возможные значения: anonymous, organization или users.

Параметр type может принимать указанные ниже значения.

Значение типа Описание
view Создает ссылку на объект DriveItem, предполагающую доступ только для чтения.
edit Создает ссылку на объект DriveItem, предполагающую доступ для чтения и записи.
embed Создает встраиваемую ссылку на объект DriveItem. Этот вариант доступен только для файлов в личных учетных записях OneDrive.

Типы областей

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

Значение Описание
anonymous Любой пользователь со ссылкой обладает правом доступа без необходимости входа в систему. Это также относится к людям вне вашей организации. Администратор может отключить поддержку ссылок, не требующих проверки подлинности.
organization Любой пользователь, вошедший в вашу организацию (клиент), может использовать ссылку для получения доступа. Доступно только в OneDrive для бизнеса и SharePoint.
users Предоставлять общий доступ только пользователям, выбранным в организации или за ее пределами.

Отклик

В случае успешного выполнения этот метод возвращает в тексте ответа один ресурс Permission, представляющий запрашиваемые разрешения для совместного доступа.

Если для элемента создается новая ссылка совместного доступа, возвращается код ответа 201 Created, а если возвращается существующая ссылка — код 200 OK.

Пример

В приведенном ниже примере запрашивается создание ссылки для совместного доступа к объекту DriveItem, указанному по {itemId}, в хранилище OneDrive пользователя. Ссылка для совместного доступа подразумевает доступ только для чтения, и ее может использовать каждый, кому она предоставлена. Все существующие разрешения удаляются при первом совместном использовании, если retainInheritedPermissions имеет значение false.

Запрос

POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/createLink
Content-type: application/json

{
  "type": "view",
  "password": "ThisIsMyPrivatePassword",
  "scope": "anonymous",
  "retainInheritedPermissions": false
}

Отклик

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["write"],
  "link": {
    "type": "view",
    "scope": "anonymous",
    "webUrl": "https://1drv.ms/A6913278E564460AA616C71B28AD6EB6",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  },
  "hasPassword": true
}

OneDrive для бизнеса и SharePoint поддерживают ссылки с возможностью общего доступа в компании. Они аналогичны ссылкам, не требующим проверки подлинности, но работают только для элементов соответствующей организации. Чтобы создать такую ссылку, задайте для параметра scope значение organization.

Запрос

POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/createLink
Content-Type: application/json

{
  "type": "edit",
  "scope": "organization"
}

Отклик

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["write"],
  "link": {
    "type": "edit",
    "scope": "organization",
    "webUrl": "https://contoso-my.sharepoint.com/personal/ellen_contoso_com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  },
}

При использовании типа ссылки embed возвращаемое значение webUrl можно внедрять в элемент HTML <iframe>. При создании встроенной ссылки свойство webHtml содержит HTML-код для объекта <iframe>, в котором размещается содержимое.

Примечание. Внедрение ссылок поддерживается только в личных учетных записях OneDrive.

Запрос

POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/createLink
Content-Type: application/json

{
  "type": "embed"
}

Отклик

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["read"],
  "link": {
    "type": "embed",
    "webHtml": "<IFRAME src=\"https://onedrive.live.com/...\"></IFRAME>",
    "webUrl": "https://onedrive.live.com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

Примечания

  • Срок действия ссылок, созданных с помощью этого действия, не истекает при условии, что в организации не включена политика срока действия.
  • Ссылки отображаются в разрешениях на совместное использование для элемента и могут быть удалены владельцем элемента.
  • Они всегда указывают на текущую версию элемента, если он не был извлечен (только в SharePoint).