为 DriveItem 创建共享链接

  • 项目

命名空间：microsoft.graph

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

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

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

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

为此 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

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Type application/json. 必需。

请求正文

请求正文定义应用程序正在请求的共享链接的属性。 请求应为具有以下属性的 JSON 对象。

名称 类型 说明
类型 string 要创建的共享链接的类型。 view、 edit或 embed。
password string 创建者设置的共享链接的密码。 仅限可选和 OneDrive 个人版。
expirationDateTime string DateTime 格式为 yyyy-MM-ddTHH：mm：ssZ 的字符串表示权限的过期时间。
retainInheritedPermissions 布尔值 可选。 如果 true (默认) ，则首次共享此项目时，将保留共享项上任何现有继承的权限。 如果 false为 ，则首次共享时将删除所有现有权限。
scope string 可选。 要创建的链接的范围。 anonymous、 organization或 users。

type 参数允许使用以下值：

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

范围类型

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

值 说明
anonymous 拥有该链接的任何人都可以访问，无需登录。 这可能包括组织外部的人员。 管理员可能会禁用匿名链接支持。
organization 登录到组织（租户）的任何人都可以使用该链接获取访问权限。 仅适用于 OneDrive for Business 和 SharePoint。
users 仅与组织内部或组织外部选择的人员共享。

响应

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

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

示例

下面的示例请求为在用户的 OneDrive 中按 {itemId} 指定的 DriveItem 创建共享链接。 共享链接配置为只读并且可由具有该链接的任何用户使用。 如果 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 for Business 和 SharePoint 都支持公司可共享的链接。 此类链接与匿名链接类似，只不过仅适用于拥有组织的成员。 若要创建公司可共享的链接，请使用值为 organization 的 scope 参数。

请求

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

注意：仅 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）。