Faça o upload de documentos utilizando a API de Impressão Universal do Microsoft GraphUpload documents using the Microsoft Graph Universal Print API

Importante

A Microsoft está oferecendo temporariamente o uso das APIs de impressão em nuvem para gerenciar o Universal Print gratuitamente.Microsoft is temporarily offering usage of the cloud printing APIs to manage Universal Print at no charge. A Microsoft espera cobrar pelo uso de algumas ou todas essas APIs no futuro.Microsoft expects to charge for the use of some or all of these APIs in the future. A Microsoft fornecerá um aviso prévio sobre alterações de preçosMicrosoft will provide advanced notice of pricing changes.

Para imprimir um documento utilizando a API de Impressão Universal no Microsoft Graph, você cria um trabalho de impressão, faz o upload do documento e, em seguida, inicia o trabalho de impressão.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. Este artigo descreve como fazer o upload de um documento, que começa com a criação de uma sessão de upload .This article describes how to upload a document, which starts with creating an upload session.

Para fazer o upload de um arquivo, ou de parte de um arquivo, seu aplicativo faz uma solicitação PUT para o valor uploadUrl recebido na resposta createUploadSession.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. Você pode fazer o upload de todo o arquivo ou dividi-lo em vários intervalos de bytes, desde que o máximo de bytes em qualquer solicitação seja inferior a 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.

É possível fazer o upload dos segmentos do arquivo em qualquer ordem e o upload pode ser feito em paralelo, com até quatro solicitações simultâneas.The segments of the file can be uploaded in any order and can be uploaded in parallel, with up to four concurrent requests. Quando todos os segmentos binários do documento são carregados, o arquivo binário é vinculado ao printDocument.When all the binary segments of document are uploaded, the binary file is linked to the printDocument.

Solicitação HTTPHTTP request

Faça uma solicitação PUT para o valor uploadUrl recebido na resposta createUploadSession.Make a PUT request to the uploadUrl value received in the createUploadSession response.

Cabeçalhos de solicitaçãoRequest headers

NomeName DescriçãoDescription
Intervalo do conteúdoContent-Range bytes {startByteIndex}-{endByteIndex}/{documentSizeInBytes}.bytes {startByteIndex}-{endByteIndex}‬/{documentSizeInBytes}. Obrigatório.Required.
Comprimento do ConteúdoContent-Length {contentLength} Obrigatório.{contentLength}‬ Required.

Corpo da solicitaçãoRequest body

O corpo da solicitação é um blob binário que contém os bytes do documento que são especificados como um intervalo de bytes inclusivo no cabeçalho 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.

ExemploExample

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>

Resposta HTTP:HTTP response

Quando a solicitação for concluída, o servidor responderá com 202 Accepted se houver mais intervalos de bytes que precisem ser carregados.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"]
}

O aplicativo pode usar o valor de nextExpectedRanges para determinar onde iniciar o próximo intervalo de bytes.Your app can use the nextExpectedRanges value to determine where to start the next byte range. Você pode ver vários intervalos especificados, indicando as partes do arquivo que o servidor ainda não recebeu.You might see multiple ranges specified, indicating parts of the file that the server has not yet received. A propriedade nextExpectedRanges indica intervalos do arquivo que não foram recebidos, e não um padrão para como seu aplicativo deve carregar o arquivo.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"
  ]
}

ComentáriosRemarks

  • Em falhas quando o cliente enviou um fragmento que o servidor já havia recebido, o servidor responderá com HTTP 416 Requested Range Not Satisfiable. Você pode solicitar o status do upload para obter uma lista mais detalhada dos intervalos que estão faltando.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.
  • Incluir o Cabeçalho de Autorização ao emitir a chamada PUTpode resultar em uma respostaHTTP 401 Unauthorized.Including the Authorization header when issuing the PUT call might result in a HTTP 401 Unauthorized response. O Cabeçalho de Autorização e o token do portador devem ser enviados apenas durante a criação da sessão de upload.The Authorization header and bearer token should only be sent when creating upload session. Não deve ser incluído ao enviar dados para a sessão de upload.It should be not be included when uploading data to upload session.

Concluindo um arquivoCompleting a file

Quando o último intervalo de bytes de um arquivo for recebido, o servidor responderá com um HTTP 201 Created.When the last byte range of a file is received, the server will response with an HTTP 201 Created. O corpo da resposta também incluirá o conjunto de propriedades para o printDocument associado.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
}

Observação: A sessão de upload é excluída após a conclusão do upload do documento.Note: Upload session is deleted after document upload is complete.

Obtenha a sessão de uploadGet the upload session

Para obter a sessão de upload, envie uma solicitação GET para o URL de upload.To get upload session, send a GET request to the upload URL.

SolicitaçãoRequest

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

RespostaResponse

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

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

Cancelar a sessão de uploadCancel the upload session

Para cancelar uma sessão de upload, envie uma solicitação DELETE para o URL de upload.To cancel an upload session, send a DELETE request to the upload URL. Isso deve ser usado em cenários em que o upload é interrompido, por exemplo, se o usuário cancelar a transferência.This should be used in scenarios where the upload is aborted, for example, if the user cancels the transfer.

Os arquivos temporários e a sessão de carregamento que os acompanha são automaticamente limpos decorrido o valor de expirationDateTime.Temporary files and their accompanying upload session are automatically cleaned up after the expirationDateTime has passed.

SolicitaçãoRequest

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

RespostaResponse

HTTP/1.1 204 No Content