printDocument：createUploadSession

命名空间：microsoft.graph

创建一个上传会话，允许应用以迭代方式上传链接到打印文档的二进制文件的范围。

作为响应的一部分，此操作返回可在后续顺序 PUT 查询中使用的上传 URL。 每个 PUT 操作的请求标头可用于指定要上传的字节的确切范围。 这允许恢复传输，以防在上传过程中断开网络连接。

注意：仅当关联的打印作业上具有 printTaskprocessing 状态（由请求应用创建的触发器启动）时，使用应用程序权限创建上传会话才会成功。 有关如何注册任务触发器的详细信息，请参阅 扩展通用打印以支持拉取打印。

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

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

权限

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

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

HTTP 请求

使用 打印机创建上传会话：

POST /print/printers/{id}/jobs/{id}/documents/{id}/createUploadSession

若要使用 printerShare (仅支持委派权限) 创建上传会话：

POST /print/shares/{id}/jobs/{id}/documents/{id}/createUploadSession

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Type application/json. 必需。

请求正文

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

参数 类型 说明
properties printDocumentUploadProperties 表示要上传的二进制文件的属性。

打印机/打印机共享应支持请求正文中 contentType 属性的值。 可以通过获取 printer/printerShare 的 printerCapabilities 来获取支持的内容类型。

对于 OXPS 到 PDF 的转换，需要 application/oxps 传递为支持 application/pdf的 printer/printerShare 的 contentType。 满足以下所有条件时，通用打印会将 OXPS 转换为 PDF：

  1. 打印机/打印机共享在 printerCapabilities 中支持application/pdf。
  2. printerCapabilities 不支持打印机/打印机共享application/oxps。
  3. 请求正文application/oxps中 contentType 属性的值为 。

响应

如果成功，此方法在响应正文中返回响应 200 OK 代码和新的 uploadSession 对象。

注意：作为 uploadSession 响应对象的一部分返回的 uploadUrl 属性是后续 PUT 查询上传文件的字节范围的不透明 URL。 它包含相应的身份验证令牌，用于在 expirationDateTime 之前过期的后续PUT查询。 请勿更改此 URL。

示例

以下示例演示如何创建可在指定 printDocument 的后续文件上传操作中使用的上传会话。

请求

POST https://graph.microsoft.com/v1.0/print/printers/{printerId}/jobs/{printJobId}/documents/{printDocumentId}/createUploadSession
Content-Type: application/json

{
  "properties": {
    "documentName": "TestFile.pdf",
    "contentType": "application/pdf", 
    "size": 4533322
  }
}

响应

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://print.print.microsoft.com/uploadSessions/5400be13-5a4e-4c20-be70-90c85bfe5d6e?tempauthtoken={token}",
    "expirationDateTime": "2020-10-25T02:19:38.1694207Z",
    "nextExpectedRanges": [
        "0-4533321"
    ]
}
  • Last updated on