printDocument: createUploadSession

命名空间:microsoft.graph

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

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

注意:仅当关联的打印作业上有一个 printTask 处于状态 processing (由请求方应用创建的触发器启动)时,使用应用程序权限创建上传会话才会成功。 有关如何注册任务触发器的详细信息,请参阅 扩展通用打印以支持拉取打印。

API 可用性

此 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 表示要上传的二进制文件的属性。

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

对于 OXPS 到 PDF 的转换,需要作为 application/oxps 支持 application/pdf. 满足以下所有条件时,通用打印将 OXPS 转换为 PDF:

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

响应

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

注意:作为 uploadSession 响应对象的一部分返回的 uploadUrl 属性是一个不透明的 URL,用于PUT后续查询上传文件的字节范围。 它包含后续查询(在 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"
    ]
}