通过

权限：grant

  • 项目

命名空间：microsoft.graph

授予用户对 由权限表示的链接的访问权限。

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

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

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） Files.ReadWrite Files.ReadWrite.All、Sites.ReadWrite.All
委派（个人 Microsoft 帐户） 不支持。 不支持。
应用程序 Files.ReadWrite.All Sites.ReadWrite.All

HTTP 请求

POST /shares/{encoded-sharing-url}/permission/grant

路径参数

参数名称 值 说明
encoded-sharing-url string 必填。 正确编码的共享 URL。

编码共享 URL

若要编码共享 URL，请使用以下逻辑：

  1. 首先，使用 base64 编码 URL。
  2. 删除值末尾的 = 字符，将 / 替换成 _，将 + 替换成 -，从而将 base64 编码结果转换成未填充的 base64url 格式。
  3. 将 u! 追加到字符串的开头。

例如，若要对 URL 进行 C# 编码，请使用以下代码：

string sharingUrl = "https://onedrive.live.com/redir?resid=1231244193912!12&authKey=1201919!12921!1";
string base64Value = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(sharingUrl));
string encodedUrl = "u!" + base64Value.TrimEnd('=').Replace('/','_').Replace('+','-');

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。

请求正文

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

{
  "recipients": [
    { "@odata.type": "microsoft.graph.driveRecipient" }
  ],
  "roles": [ "read | write"]
}
参数 类型 说明
recipients 集合 (驱动器recipient) 将接收访问权限的收件人的集合。
角色 集合（字符串） 如果链接是“现有访问权限”链接，则指定要授予用户的角色。 否则，必须与链接的角色匹配。

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

响应

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

成功后，始终会在结果集中返回表示已更新链接 的权限 。 可以通过存在包含“scope”属性的“链接”方面来标识更新的链接。 在某些情况下，更新的链接可能具有与原始链接不同的 URL，在这种情况下，应使用新 URL。

请参阅错误响应主题，详细了解错误返回方式。

示例

本示例授予用户 john@contoso.com 和 ryan@external.com 对共享链接的访问权限，而无需修改该链接的其他现有权限。

请求

POST https://graph.microsoft.com/v1.0/shares/{encoded-sharing-url}/permission/grant
Content-type: application/json

{
  "recipients": [
    {
      "email": "john@contoso.com"
    },
    {
      "email": "ryan@external.com"
    }
  ],
  "roles": ["read"]
}

响应

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

{
  "value": [
    {
      "hasPassword": false,
      "id": "5fab944a-47ec-48d0-a9b5-5178a926d00f",
      "link": {
        "preventsDownload": false,
        "scope": "users",
        "type": "view",
        "webUrl": "https://contoso.sharepoint.com/:t:/g/design/EZexPoDjW4dMtKFUfAl6BK4BvIUuss52hLYzihBfx-PD6Q"
      },
      "roles": [
        "read"
      ]
    }
  ]
}

注意：为了提高可读性，可能缩短了此处显示的响应对象。

如果链接是 现有访问 链接，则会返回表示以下内容的其他权限：

  • 表示已成功授予访问权限的收件人的用户类型权限。 可以通过 存在 grantedTo 属性来标识这些属性。
  • 链接类型权限，表示需要发送给无法识别的外部用户才能获得访问权限的邀请。 这些可以通过 邀请 方面的存在来标识。 这些条目将包含包含邀请 URL 的链接 ，grantedToIdentities 集合将指示应向其发送链接的用户。
HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "hasPassword": false,
      "id": "00000000-0000-0000-0000-000000000000",
      "link": {
        "preventsDownload": false,
        "scope": "existingAccess",
        "type": "view",
        "webUrl": "https://contoso.sharepoint.com/teams/design/shareddocs/Document.docx"
      },
      "roles": [
        "read"
      ]
    },
    {
      "grantedTo": {
        "user": {
          "displayName": "John Smith",
          "email": "john@contoso.com",
          "id": "47aecee2-d061-4730-8ecb-4c61360441ae"
        }
      },
      "id": "aTowIy5mfG1lbWJlcnNoaXB8bGltaXRlZDJAa2xhbW9kYi5vbm1pY3Jvc29mdC5jb20",
      "roles": [
        "read"
      ]
    },
    {
      "grantedToIdentities": [
        {
          "user": {
            "email": "ryan@external.com"
          }
        }
      ],
      "invitation": {
        "signInRequired": true
      },
      "roles": [
        "read"
      ],
      "link": {
        "type": "view",
        "webUrl": "https://contoso.sharepoint.com/:t:/g/teams/design/EZexPoDjW4dMtKFUfAl6BK4Bw_F7gFH63O310A7lDtK0mQ"
      }
    }
  ]
}

注意：为了提高可读性，可能缩短了此处显示的响应对象。