Создание ссылки совместного доступа для ресурса DriveItemCreate a sharing link for a DriveItem

Используя действие createLink, вы можете поделиться ресурсом DriveItem с помощью ссылки для совместного доступа.You can use createLink action to share a DriveItem via a sharing link.

Действие createLink создает ссылку для совместного доступа, если ссылка указанного типа еще не существует для приложения, совершающего вызов. Если для приложения уже создана такая ссылка указанного типа, возвращается она.The createLink action will create a new sharing link if the specified link type doesn't already exist for the calling application. If a sharing link of the specified type already exists for the app, the existing sharing link will be returned.

Ресурсы DriveItem наследуют разрешения совместного доступа от своих предков.DriveItem resources inherit sharing permissions from their ancestors.

РазрешенияPermissions

Для вызова этого API требуется одно из указанных ниже разрешений. Дополнительные сведения, включая сведения о том, как выбрать разрешения, см. в статье Разрешения.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Тип разрешенияPermission type Разрешения (в порядке повышения привилегий)Permissions (from least to most privileged)
Делегированные (рабочая или учебная учетная запись)Delegated (work or school account) Files.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.All
Делегированные (личная учетная запись Майкрософт)Delegated (personal Microsoft account) Files.ReadWrite, Files.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All
Для приложенийApplication Files.ReadWrite.All, Sites.ReadWrite.AllFiles.ReadWrite.All, Sites.ReadWrite.All

HTTP-запросHTTP request

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

Тело запросаRequest body

В теле запроса определяются свойства ссылки для совместного доступа, запрашиваемой приложением.The body of the request defines properties of the sharing link your application is requesting. Запрос должен быть объектом JSON с указанными ниже свойствами.The request should be a JSON object with the following properties.

ИмяName ТипType ОписаниеDescription
typetype stringstring Тип создаваемой ссылки для совместного доступа. Возможные значения: view, edit или embed.The type of sharing link to create. Either view, edit, or embed.
scopescope stringstring Необязательный параметр.Optional. Область создаваемой ссылки.The scope of link to create. Возможные значения: anonymous или organization.Either anonymous or organization.

Параметр type может принимать указанные ниже значения.The following values are allowed for the type parameter.

Значение типаType value ОписаниеDescription
view Создает ссылку на объект DriveItem, предполагающую доступ только для чтения.Creates a read-only link to the DriveItem.
edit Создает ссылку на объект DriveItem, предполагающую доступ для чтения и записи.Creates a read-write link to the DriveItem.
embed Создает встраиваемую ссылку на объект DriveItem.Creates an embeddable link to the DriveItem. Этот вариант доступен только для файлов в личных учетных записях OneDrive.This option is only available for files in OneDrive personal.

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

Параметр scope может принимать указанные ниже значения.The following values are allowed for the scope parameter. Если параметр scope не задан, создается ссылка того типа, который используется в организации по умолчанию.If the scope parameter is not specified, the default link type for the organization is created.

ЗначениеValue ОписаниеDescription
anonymous Лица, имеющие ссылку имеет доступ, без необходимости входа.Anyone with the link has access, without needing to sign in. Сюда может входить пользователям за пределами вашей организации.This may include people outside of your organization. Поддержка анонимных ссылка может быть отключена администратором.Anonymous link support may be disabled by an administrator.
organization Любой пользователь вошел в вашей организации (клиента) используйте ссылку для доступа.Anyone signed into your organization (tenant) can use the link to get access. Доступно только в OneDrive для бизнеса и SharePoint.Only available in OneDrive for Business and SharePoint.

ОткликResponse

В случае успешного выполнения этот метод возвращает в тексте ответа один ресурс Permission, представляющий запрашиваемые разрешения для совместного доступа.If successful, this method returns a single Permission resource in the response body that represents the requested sharing permissions.

Если для элемента создается новая ссылка совместного доступа, возвращается код ответа 201 Created, а если возвращается существующая ссылка — код 200 OK.The response will be 201 Created if a new sharing link is created for the item or 200 OK if an existing link is returned.

ПримерExample

В приведенном ниже примере запрашивается создание ссылки для совместного доступа к объекту DriveItem, указанному по {itemId}, в хранилище OneDrive пользователя.The following example requests a sharing link to be created for the DriveItem specified by {itemId} in the user's OneDrive. Ссылка для совместного доступа подразумевает доступ только для чтения, и ее может использовать каждый, кому она предоставлена.The sharing link is configured to be read-only and usable by anyone with the link.

ЗапросRequest

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

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

ОткликResponse

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 поддерживают ссылки с возможностью общего доступа в компании.OneDrive for Business and SharePoint support company sharable links. Они аналогичны ссылкам, не требующим проверки подлинности, но работают только для элементов соответствующей организации.These are similar to anonymous links, except they only work for members of the owning organization. Чтобы создать такую ссылку, задайте для параметра scope значение organization.To create a company sharable link, use the scope parameter with a value of organization.

ЗапросRequest

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

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

ОткликResponse

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>, в котором размещается содержимое.When using the embed link type, the webUrl returned can be embedded in an <iframe> HTML element. When an embed link is created the webHtml property contains the HTML code for an <iframe> to host the content.

Примечание. Внедрение ссылок поддерживается только в личных учетных записях OneDrive.Note: Embed links are only supported for OneDrive personal.

ЗапросRequest

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

{
  "type": "embed"
}

ОткликResponse

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

ЗамечанияRemarks

  • Срок действия ссылок, созданных с помощью этого действия, не истекает при условии, что в организации не включена политика срока действия.Links created using this action do not expire unless a default expiration policy is enforced for the organization.
  • Ссылки отображаются в разрешениях на совместное использование для элемента и могут быть удалены владельцем элемента.Links are visible in the sharing permissions for the item and can be removed by an owner of the item.
  • Они всегда указывают на текущую версию элемента, если он не был извлечен (только в SharePoint).Links always point to the current version of a item unless the item is checked out (SharePoint only).