为 DriveItem 创建共享链接

命名空间:microsoft.graph

可以使用 createLink 操作通过共享链接共享 DriveItem

如果调用应用程序指定的链接类型尚不存在,CreateLink 操作将创建新的共享链接。如果应用程序指定的共享链接类型已存在,则返回现有的共享链接。

DriveItem 资源从其上级继承共享权限。

权限

要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限

权限类型 权限(从最低特权到最高特权)
委派(工作或学校帐户) Files.ReadWrite、Files.ReadWrite.All、Sites.ReadWrite.All
委派(个人 Microsoft 帐户) 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 对象。

名称 类型 说明
类型 string 要创建的共享链接的类型。vieweditembed
password string 创建者设置的共享链接的密码。 可选且OneDrive个人。
expirationDateTime string DateTime 格式为 yyyy-MM-ddTHH:mm:ssZ 的 String 表示权限的过期时间。
scope string 可选。 要创建的链接的范围。 anonymousorganization

type 参数允许使用以下值:

类型值 说明
view 创建到 DriveItem 的只读链接。
edit 创建到 DriveItem 的读写链接。
embed 创建到 DriveItem 的可嵌入链接。 此选项仅适用于 OneDrive 个人版中的文件。

范围类型

scope 参数允许使用以下值。 如果未指定 scope 参数,则为组织创建默认的链接类型。

说明
anonymous 拥有该链接的任何人都可以访问,无需登录。 这可能包括组织外部的人员。 管理员可能会禁用匿名链接支持。
organization 登录到组织(租户)的任何人都可以使用该链接获取访问权限。 仅适用于 OneDrive for Business 和 SharePoint。

响应

如果成功,此方法将在响应正文中返回单个 Permission 资源,此响应正文表示请求的共享权限。

如果已经为此项目创建新的共享链接,则响应为 201 Created;如果返回现有链接,则为 200 OK

示例

下面的示例请求为在用户的 OneDrive 中按 {itemId} 指定的 DriveItem 创建共享链接。 共享链接配置为只读并且可由具有该链接的任何用户使用。

请求

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

{
  "type": "view",
  "password": "ThisIsMyPrivatePassword",
  "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"
    },
  },
  "hasPassword": true
}

OneDrive for Business 和 SharePoint 都支持公司可共享的链接。 此类链接与匿名链接类似,只不过仅适用于拥有组织的成员。 若要创建公司可共享的链接,请使用值为 organizationscope 参数。

请求

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 链接类型时,可以在 <iframe> HTML 元素中嵌入返回的 webUrl。创建嵌入链接时,webHtml 属性包含 <iframe> 的 HTML 代码以托管内容。

注意: 仅 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://onedrive.live.com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

注解

  • 使用此操作创建的链接不会过期,除非对组织强制执行了默认过期策略。
  • 链接在项的共享权限中可见,可以由该项的所有者删除。
  • 除非项已被签出,否则链接始终指向该项的最新版本(仅限 SharePoint)。