Charger des documents à l’aide de l’API d’impression universelle Microsoft Graph

Pour imprimer un document à l’aide de l’API d’impression universelle dans Microsoft Graph, vous créer un travail d’impression, charger un document et démarrer le travail d’impression. Cet article décrit la procédure à suivre pour charger un document, qui commence par la création d’une session de téléchargement.

Pour charger a fichier, ou une partie d’un fichier, votre application envoie une demande PUT à la valeur uploadUrl reçue dans la réponse createUploadSession. Vous pouvez charger l’intégralité du fichier, ou le diviser en plusieurs plages d’octets, tant que le nombre maximal d’octets de chaque demande est inférieur à 10 Mo.

Les segments du fichier peuvent être chargés dans n’importe quel ordre et peuvent être chargés en parallèle, avec un maximum de quatre demandes simultanées. Une fois tous les segments binaires du document chargés, le fichier binaire est lié à printDocument.

Remarque : Si votre application fractionne un fichier en plusieurs plages d’octets, nous vous recommandons de définir la taille de chaque plage d’octets sur un multiple de 200 Ko, sauf si vous utilisez le Kit de développement logiciel (SDK) Microsoft Graph, ce qui nécessite que la taille du segment soit un multiple de 320 Ko.

Chargement d’un fichier

Demande

Envoyez une demande PUT à la valeur uploadUrl reçue dans la réponse createUploadSession.

En-têtes de demande

Nom	Description
Content-Range	octets {startByteIndex}-{endByteIndex}‬/{documentSizeInBytes}. Obligatoire.
Content-Length	{contentLength} est obligatoire.

Corps de la demande

Le corps de la demande est un Blob binaire contenant les octets du document spécifiés sous forme de plage d’octets incluse dans l’en-tête de Content-Range.

Exemple

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>

Ici, 0 et 72796 sont les index de début et de fin du segment de fichier et 4533322 est la taille du document.

Réponse

Quand la demande est terminée, le serveur répond avec 202 Accepted si d’autres plages d’octets doivent être chargées.

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

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

Votre application peut utiliser la valeur nextExpectedRanges pour déterminer où commencer la plage d’octets suivante. Plusieurs plages peuvent être spécifiées, indiquant les parties du fichier que le serveur n’a pas encore reçues. La propriété nextExpectedRanges indique les plages du fichier qui n’ont pas été reçues et qui ne doivent pas être respectées pendant le chargement du fichier.

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

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

Remarques

• En cas d’échec, lorsque le client envoie un fragment que le serveur a déjà reçu, le serveur renvoie la réponse HTTP 416 Requested Range Not Satisfiable. Vous pouvez demander le statut de chargement pour obtenir une liste plus détaillée des plages manquantes.
• L’inclusion de l’en-tête Authorization lors de l’appel PUT peut provoquer une réponse HTTP 401 Unauthorized. Vous ne devez envoyer l’en-tête d’autorisation et le jeton du porteur que lors de la création de la session de chargement. Vous ne devez pas inclure cet élément lors du chargement des données dans la session de chargement.

Effectuer un chargement de fichier

Lorsque le serveur reçoit la dernière plage d’octets d’un fichier, il renvoie la réponse HTTP 201 Created. Le corps de la réponse inclut également le jeu de propriétés du document printDocument associé.

Demande

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>

Réponse

HTTP/1.1 201 Created
Content-Type: application/json

{
   "id": "9001bcd9-e36a-4f51-bfc6-140c3ad7f9f7",
   "documentName": "TestFile.pdf",
   "contentType": "application/pdf", 
   "size": 4533322
}

Remarque : le programme supprime la session de chargement une fois le chargement du document terminé.

Obtenir la session de chargement

Pour obtenir la session de chargement, envoyez une demande GET à l’URL de chargement.

Demande

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

Réponse

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

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

Exemples de code : créer une session de chargement, puis charger des documents

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();

Annuler la session de chargement

Pour annuler une session de chargement, envoyez une demande DELETE à l’URL de chargement. Cela doit être utilisé dans les scénarios où le chargement est abandonné ; par exemple, si l’utilisateur annule le transfert.

Les fichiers temporaires et leur session de chargement associée sont automatiquement nettoyés lorsque la date expirationDateTime est expirée.

Demande

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

Réponse

HTTP/1.1 204 No Content