命名空间:microsoft.graph
重要
Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。
创建一个上传会话,此会话允许应用迭代上传链接到打印文档的二进制文件范围。
作为响应的一部分,此操作将返回可在后续顺序 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 对象。
printer/printerShare 应支持请求正文中 contentType 属性的值。 可以通过获取 printer/ printerShare 的 printerCapabilities 来获取支持的内容类型。
对于 OXPS 到 PDF 的转换,需要作为 application/oxps 支持 application/pdf.
满足以下所有条件时,通用打印将 OXPS 转换为 PDF:
-
printerCapabilities 中的打印机/打印机共享支持
application/pdf。
- printerCapabilities 不支持
application/oxps打印机/打印机共享。
- 请求正文中 contentType 属性的值为
application/oxps。
响应
如果成功,此方法将在响应正文中返回响应 200 OK 代码和新的 uploadSession 对象。
注意:作为 uploadSession 响应对象的一部分返回的 uploadUrl 属性是一个不透明的 URL,用于PUT后续查询上传文件的字节范围。 它包含后续查询(在 expirationDateTime 到期)的PUT相应身份验证令牌。 请勿更改此 URL。
示例
下面的示例显示了如何创建一个上传会话,您可以在后续文件上传操作中使用该会话上传到指定的 printDocument。
请求
POST https://graph.microsoft.com/beta/print/shares/1c879027-5120-4aaf-954a-ebfd509a3bcc/jobs/46207/documents/9001bcd9-e36a-4f51-bfc6-140c3ad7f9f7/createUploadSession
Content-type: application/json
{
"properties": {
"documentName": "TestFile.pdf",
"contentType": "application/pdf",
"size": 4533322
}
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Print.Shares.Item.Jobs.Item.Documents.Item.CreateUploadSession;
using Microsoft.Graph.Beta.Models;
var requestBody = new CreateUploadSessionPostRequestBody
{
Properties = new PrintDocumentUploadProperties
{
DocumentName = "TestFile.pdf",
ContentType = "application/pdf",
Size = 4533322L,
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Print.Shares["{printerShare-id}"].Jobs["{printJob-id}"].Documents["{printDocument-id}"].CreateUploadSession.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphprint "github.com/microsoftgraph/msgraph-beta-sdk-go/print"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
//other-imports
)
requestBody := graphprint.NewCreateUploadSessionPostRequestBody()
properties := graphmodels.NewPrintDocumentUploadProperties()
documentName := "TestFile.pdf"
properties.SetDocumentName(&documentName)
contentType := "application/pdf"
properties.SetContentType(&contentType)
size := int64(4533322)
properties.SetSize(&size)
requestBody.SetProperties(properties)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createUploadSession, err := graphClient.Print().Shares().ByPrinterShareId("printerShare-id").Jobs().ByPrintJobId("printJob-id").Documents().ByPrintDocumentId("printDocument-id").CreateUploadSession().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.print.shares.item.jobs.item.documents.item.createuploadsession.CreateUploadSessionPostRequestBody createUploadSessionPostRequestBody = new com.microsoft.graph.beta.print.shares.item.jobs.item.documents.item.createuploadsession.CreateUploadSessionPostRequestBody();
PrintDocumentUploadProperties properties = new PrintDocumentUploadProperties();
properties.setDocumentName("TestFile.pdf");
properties.setContentType("application/pdf");
properties.setSize(4533322L);
createUploadSessionPostRequestBody.setProperties(properties);
var result = graphClient.print().shares().byPrinterShareId("{printerShare-id}").jobs().byPrintJobId("{printJob-id}").documents().byPrintDocumentId("{printDocument-id}").createUploadSession().post(createUploadSessionPostRequestBody);
const options = {
authProvider,
};
const client = Client.init(options);
const uploadSession = {
properties: {
documentName: 'TestFile.pdf',
contentType: 'application/pdf',
size: 4533322
}
};
await client.api('/print/shares/1c879027-5120-4aaf-954a-ebfd509a3bcc/jobs/46207/documents/9001bcd9-e36a-4f51-bfc6-140c3ad7f9f7/createUploadSession')
.version('beta')
.post(uploadSession);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Print\Shares\Item\Jobs\Item\Documents\Item\CreateUploadSession\CreateUploadSessionPostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\PrintDocumentUploadProperties;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new CreateUploadSessionPostRequestBody();
$properties = new PrintDocumentUploadProperties();
$properties->setDocumentName('TestFile.pdf');
$properties->setContentType('application/pdf');
$properties->setSize(4533322);
$requestBody->setProperties($properties);
$result = $graphServiceClient->escapedPrint()->shares()->byPrinterShareId('printerShare-id')->jobs()->byPrintJobId('printJob-id')->documents()->byPrintDocumentId('printDocument-id')->createUploadSession()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Devices.CloudPrint
$params = @{
properties = @{
documentName = "TestFile.pdf"
contentType = "application/pdf"
size = 4533322
}
}
New-MgBetaPrintShareJobDocumentUploadSession -PrinterShareId $printerShareId -PrintJobId $printJobId -PrintDocumentId $printDocumentId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.print.shares.item.jobs.item.documents.item.create_upload_session.create_upload_session_post_request_body import CreateUploadSessionPostRequestBody
from msgraph_beta.generated.models.print_document_upload_properties import PrintDocumentUploadProperties
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CreateUploadSessionPostRequestBody(
properties = PrintDocumentUploadProperties(
document_name = "TestFile.pdf",
content_type = "application/pdf",
size = 4533322,
),
)
result = await graph_client.print.shares.by_printer_share_id('printerShare-id').jobs.by_print_job_id('printJob-id').documents.by_print_document_id('printDocument-id').create_upload_session.post(request_body)
响应
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$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"
]
}