通过

driveItem：邀请

命名空间：microsoft.graph

发送 driveItem 的共享邀请。 共享邀请为收件人提供权限，并选择性地向他们发送电子邮件，通知他们该项目已共享。

重要

  • 无法在根 driveItem 上创建或修改权限，驱动器的 driveType 为 personal ( OneDrive for home) 。
  • 不能使用仅限应用的访问权限邀请新来宾。 可以使用仅限应用的请求邀请现有来宾。

此 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/{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

请求标头

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

请求正文

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

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

响应

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

有关如何返回错误的详细信息，请参阅 错误响应。

部分成功响应

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

发送邀请通知错误

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

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

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

示例

示例 1：发送共享邀请

以下示例演示如何使用电子邮件地址 ryan@contoso.com向用户发送共享邀请，包括有关协作下文件的消息。 此邀请授予 Ryan 对该文件的读写访问权限。

请求

以下示例显示了一个请求。

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

{
  "recipients": [
    {
      "email": "ryan@contoso.com"
    }
  ],
  "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"
    }
  ]
}

示例 2：发送部分成功的共享邀请

以下示例演示了部分成功的请求。

请求

以下示例显示了一个请求。

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

{
  "recipients": [
    {
      "email": "helga@contoso.com"
    },
    {
      "email": "robin@contoso.com"
    }
  ],
  "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 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"
    }
  ]
}

相关内容

有关可用角色的列表，请参阅 roles 属性值。

  • Last updated on