权限资源类型

命名空间：microsoft.graph

重要

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

权限资源提供有关为 driveItem 资源授予的共享权限的信息。

共享权限具有许多不同的形式。 权限 资源通过资源上的不同方面表示这些不同的形式。

注意：OneDrive for Business和 SharePoint 文档库不返回 inheritedFrom 属性。

OneDrive for Business和 SharePoint 文档库不返回 inheritedFrom 属性。 grantedTo和grantedToIdentities将在未来弃用，响应将在相应的属性名称下分别迁移到grantedToV2和grantedToIdentitiesV2。

JSON 表示形式

以下 JSON 表示形式显示了资源类型。

{
  "id": "string (identifier)",
  "grantedTo": {"@odata.type": "microsoft.graph.identitySet"},
  "grantedToIdentities": [{"@odata.type": "microsoft.graph.identitySet"}],
  "grantedToV2": {"@odata.type": "microsoft.graph.sharePointIdentitySet"},
  "grantedToIdentitiesV2": [{"@odata.type": "microsoft.graph.sharePointIdentitySet"}],
  "inheritedFrom": {"@odata.type": "microsoft.graph.itemReference"},
  "invitation": {"@odata.type": "microsoft.graph.sharingInvitation"},
  "link": {"@odata.type": "microsoft.graph.sharingLink"},
  "roles": ["string"],
  "shareId": "string",
  "expirationDateTime": "string (timestamp)",
  "hasPassword": "boolean"
}

属性

属性	类型	说明
id	String	在项目的所有权限中，某个权限的唯一标识符。 此为只读属性。
grantedToV2	SharePointIdentitySet	对于用户类型权限，此权限的用户和应用程序的详细信息。 只读。
grantedToIdentitiesV2	集合（SharePointIdentitySet）	对于链接类型权限，被授予权限的用户的详细信息。 只读。
invitation	SharingInvitation	此权限的全部关联共享邀请的详细信息。 只读。
inheritedFrom	ItemReference	如果当前权限继承自上级，则提供对上级权限的引用。 此为只读属性。
link	SharingLink	提供当前权限的链接详细信息（如果它是链接类型权限）。 此为只读属性。
角色	集合（字符串）	权限的类型，例如，read。 有关角色的完整列表，请参阅 Roles 属性值部分。 只读。
shareId	String	可用于通过 shares API 访问此共享项的唯一令牌。 只读。
expirationDateTime	DateTimeOffset	DateTimeOffset 的格式 yyyy-MM-ddTHH:mm:ssZ 表示权限的过期时间。 DateTime.MinValue 指示没有为此权限设置过期时间。 可选。
HasPassword	布尔值	指示是否为此权限设置了密码。 此属性只出现在响应中。 可选。 只读。 仅适用于 OneDrive 个人版。
grantedTo（已弃用）	IdentitySet	对于用户类型权限，此权限的用户和应用程序的详细信息。 只读。
grantedToIdentities（已弃用）	Collection(IdentitySet)	对于类型权限，被授予权限的用户的详细信息。 只读。

角色属性值

值	说明
阅读	提供读取项的元数据和内容的功能。
写入	提供读取并修改项的元数据和内容的功能。
所有者	对于 SharePoint 和 OneDrive for Business，这表示所有者角色。

权限资源使用 facet 提供有关由该资源表示的权限类型的信息。

共享链接包含访问该项所需的唯一令牌。

具有 邀请 方面的权限表示通过邀请特定用户或组有权访问文件而添加的权限。

共享链接

具有 链接 facet 的权限表示在该项上创建的共享链接。 这些是最常见的权限类型。 共享链接提供可用于访问文件或文件夹的唯一 URL。 可以设置它们以通过各种方式授予访问权限。 例如，可使用 createLink API 创建适用于已登录到组织的任何用户的链接，或创建可用于任何人且无需登录的链接。 你可以使用 invite API 创建仅适用于特定人员的链接（无论他们是否在你的公司中）。

下面是一些共享链接示例。

查看链接

此查看链接向具有相应链接的任何人提供只读访问权限。

{
  "id": "1",
  "roles": ["read"],
  "link": {
    "scope": "anonymous",
    "type": "view",
    "webUrl": "https://onedrive.live.com/redir?resid=5D33DD65C6932946!70859&authkey=!AL7N1QAfSWcjNU8&ithint=folder%2cgif",
    "application": { "id": "1234", "displayName": "Sample Application" }
  },
  "shareId": "!LKj1lkdlals90j1nlkascl",
  "expirationDateTime": "0001-01-01T00:00:00Z"
}

编辑链接

此编辑链接向组织中具有相应链接的任何人提供读写访问权限。

{
  "id": "2ceefb3g32hh",
  "roles": ["write"],
  "link": {
    "scope": "organization",
    "type": "edit",
    "webUrl": "https://contoso.sharepoint.com/:w:/t/design/fj277ghautbb422707565gnvg23",
    "application": { "id": "1234", "displayName": "Sample Application" }
  },
  "shareId": "!LKj1lkdlals90j1nlkascl",
  "expirationDateTime": "0001-01-01T00:00:00Z"
}

现有的访问链接

此链接不会向用户授予任何其他权限。

{
  "id": "00000000-0000-0000-0000-000000000000",
  "roles": ["read"],
  "link": {
    "scope": "existingAccess",
    "type": "view",
    "webUrl": "https://contoso.sharepoint.com/:w:/t/design/Shared%20Documents/SampleDoc.docx?d=w12345",
  },
  "expirationDateTime": "0001-01-01T00:00:00Z"
}

特定人员链接

此链接向 grantedToIdentities 集合中的特定人员提供读写访问权限。

{
  "id": "3",
  "grantedToIdentities": [
    {
       "user": {
        "id": "35fij1974gb8832",
        "displayName": "Misty Suarez"
      }
    },
    {
       "user": {
        "id": "9397721fh4hgh73",
        "displayName": "Judith Clemons"
      }
    }
  ],
  "grantedToIdentitiesV2": [
    {
       "user": {
        "id": "35fij1974gb8832",
        "displayName": "Misty Suarez"
      },
      "siteUser": {
        "id": "1",
        "displayName": "Misty Suarez",
        "loginName": "Misty Suarez"
      }
    },
    {
       "user": {
        "id": "9397721fh4hgh73",
        "displayName": "Judith Clemons"
      },
      "siteUser": {
        "id": "2",
        "displayName": "Judith Clemons",
        "loginName": "Judith Clemons"
      }
    }
  ],
  "roles": ["write"],
  "link": {
    "webUrl": "https://contoso.sharepoint.com/:w:/t/design/a577ghg9hgh737613bmbjf839026561fmzhsr85ng9f3hjck2t5s",
    "application": { "id": "1234", "displayName": "Sample Application" }
  },
  "shareId": "!LKj1lkdlals90j1nlkascl",
  "expirationDateTime": "0001-01-01T00:00:00Z"
}

共享邀请

邀请或授权 API 发送的权限可以在邀请方面包含与已知帐户不匹配的电子邮件地址的其他信息。 在这种情况下，在兑换邀请链接之前，可能不会设置 grantedTo 属性，这在用户第一次单击链接并登录时发生。

{
  "id": "1",
  "roles": ["write"],
  "invitation": {
    "email": "jd@fabrikam.com",
    "signInRequired": true
  },
  "shareId": "FWxc1lasfdbEAGM5fI7B67aB5ZMPDMmQ11U",
  "expirationDateTime": "0001-01-01T00:00:00Z"
}

在用户兑换共享邀请后，grantedTo 属性将包含兑换权限的帐户的相关信息：

{
  "id": "1",
  "roles": ["write"],
  "grantedTo": {
    "user": {
      "id": "5D33DD65C6932946",
      "displayName": "Robin Danielsen"
    }
  },
  "grantedToV2": {
    "user": {
      "id": "5D33DD65C6932946",
      "displayName": "Robin Danielsen"
    },
    "siteUser": {
      "id": "1",
      "displayName": "Robin Danielsen",
      "loginName": "Robin Danielsen"
    }
  },
  "invitation": {
    "email": "rd@contoso.com",
    "signInRequired": true
  },
  "shareId": "FWxc1lasfdbEAGM5fI7B67aB5ZMPDMmQ11U",
  "expirationDateTime": "0001-01-01T00:00:00Z"
}

方法

方法	REST 路径
列出权限	GET /drive/items/{item-id}/permissions
获取权限	GET /drive/items/{item-id}/permissions/{id}
创建链接	POST /drive/items/{item-id}/createLink
邀请人员	POST /drive/items/{item-id}/invite
更新权限	PATCH /drive/items/{item-id}/permissions/{id}
删除权限	DELETE /drive/items/{item-id}/permissions/{id}
授予对共享链接的访问权限	POST /shares/{encoded-sharing-url}/permission/grant
撤销对共享链接的授权	POST /drive/items/{item-id}/permissions/{id}/revokeGrants