Cargar documentos mediante la API de Impresión universal de Microsoft Graph

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. Este artículo describe cómo cargar un documento, lo que comienza con crear una sesión de carga.

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. 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.

Los segmentos del archivo pueden cargarse en cualquier orden y se pueden cargar en paralelo, con hasta cuatro solicitudes simultáneas. Cuando se cargan todos los segmentos binarios de un documento, el archivo binario está vinculado al printDocument.

Nota: Si la aplicación divide un archivo en varios intervalos de bytes, se recomienda que el tamaño de cada intervalo de bytes sea un múltiplo de 200 KB a menos que se use el SDK de Microsoft Graph, lo que requiere que el tamaño del segmento sea un múltiplo de 320 KB.

Cargar un archivo

Solicitud

Realice una solicitud PUT al valor uploadUrl recibido en la respuesta createUploadSession.

Encabezados de solicitud

Nombre	Descripción
Content-Range	bytes {startByteIndex}-{endByteIndex}‬/{documentSizeInBytes}. Necesario.
Content-Length	{contentLength}‬ Necesario.

Cuerpo de solicitud

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.

Ejemplo

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>

Aquí, 0 y 72 796 son los índices de inicio y finalización del segmento de archivos y 4 533 322 es el tamaño del documento.

Respuesta

Cuando se complete la solicitud, el servidor responderá con 202 Accepted si existen más intervalos de bytes que necesitan cargarse.

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. Es posible que vea varios intervalos especificados, lo que indica las partes del archivo que aún no ha recibido el servidor. 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.

HTTP/1.1 202 Accepted
Content-Type: application/json

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

Comentarios

• 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.
• Incluir el encabezado Authorization al hacer la llamada PUT puede resultar en una respuesta HTTP 401 Unauthorized. El token de portador y el encabezado de autorización solo se deben enviar al crear la sesión de carga. No se debe incluir al cargar datos en la sesión de carga.

Completar una carga de archivos

Cuando se reciba el último intervalo de bytes de un archivo, el servidor responderá con un HTTP 201 Created. El cuerpo de la respuesta también incluirá el conjunto de propiedades del printDocument asociado.

Solicitud

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>

Respuesta

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 complete la carga del documento.

Obtener la sesión de carga

Para obtener la sesión de carga, envíe una solicitud GET a la dirección URL de carga.

Solicitud

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

Respuesta

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

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

Ejemplos de código: crear una sesión de carga y cargar documentos

C#

            GraphServiceClient graphClient = new GraphServiceClient( authProvider );

            var properties = new PrintDocumentUploadProperties
            {
	            DocumentName = "TestFile.pdf",
	            ContentType = "application/pdf",
	            Size = 4533322
            };

            var uploadSession = await graphClient.Print.Printers["{printer-id}"].Jobs["{printJob-id}"].Documents["{printDocument-id}"]
            	.CreateUploadSession(properties)
	            .Request()
	            .PostAsync()

            // if using Graph SDK, maxSliceSize should in multiples of 320 KiB
            int maxSliceSize = 320 * 1024;
            var fileUploadTask =
                new LargeFileUploadTask<PrintDocument>(uploadSession, fileStream, maxSliceSize);

            // Create a callback that is invoked after each slice is uploaded
            IProgress<long> progress = new Progress<long>(prog =>
            {
                Console.WriteLine($"Uploaded {prog} bytes of {fileStream.Length} bytes");
            });

            // Upload the file

            var uploadResult = await fileUploadTask.UploadAsync(progress);

JavaScript

    const options = {
      authProvider,
    };
    const client = Client.init(options);
   
    const fileName = "test.txt";
    const file = fs.readFileSync(`./${fileName}`);
    const stats = fs.statSync(`./${fileName}`);
    const requestUrl ="https://graph.microsoft.com/v1.0/print/shares/{id}/jobs/{id}/documents/{id}/createuploadsession"
    const payload = {
        "properties": {
            "documentName": fileName,
            "contentType": "application/pdf",
            "size": stats.size
        }
    }
    const uploadSession = await LargeFileUploadTask.createUploadSession(client, requestUrl, payload);

    // Create FileUpload object. 
    /* Note:
     * As alternatives to using a javascript `File` object to create a `FileUpload`, 
     * you can use a `ReadStream` object to create a `StreamUpload`.
     * const readStream = fs.createReadStream(`./test/sample_files/${fileName}`);
     * const fileObject = new StreamUpload(readStream, fileName, totalsize);
     * OR
     * you can also create a custom implementation of the `FileObject` interface.
     * FileUpload and StreamUpload classes are available in 3.0.0 version of the Microsoft Graph JS client library.
     */
    const fileObject = new FileUpload(file, file.name, file.size);
     
    // Create LargeFileUploadTask object and start the upload() task
    const task = new LargeFileUploadTask(client, fileObject, uploadSession);
    const uploadResponse = await task.upload();

Cancelar la sesión de carga

Para cancelar una sesión de carga, envíe una solicitud DELETE a la dirección URL de carga. Esto debe usarse en escenarios en los que se anule la carga; por ejemplo, si el usuario cancela la transferencia.

Los archivos temporales y la sesión de carga que los acompaña se limpian automáticamente cuando pasa la expirationDateTime.

Solicitud

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

Respuesta

HTTP/1.1 204 No Content