Microsoft Graph のユニバーサル印刷 API を使用して文書をアップロードする

Microsoft Graph のユニバーサル印刷 API を使用して文書を印刷するには、印刷ジョブを作成し、文書をアップロードして、印刷ジョブを開始します。 この記事では、アップロード セッションの作成から文書をアップロードする方法について説明します。

ファイル、またはファイルの一部をアップロードするために、アプリは createUploadSession 応答で受け取った uploadUrl の値に PUT 要求を行います。 どの要求の最大バイト数も 10 MB 未満である限り、ファイル全体をアップロードすることも、ファイルをいくつかのバイト範囲に分割することも可能です。

ファイルのセグメントは、任意の順序で並列にアップロードすることができ、同時要求は最大 4 件まで可能です。 文書のすべてのバイナリ セグメントがアップロードされると、バイナリ ファイルは printDocument にリンクされます。

備考: アプリでファイルが複数のバイト範囲に分割される場合、セグメント サイズを 320 KB の倍数にする必要がある Microsoft Graph SDK を使用している場合を除き、各バイト範囲のサイズを 200 KB の倍数にすることをお勧めします。

ファイルをアップロードする

要求

createUploadSession 応答で受信した uploadUrl 値に、PUT 要求を送信します。

要求ヘッダー

名前	説明
Content-Range	bytes {startByteIndex}-{endByteIndex}‬/{documentSizeInBytes}. 必須です。
コンテンツの長さ	{contentLength} 必ず指定します。

要求本文

要求本文は、文書のバイト数を含むバイナリ BLOB であり、Content-Range ヘッダーの 包括的な バイト範囲として指定されます。

例

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>

ここでは、0 と 72796 はファイル セグメントの開始インデックスと終了インデックスで、4533322 はドキュメントのサイズです。

応答

要求の完了時に、アップロードする必要のあるバイト範囲がまだ存在している場合、サーバーは 202 Accepted で応答します。

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

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

アプリは nextExpectedRanges の値を使用して、次のバイト範囲の開始点を判断できます。 サーバーがまだ受信していないファイルの部分を示す、複数の指定範囲が表示されることがあります。 nextExpectedRanges プロパティは、まだ受信されていないファイルの範囲を示します。アプリによるファイル アップロード方法のパターンを示すものではありません。

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

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

備考

• サーバーが既に受信していたフラグメントをクライアントが送信した場合のエラーでは、サーバーから HTTP 416 Requested Range Not Satisfiable の応答が返されます。 受信されていない範囲のより詳細なリストを取得するために、アップロード ステータスを要求できます。
• PUT の呼び出しを発行するときに、Authorization ヘッダーを含めると、HTTP 401 Unauthorized 応答が発生する可能性があります。 Authorization ヘッダーとベアラー トークンは、アップロード セッションを作成するときにのみ送信する必要があります。 アップロード セッションにデータをアップロードするときに、このファイルを含めないでください。

ファイルのアップロードを完了する

ファイルの最後のバイト範囲が受信されると、サーバーは HTTP 201 Created の応答を返します。 また、応答本文には、関連付けられている 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
}

注: 文書のアップロード完了後、アップロード セッションは削除されます。

アップロード セッションを取得する

アップロード セッションを取得するには、アップロード URL に GET 要求を送信します。

要求

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

応答

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

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

コード例: アップロード セッションの作成と文書のアップロード

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

アップロード セッションを取り消す

アップロード セッションを取り消すには、アップロード URL に DELETE 要求を送信します。 これは、アップロードが中止されるシナリオで使用する必要があります。たとえば、ユーザーが転送をキャンセルした場合などです。

一時ファイルとそれに伴うアップロード セッションは、expirationDateTime が経過した後、自動的にクリーンアップされます。

要求

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

応答

HTTP/1.1 204 No Content