Cargar documentos mediante la API de Impresión universal de Microsoft GraphUpload documents using the Microsoft Graph Universal Print API

Para imprimir un documento con la API de impresión universal de Microsoft Graph, cree un trabajo de impresión, cargue un documento y luego inicie el trabajo de impresión.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 artículo describe cómo cargar un documento, lo que comienza con crear una sesión de carga.This article describes how to upload a document, which starts with creating an upload session.

Para cargar un archivo o una parte de un archivo, la aplicación hace una solicitud PUT al valor uploadUrl recibido en la respuesta 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. Puede cargar el archivo completo o dividir el archivo en varios intervalos de bytes, siempre y cuando el número máximo de bytes de cualquier solicitud dada sea 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.

Los segmentos del archivo pueden cargarse en cualquier orden y se pueden cargar en paralelo, con hasta cuatro solicitudes 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. Cuando se cargan todos los segmentos binarios de un documento, el archivo binario está vinculado al printDocument .When all the binary segments of document are uploaded, the binary file is linked to the printDocument .

Solicitud HTTPHTTP request

Realice una solicitud PUT al valor uploadUrl recibido en la respuesta createUploadSession .Make a PUT request to the uploadUrl value received in the createUploadSession response.

Encabezados de solicitudRequest headers

NombreName DescripciónDescription
Content-RangeContent-Range bytes {startByteIndex}-{endByteIndex}‬/{documentSizeInBytes}.bytes {startByteIndex}-{endByteIndex}‬/{documentSizeInBytes}. Necesario.Required.
Content-LengthContent-Length {contentLength}‬ Necesario.{contentLength}‬ Required.

Cuerpo de solicitudRequest body

El cuerpo de la solicitud es un blob binario que contiene los bytes del documento que se especifican como un rango de bytes inclusivo en el encabezado 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.

EjemploExample

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>

Respuesta HTTPHTTP response

Cuando se complete la solicitud, el servidor responderá con 202 Accepted si existen más intervalos de bytes que necesitan cargarse.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"]
}

Su aplicación puede usar el valor nextExpectedRanges para determinar dónde comenzar el siguiente intervalo de bytes.Your app can use the nextExpectedRanges value to determine where to start the next byte range. Es posible que vea varios intervalos especificados, lo que indica las partes del archivo que aún no ha recibido el servidor.You might see multiple ranges specified, indicating parts of the file that the server has not yet received. La propiedad nextExpectedRanges indica intervalos del archivo que no se han recibido y no un patrón de cómo debe cargar el archivo la aplicación.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"
  ]
}

ComentariosRemarks

  • Cuando se produzcan errores en los que el cliente envíe un fragmento que el servidor ya ha recibido, el servidor responderá HTTP 416 Requested Range Not Satisfiable. Puede solicitar el estado de la carga para obtener una lista más detallada de los intervalos que faltan.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 el encabezado de autorización al emitir la llamada PUT puede resultar en una respuesta HTTP 401 Unauthorized.Including the Authorization header when issuing the PUT call might result in a HTTP 401 Unauthorized response. El token de portador y encabezado de autorización solo se debe enviar al crear sesión de carga.The Authorization header and bearer token should only be sent when creating upload session. No se debe incluir al cargar datos en la sesión de carga.It should be not be included when uploading data to upload session.

Finalización de un archivoCompleting a file

Cuando se reciba el último intervalo de bytes de un archivo, el servidor responderá con un HTTP 201 Created.When the last byte range of a file is received, the server will response with an HTTP 201 Created. El cuerpo de la respuesta también incluirá el conjunto de propiedades del printDocument asociado.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
}

Nota: la sesión de carga se elimina una vez que se completa la carga del documento.Note: Upload session is deleted after document upload is complete.

Obtener la sesión de cargaGet the upload session

Para obtener la sesión de carga, envíe una solicitud GET a la dirección URL de carga.To get upload session, send a GET request to the upload URL.

SolicitudRequest

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

RespuestaResponse

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

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

Cancelar la sesión de cargaCancel the upload session

Para cancelar una sesión de carga, envíe una solicitud DELETE a la dirección URL de carga.To cancel an upload session, send a DELETE request to the upload URL. Debe utilizarse en los casos en los que se anula la carga, por ejemplo, si el usuario cancela la transferencia.This should be used in scenarios where the upload is aborted, for example, if the user cancels the transfer.

Los archivos temporales y la sesión de carga que los acompaña se limpian automáticamente cuando pasa la expirationDateTime .Temporary files and their accompanying upload session are automatically cleaned up after the expirationDateTime has passed.

SolicitudRequest

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

RespuestaResponse

HTTP/1.1 204 No Content