listItem：createLink

  • 项目

命名空间：microsoft.graph

重要

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

为 listItem 创建共享链接。

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

listItem 资源从项所在的 列表中 继承共享权限。

此 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 /sites/{siteId}/lists/{listId}/items/{itemId}/createLink

请求标头

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

请求正文

在请求正文中，提供参数的 JSON 表示形式。

下表显示了可用于此操作的参数。

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

type 参数允许使用以下值：

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

范围类型

scope 参数允许使用以下值。

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

响应

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

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

示例

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

请求

POST https://graph.microsoft.com/beta/sites/{siteId}/lists/{listId}/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/sites/{siteId}/lists/{listId}/items/{itemId}/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 属性包含用于 <iframe> 托管内容的 的 HTML 代码。

注意：仅 OneDrive 个人版支持嵌入链接。

请求

POST https://graph.microsoft.com/beta/sites/{siteId}/lists/{listId}/items/{itemId}/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"
    },
  }
}

说明

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