通过

driveItem：createLink

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

创建链接以共享 driveItem 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

注意

SharePoint Embedded 需要 FileStorageContainer.Selected 权限才能访问容器的内容。 此权限不同于前面提到的权限。 除了Microsoft Graph 权限外，应用还必须具有调用此 API 所需的 容器类型权限 。 有关详细信息，请参阅 SharePoint Embedded 身份验证和授权。

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 可选。 要创建的共享链接的类型。
范围 String 可选。 要创建的链接的范围。 anonymous、organization或users
expirationDateTime DateTimeOffset 可选。 DateTime 格式为 yyyy-MM-ddTHH：mm：ssZ 的字符串表示权限的过期时间。
密码 String 可选。 创建者设置共享链接的密码。
recipients driveRecipient 集合 可选。 接收对共享链接的访问权限的收件人的集合。
retainInheritedPermissions 布尔值 可选。 如果 true (默认) ，则首次共享此项目时，将保留共享项上任何现有继承的权限。 如果 false为 ，则首次共享时将删除所有现有权限。
sendNotification 布尔值 如果 true为 ，则此方法将电子邮件中的 共享链接 发送给 中指定的 recipients用户。 适用于 OneDrive for Business 或 SharePoint。 默认值为 false。 可选。

type 参数允许使用以下值：

类型值 说明
view 创建 driveItem 的只读链接。
回顾 创建 driveItem 的审阅链接。 此选项仅适用于 OneDrive for Business 和 SharePoint 中的文件。
edit 创建 driveItem 的读写链接。
嵌入 创建 driveItem 的可嵌入链接。
blocksDownload 创建阻止下载到 driveItem 的只读链接。 此选项仅适用于 OneDrive for Business 和 SharePoint 中的文件。
createOnly 创建 driveItem 的仅上传链接。 此选项仅适用于 OneDrive for Business 和 SharePoint 中的文件夹。
addressBar 为新创建的文件创建浏览器地址栏中显示的默认链接。 仅适用于 OneDrive for Business 和 SharePoint。 组织管理员配置此链接类型是否支持并指定它支持的功能。
adminDefault 创建由组织管理员确定的 driveItem 的默认链接。 仅适用于 OneDrive for Business 和 SharePoint。 管理员为组织强制实施策略。

范围类型

scope 参数允许使用以下值。

值 说明
匿名 拥有该链接的任何人都可以访问，无需登录。 它可能包括组织外部的人员。 管理员可以禁用对匿名链接的支持。
组织 登录到组织（租户）的任何人都可以使用该链接获取访问权限。 仅适用于 OneDrive for Business 和 SharePoint。
users 收件人集合中的特定人员可以使用链接获取访问权限。 仅适用于 OneDrive for Business 和 SharePoint。

响应

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

如果为 driveItem 创建新的共享链接，或者200 OK返回了现有链接，则响应为 201 Created 。

示例

以下示例请求为用户的 OneDrive 中的 {itemId} 指定的 driveItem 创建共享链接。 共享链接配置为只读并且可由具有该链接的任何用户使用。 对于OneDrive for Business和 SharePoint 用户，请使用 sendNotification 参数创建共享链接。 然后，共享链接将通过电子邮件发送给收件人。 如果 retainInheritedPermissions 为 false，则首次共享时将删除所有现有权限。

请求

POST https://graph.microsoft.com/beta/me/drive/items/{itemId}/createLink
Content-Type: application/json

{
  "type": "view",
  "scope": "anonymous",
  "password": "String",
  "recipients": [
    {
      "@odata.type": "microsoft.graph.driveRecipient"
    }
  ],
  "sendNotification": true,
  "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/beta/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/beta/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"
    },
  }
}

备注

  • 若要根据组织的默认策略和调用方对 driveItem 的权限创建链接，请省略范围和类型参数。
  • 除非为组织强制执行默认过期策略，否则使用此作创建的链接不会过期。
  • 链接在 driveItem 的共享权限中可见，并且可由 driveItem 的所有者删除。
  • 链接始终指向 driveItem 的当前版本，除非仅在 sharePoint) (签出 driveItem 。
  • Last updated on