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

  • Статья

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

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

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

Разрешения

Для вызова этого 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

Тело запроса

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

Имя Тип Описание
type string Тип создаваемой ссылки для совместного доступа. Возможные значения: view, edit или embed.
scope string Необязательный параметр. Область создаваемой ссылки. Возможные значения: anonymous или organization.

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

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

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

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

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

Отклик

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

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

Пример

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

Запрос

POST /me/drive/items/{item-id}/createLink
Content-type: application/json

{
  "type": "view",
  "scope": "anonymous"
}

Отклик

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

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

Запрос

POST /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 /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://onedive.live.com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

Примечания

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