使用 Microsoft Graph 通用打印 API 上载文档Upload documents using the Microsoft Graph Universal Print API

若要使用 Microsoft Graph 中的通用打印 API 打印文档,你需要 创建一个打印作业、上传文档,然后 启动打印作业To print a document using the Universal Print API in Microsoft Graph, you create a print job, upload a document, and then start the print job. 本文介绍了如何上传文档,首先需要 创建一个上载会话This article describes how to upload a document, which starts with creating an upload session.

若要上传文件或文件的一部分,你的应用可以对在 createUploadSession 响应中收到的 uploadUrl 值发出 PUT 请求。To upload a file, or a portion of a file, your app makes a PUT request to the uploadUrl value received in the createUploadSession response. 可以上传整个文件,也可以将文件拆分为多个字节范围,只要任意给定请求中的最大字节数小于 10 MB 即可。You can upload the entire file, or split the file into multiple byte ranges, as long as the maximum bytes in any given request is less than 10 MB.

可按任意顺序上传文件的片段,并且最多可并行上传四个并发请求。The segments of the file can be uploaded in any order and can be uploaded in parallel, with up to four concurrent requests. 当上载文档的所有二进制片段后,二进制文件将链接到 printDocumentWhen all the binary segments of document are uploaded, the binary file is linked to the printDocument .

HTTP 请求HTTP request

createUploadSession 响应中收到的 uploadUrl 值发出 PUT 请求。Make a PUT request to the uploadUrl value received in the createUploadSession response.

请求标头Request headers

名称Name DescriptionDescription
Content-RangeContent-Range bytes {startByteIndex}-{endByteIndex}‬/{documentSizeInBytes}。bytes {startByteIndex}-{endByteIndex}‬/{documentSizeInBytes}. 必填。Required.
Content-LengthContent-Length 需要 {contentLength}。{contentLength}‬ Required.

请求正文Request body

请求正文是一个二进制 blob,其中包含在 Content-Range 标头中指定为 非独占 字节范围的文档的字节数。The request body is a binary blob containing the bytes of the document that are specified as an inclusive byte range in the Content-Range header.

示例Example

PUT https://print.print.microsoft.com/uploadSessions/5400be13-5a4e-4c20-be70-90c85bfe5d6e?tempauthtoken={token}
Content-Range: bytes=0-72796/4533322
Content-Length: 72797

<bytes 0-72796 of the file>

HTTP 响应HTTP response

当此请求完成时,如果还需要上传其他字节范围,服务器将会返回 202 Accepted 作为响应。When the request is complete, the server will respond with 202 Accepted if there are more byte ranges that need to be uploaded.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "expirationDateTime": "2020-10-25T02:19:38.1694207Z",
  "nextExpectedRanges": ["72797-4533321"]
}

应用可以使用 nextExpectedRanges 值来确定开始上传下一字节范围的位置。Your app can use the nextExpectedRanges value to determine where to start the next byte range. 可能会发现指定的多个范围,这些范围指明了服务器尚未收到的文件部分。You might see multiple ranges specified, indicating parts of the file that the server has not yet received. nextExpectedRanges 属性指示尚未收到的文件的范围,而不是应用应上传文件的方式。The nextExpectedRanges property indicates ranges of the file that have not been received and not a pattern for how your app should upload the file.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "expirationDateTime": "2020-10-25T02:19:38.1694207Z",
  "nextExpectedRanges": [
  "72797-72897",
  "78929-4533322"
  ]
}

备注Remarks

  • 如果因客户端发送了服务器已接收的片段导致失败,服务器将响应 HTTP 416 Requested Range Not Satisfiable。可以 请求上载状态 以获取缺少范围的详细列表。On failures when the client sent a fragment the server had already received, the server will respond with HTTP 416 Requested Range Not Satisfiable. You can request upload status to get a more detailed list of missing ranges.
  • 在发出 PUT 调用时添加授权标头可能会导致 HTTP 401 Unauthorized 响应。Including the Authorization header when issuing the PUT call might result in a HTTP 401 Unauthorized response. 授权标头和承载令牌只应在创建上传会话时发送。The Authorization header and bearer token should only be sent when creating upload session. 将数据上载到上载会话时,不应将其包含在内。It should be not be included when uploading data to upload session.

完成文件Completing a file

当接收到一个文件的最后一个字节范围时,服务器将在 HTTP 201 Created 上响应。When the last byte range of a file is received, the server will response with an HTTP 201 Created. 响应正文中还将包括 printDocument 相关联的属性集。The response body will also include the property set for the associated printDocument .

PUT https://print.print.microsoft.com/uploadSessions/5400be13-5a4e-4c20-be70-90c85bfe5d6e?tempauthtoken={token}
Content-Length: 10
Content-Range: bytes 4533312-4533321/4533322

<final bytes of the file>
HTTP/1.1 201 Created
Content-Type: application/json

{
   "id": "9001bcd9-e36a-4f51-bfc6-140c3ad7f9f7",
   "documentName": "TestFile.pdf",
   "contentType": "application/pdf", 
   "size": 4533322
}

注意: 文档上传完成后,将会删除上传会话。Note: Upload session is deleted after document upload is complete.

获取上载会话Get the upload session

若要获取上载会话,请向上载 URL 发送 GET 请求。To get upload session, send a GET request to the upload URL.

请求Request

GET https://print.print.microsoft.com/uploadSessions/5400be13-5a4e-4c20-be70-90c85bfe5d6e?tempauthtoken={token}

响应Response

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

{
  "expirationDateTime": "2020-10-25T02:19:38.1694207Z",
  "nextExpectedRanges": [
  "72797-72897",
  "78929-4533322"
  ]
}

取消上传会话Cancel the upload session

若要取消上载会话,请向上载 UR L 发送 DELETE 请求。To cancel an upload session, send a DELETE request to the upload URL. 应在上载中止(例如,如果用户取消传输)的情况下使用上述方法。This should be used in scenarios where the upload is aborted, for example, if the user cancels the transfer.

expirationDateTime 通过后,系统将自动清理临时文件及其随附的上传会话。Temporary files and their accompanying upload session are automatically cleaned up after the expirationDateTime has passed.

请求Request

DELETE https://print.print.microsoft.com/uploadSessions/5400be13-5a4e-4c20-be70-90c85bfe5d6e?tempauthtoken={token}

响应Response

HTTP/1.1 204 No Content