发送共享邀请

  • 项目

命名空间：microsoft.graph

重要

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

发送 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/{drive-id}/items/{item-id}/invite
POST /groups/{group-id}/drive/items/{item-id}/invite
POST /me/drive/items/{item-id}/invite
POST /sites/{siteId}/drive/items/{itemId}/invite
POST /users/{userId}/drive/items/{itemId}/invite

请求正文

在请求正文中，提供具有以下参数的 JSON 对象。

{
  "requireSignIn": false,
  "sendInvitation": false,
  "roles": [ "read | write"],
  "recipients": [
    { "@odata.type": "microsoft.graph.driveRecipient" },
    { "@odata.type": "microsoft.graph.driveRecipient" }
  ],
  "message": "string"
}
参数 类型 说明
recipients 集合 (驱动器recipient) 接收访问权限和共享邀请的收件人的集合。
message String 共享邀请中包含的纯文本格式的邮件。 最大长度为 2,000 个字符。
requireSignIn Boolean 指定邀请的收件人要查看共享项目的登录位置。
sendInvitation Boolean 指定是否 (false) 生成电子邮件或帖子，或者最近是否 (true) 创建权限。
角色 集合（字符串） 指定向共享邀请的收件人授予的角色。
expirationDateTime DateTimeOffset 指定权限过期后的 dateTime 。 对于 OneDrive for Business 和 SharePoint，xpirationDateTime 仅适用于 sharingLink 权限。 适用于 OneDrive for Business、SharePoint 和高级个人 OneDrive 帐户。
密码 String 创建者在邀请上设置的密码。 仅限可选和 OneDrive 个人版
retainInheritedPermissions 布尔值 可选。 如果 true (默认) ，则首次共享此项目时，将保留共享项上任何现有继承的权限。 如果 false为 ，则首次共享时将删除所有现有权限。

示例

本示例向电子邮件地址为“”ryan@contoso.org的用户发送共享邀请，其中包含有关正在协作的文件的消息。 此邀请授予 Ryan 对该文件的读写访问权限。

HTTP 请求

如果成功，此方法在响应正文中返回 200 OK 响应代码和 permission 集合对象。

POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/invite
Content-type: application/json

{
  "recipients": [
    {
      "email": "robin@contoso.org"
    }
  ],
  "message": "Here's the file that we're collaborating on.",
  "requireSignIn": true,
  "sendInvitation": true,
  "roles": [ "write" ],
  "password": "password123",
  "expirationDateTime": "2018-07-15T14:00:00.000Z"
}

响应

以下示例显示了相应的响应。

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "@deprecated.GrantedTo": "GrantedTo has been deprecated. Refer to GrantedToV2",
      "grantedTo": {
        "user": {
          "displayName": "Robin Danielsen",
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
        }
      },
      "grantedToV2": {
        "user": {
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20",
          "displayName": "Robin Danielsen"
        },
        "siteUser": {
          "id": "1",
          "displayName": "Robin Danielsen",
          "loginName": "Robin Danielsen"
        }
      },
      "hasPassword": true,
      "id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "robin@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "expirationDateTime": "2018-07-15T14:00:00.000Z"
    }
  ]
}

部分成功响应

邀请多个收件人时，某些收件人的通知可能会成功，而其他收件人可能会失败。 在这种情况下，服务返回 HTTP 状态代码为 207 的部分成功响应。 返回部分成功后，每个失败收件人的响应都包含一个 error 对象，其中包含有关错误原因以及如何修复错误的信息。

以下示例显示了部分响应。

HTTP/1.1 207 Multi-Status
Content-type: application/json

{
  "value": [
    {
      "grantedTo": {
        "user": {
          "displayName": "Helga Hammeren",
          "id": "5D8CA5D0-FFF8-4A97-B0A6-8F5AEA339681"
        }
      },
      "id": "1EFG7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "helga@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "error": {
        "code":"notAllowed",
        "message":"Account verification needed to unblock sending emails.",
        "localizedMessage": "Kontobestätigung erforderlich, um das Senden von E-Mails zu entsperren.",
        "fixItUrl":"http://g.live.com/8SESkydrive/VerifyAccount",
        "innererror":{
          "code":"accountVerificationRequired"
        }
      }
    },
    {
      "grantedTo": {
        "user": {
          "displayName": "Robin Danielsen",
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
        }
      },
      "id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "robin@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "expirationDateTime": "2018-07-15T14:00:00.000Z"
    }
  ]
}

SendNotification 错误

下面是发送通知失败时，你的应用在嵌套 innererror 对象中可能会遇到的一些其他错误。 应用不需要处理这些错误。

代码 说明
accountVerificationRequired 需要帐户验证才能取消阻止发送通知。
hipCheckRequired 需要解决 HIP (主机入侵防护) 检查 来取消阻止发送通知。
exchangeInvalidUser 找不到当前用户的邮箱。
exchangeOutOfMailboxQuota 超出配额。
exchangeMaxRecipients 超出了可同时发送通知的最大收件人数。

注意： 该服务可以随时添加新错误代码或停止返回旧错误代码。

备注

  • driveType 为 personal (OneDrive 个人) 的驱动器无法创建或修改对根 DriveItem 的权限。
  • 有关可用角色的列表，请参阅 roles 属性值。

错误响应

有关错误返回方式的详细信息，请阅读错误 响应 主题。