driveItem: previewdriveItem: preview

命名空间:microsoft.graphNamespace: microsoft.graph


/betaMicrosoft Graph 中的版本下的 api 可能会发生更改。APIs under the /beta version in Microsoft Graph are subject to change. 不支持在生产应用程序中使用这些 API。Use of these APIs in production applications is not supported.

此操作允许您获取项目的短生存期可嵌入 Url,以呈现临时预览。This action allows you to obtain short-lived embeddable URLs for an item in order to render a temporary preview.

如果要获取持续生存期的可嵌入链接,请改用 createLink API。If you want to obtain long-lived embeddable links, use the createLink API instead.

注意:****预览操作当前仅适用于 SharePoint 和 OneDrive for business。Note: The preview action is currently only available on SharePoint and OneDrive for Business.


要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

权限类型Permission type 权限(从最低特权到最高特权)Permissions (from least to most privileged)
委派(工作或学校帐户)Delegated (work or school account) Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.AllFiles.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
委派(个人 Microsoft 帐户)Delegated (personal Microsoft account) 不支持。Not supported.
应用程序Application Files.Read.All、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.AllFiles.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

HTTP 请求HTTP request

POST /drives/{driveId}/items/{itemId}/preview
POST /groups/{groupId}/drive/items/{itemId}/preview
POST /me/drive/items/{itemId}/preview
POST /sites/{siteId}/drive/items/{itemId}/preview
POST /users/{userId}/drive/items/{itemId}/preview
POST /shares/{shareId}/driveItem/preview

请求正文Request body

请求正文定义您的应用程序所请求的可嵌入 URL 的属性。The body of the request defines properties of the embeddable URL your application is requesting. 请求应为具有以下属性的 JSON 对象。The request should be a JSON object with the following properties.

名称Name 类型Type 说明Description
格式viewer 字符串string 可选。Optional. 要使用的预览应用。Preview app to use. onedriveoffice)。onedrive or office. 如果为 null,则将自动选择合适的查看器。If null, a suitable viewer will be chosen automatically.
chromelesschromeless 布尔boolean 可选。Optional. 如果 true (默认) ,则嵌入的视图将不包含任何控件。If true (default), the embedded view will not include any controls.
allowEditallowEdit 布尔boolean 可选。Optional. 如果 true 是,则可以从嵌入的 UI 编辑该文件。If true, the file can be edited from the embedded UI.
pagepage string/numberstring/number 可选。Optional. 要从其开始的文档的页码(如果适用)。Page number of document to start at, if applicable. 为在文件类型(如 ZIP)周围的将来用例指定为字符串。Specified as string for future use cases around file types such as ZIP.
zoomzoom numbernumber 可选。Optional. 要从其开始的缩放级别(如果适用)。Zoom level to start at, if applicable.


    "getUrl": "",
    "postParameters": "param1=value&param2=another%20value",
    "postUrl": ""

响应将是一个包含以下属性的 JSON 对象:The response will be a JSON object containing the following properties:

名称Name 类型Type 说明Description
getUrlgetUrl 字符串string 适用于使用 HTTP GET (iframe 等嵌入的 URL ) URL suitable for embedding using HTTP GET (iframes, etc.)
postUrlpostUrl 字符串string 适合使用 HTTP POST (表单 post、JS 等进行嵌入的 URL ) URL suitable for embedding using HTTP POST (form post, JS, etc.)
postParameterspostParameters 字符串string 如果使用 postUrl,则发布要包括的参数POST parameters to include if using postUrl

根据指定选项的 embed 支持的当前状态,可能会返回 getUrl、postUrl 或 both。Either getUrl, postUrl, or both might be returned depending on the current state of embed support for the specified options.

postParameters 是格式为的字符串 application/x-www-form-urlencoded ,如果向 postUrl 执行 POST,应相应地设置内容类型。postParameters is a string formatted as application/x-www-form-urlencoded, and if performing a POST to the postUrl the content-type should be set accordingly. 例如:For example:

Content-Type: application/x-www-form-urlencoded



注意: 此参数已弃用,将不会在 v1.0 终结点上可用。Note: This parameter is deprecated and will not be made available on the v1.0 endpoint.

查看器参数允许使用以下值。The following values are allowed for the viewer parameter.

类型值Type value 说明Description
(null) (null) 选择用于呈现文件的适当的应用程序。Chooses an appropriate app for rendering the file. 在大多数情况下,这将使用 onedrive 预览器,但可能因文件类型而异。In most cases this will use the onedrive previewer, but may vary by file type.
onedrive 使用 OneDrive 预览器应用程序呈现文件。Use the OneDrive previewer app to render the file.
office 使用 Office 的 web 版本呈现文件。Use the web version of Office to render the file. 仅对 Office 文档有效。Only valid for Office documents.

Chrome vs chromelessChrome vs chromeless

注意: 此参数已弃用,将不会在 v1.0 终结点上可用。Note: This parameter is deprecated and will not be made available on the v1.0 endpoint.

如果 chromeless 为 true,预览将是文件的简略呈现。If chromeless is true, the preview will be a bare rendering of the file. 否则,可能会显示其他工具栏/按钮以与文档/视图进行交互。Otherwise, there may be additional toolbars/buttons displayed for interacting with the document/view.


注意: 此参数已弃用,将不会在 v1.0 终结点上可用。Note: This parameter is deprecated and will not be made available on the v1.0 endpoint.

如果 allowEdit 为 true,则文档可以通过嵌入预览的用户交互进行修改。If allowEdit is true, the document can be modified by user interaction with the embedded preview. 此功能可能不适用于所有预览版应用或文件类型。This capability may not be available for all preview apps or file types.


"" 和 "" page zoom 选项可能不适用于所有预览版应用,但如果预览应用支持它,则将应用 "" 和 "" 选项。The page and zoom options might not be available for all preview apps, but will be applied if the preview app supports it.