权限: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"
      }
    }
  ]
}

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