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. 打印机/打印机共享不支持 application/oxpsprinterCapabilities
  3. 请求正文application/oxpscontentType 属性的值为 。

响应

如果成功,此方法在响应正文中返回响应 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"
    ]
}