Hochladen von Dokumenten mithilfe der Microsoft Graph-API für universelles Drucken

Um ein Dokument mit der API für universelles Drucken in Microsoft Graph zu drucken, erstellen Sie einen Druckauftrag, laden ein Dokument hoch und starten dann den Druckauftrag. In diesem Artikel wird das Hochladen eines Dokuments, beginnend mit der Erstellung einer Uploadsitzung, beschrieben.

Zum Hochladen einer Datei oder eines Teils einer Datei sendet die App eine PUT-Anfrage an den Wert uploadUrl, der ihr in der createUploadSession-Antwort übermittelt wurde. Sie können die gesamte Datei hochladen oder die Datei in Fragmente aufteilen, vorausgesetzt, die maximale Bytezahl pro Anforderung bleibt unter 10 MiB.

Die Segmente der Datei können in beliebiger Reihenfolge und parallel mit bis zu vier gleichzeitigen Anforderungen hochgeladen werden. Wenn alle Binärsegmente eines Dokuments hochgeladen werden, wird die Binärdatei mit printDocument verknüpft.

Hinweis: Wenn Ihre App eine Datei in mehrere Bytebereiche aufteilt, wird empfohlen, dass die Größe jedes Bytebereichs ein Vielfaches von 200 KB ist, es sei denn, Sie verwenden das Microsoft Graph-SDK, für das die Segmentgröße ein Vielfaches von 320 KB sein muss.

Hochladen einer Datei

Anforderung

Erstellen Sie eine PUT-Anforderung an den Wert uploadUrl, der ihr in der createUploadSession-Antwort übermittelt wurde.

Anforderungsheader

Name	Beschreibung
Content-Range	bytes {startByteIndex}-{endByteIndex}‬/{documentSizeInBytes}. Erforderlich.
Content-Length	{contentLength}‬ Erforderlich.

Anforderungstext

Der Anforderungstext ist ein binäres Blob, das die als inclusive-Bytebereich im Content-Range-Header angegebenen Bytes des Dokuments enthält.

Beispiel

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>

Hier sind 0 und 72796 die Start- und Endindizes des Dateisegments und 4533322 ist die Größe des Dokuments.

Antwort

Wenn die Anforderung abgeschlossen ist, antwortet der Server mit 202 Accepted, wenn es weitere Bytebereiche, die hochgeladen werden müssen.

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

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

Die App kann mithilfe des Werts nextExpectedRanges bestimmen, wo der nächste Bytebereich beginnen soll. Eventuell werden mehrere Bereiche angegeben. Sie stehen für Teile der Datei, die der Server noch nicht empfangen hat. Die Eigenschaft nextExpectedRanges gibt Dateibereiche an, die noch nicht empfangen wurden. Sie ist nicht als Muster für den Dateiupload der App zu verstehen.

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

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

Hinweise

• Wenn der Client bei Fehlern ein Fragment sendet, das der Server bereits empfangen hat, antwortet der Server mit HTTP 416 Requested Range Not Satisfiable. Sie können den Uploadstatus anfordern, um eine detailliertere Liste der fehlenden Bereiche zu erhalten.
• Das Hinzufügen der Authorization-Kopfzeile beim PUT-Anruf kann zu einer HTTP 401 Unauthorized-Antwort führen. Die Autorisierungskopfzeile und das Bearertoken sollten nur beim Erstellen der Uploadsitzung gesendet werden. Sie sollte beim Hochladen von Daten in die Uploadsitzung nicht einbezogen werden.

Abschließen eines Dateiuploads

Wenn der letzte Bytebereich einer Datei empfangen wird, antwortet der Server mit einer HTTP 201 Created. Der Antworttext enthält außerdem den Eigenschaftensatz für das zugeordnete printDocument.

Anforderung

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>

Antwort

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

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

Hinweis: Die Uploadsitzung wird gelöscht, nachdem der Upload des Dokuments abgeschlossen ist.

Abrufen der Uploadsitzung

Zum Abrufen einer Uploadsitzung senden Sie eine GET-Anforderung an die Upload-URL.

Anforderung

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

Antwort

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

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

Codebeispiele: Erstellen einer Uploadsitzung und Hochladen von Dokumenten

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

Abbrechen der Uploadsitzung

Zum Abbrechen einer Uploadsitzung senden Sie eine DELETE-Anforderung an die Upload-URL. Dies sollte in Szenarien verwendet werden, in denen der Upload abgebrochen wird. Beispielsweise, wenn der Benutzer die Übertragung abbricht.

Temporäre Dateien und die zugehörigen Uploadsitzungen werden automatisch bereinigt, wenn der über expirationDateTime festgelegte Termin abgelaufen ist.

Anforderung

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

Antwort

HTTP/1.1 204 No Content