Opis mechanizmu

Endpoint służy do pobierania gotowego, wyrenderowanego dokumentu w postaci strumienia pliku binarnego, po tym jak zadanie asynchroniczne osiągnęło w kolejce status końcowy „Succeeded”.

• Wersja: v0
• Metoda HTTP: GET
• Format danych: Zależny od wyjściowego pliku (Binary Stream)

Szkielet żądania (Request URI)

Pobranie pliku realizowane jest poprzez dedykowane żądanie typu GET:

GET /api/v0/PrintQueue/{operationId}/result HTTP/1.1
Host: localhost:5000
Accept: */*

Parametry ścieżki (Path Parameters)

• {operationId} (string / GUID): Wymagany. Umieszczany bezpośrednio w ścieżce adresu URL. Jest to unikalny identyfikator powiązany z plikiem wynikowym operacji wydruku (GUID przekazany przez Twój system w payloadzie wejściowym podczas zlecania zadania metodą POST /enqueue).

Pełny cykl życia operacji asynchronicznej (Krok po kroku)

Zrozumienie poniższej ścieżki jest kluczowe dla dewelopera: do odpytywania o status zadania używamy identyfikatora jobId, natomiast do końcowego odebrania pliku binarnego wymagany jest identyfikator operationId.

Krok 1: Zlecenie zadania do kolejki (opis /api/v0/PrintQueue/enqueue)

POST /api/v0/PrintQueue/enqueue HTTP/1.1
Content-Type: application/json

{
  "operationId": "my-report-123",
  "printFormat": "Pdf",
  "report": {
    "source": "SGVsbG8gd29ybGQh",
    "dataFormat": "Bytes"
  },
  "output": {
    "dataFormat": "Bytes"
  }
}

Odpowiedź serwera (HTTP 202 Accepted):

{
  "jobId": "job-12345",
  "operationId": "my-report-123"
}

Krok 2: Sprawdzenie statusu przetwarzania w tle (opis /api/v0/PrintQueue/{jobId}/status)

Odpytujemy system za pomocą otrzymanego parametru jobId:

GET /api/v0/PrintQueue/job-12345/status HTTP/1.1

Odpowiedź serwera (HTTP 200 OK):

{
  "status": "Succeeded"
}

Krok 3: Pobranie gotowego pliku wynikowego

Gdy status zmieni się na „Succeeded”, pobieramy dokument za pomocą opisywanego w tym artykule /api/v0/PrintQueue/{operationId}/result, wskazując w ścieżce jego operationId:

GET /api/v0/PrintQueue/my-report-123/result HTTP/1.1
Accept: */*

Odpowiedź serwera (HTTP 200 OK): Surowy pobierany plik PDF (Binary file download).

Kody odpowiedzi (Responses)

? HTTP 200 OK

Serwer pomyślnie zweryfikował ukończenie zadania i zwraca wygenerowany dokument jako binarny strumień danych przeznaczony do bezpośredniego pobrania (File Download). Nagłówek odpowiedzi: Content-Type jest automatycznie dopasowywany przez silnik do formatu wybranego w parametrze wejściowym printFormat żądania:

• Dla formatu PDF: application/pdf
• Dla formatów Excel (XLSX): application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
• Dla formatów Word (DOCX): application/vnd.openxmlformats-officedocument.wordprocessingml.document

Format odpowiedzi:
Surowy plik binarny (Strumień bajtów dokumentu pdf/xlsx/doc)

? HTTP 404 Not Found

Zwracany w sytuacji, gdy przekazany identyfikator operationId nie istnieje w rejestrze, zadanie powiązane z operacją wciąż się przetwasza (nie osiągnęło jeszcze statusu Succeeded) bądź pierwotna konfiguracja wyjściowa (output) zakładała bezpośredni zapis pliku na serwerze lub chmurze S3 zamiast buforowania w pamięci bazy danych API.

Format odpowiedzi: application/json (string)

Realne Przykłady Implementacji (Odbiór i Zapis Strumienia)

W przypadku poprawnego wywołania (status 200 OK), serwer nie zwraca struktury tekstowej JSON, lecz surową zawartość binarną pliku, którą aplikacja kliencka musi odebrać jako tablicę bajtów i zapisać fizycznie na dysku lokalnym.

1. Przykład w języku Python ( requests )

import requests

operation_id = "f7b6058c-6878-433b-bf72-a0e28f32371a"
url = f"http://localhost:5000/api/v0/PrintQueue/{operation_id}/result"

response = requests.get(url, headers={"Accept": "*/*"})

if response.status_code == 200:
    print(f"Wykryto format pliku z nagłówka Content-Type: {response.headers.get('Content-Type')}")
    
    # Zapis surowego binarnego strumienia bajtów (content) na dysk lokalny klienta
    with open("PobranaEtykieta.pdf", "wb") as file:
        file.write(response.content)
    print("Pomyślnie pobrano i zapisano dokument jako PobranaEtykieta.pdf")
elif response.status_code == 404:
    print("Dokument nie istnieje, wciąż się renderuje lub został zapisany w trybie Path/S3.")

2. Przykład w języku C# ( HttpClient )

using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var operationId = "f7b6058c-6878-433b-bf72-a0e28f32371a";
        var url = $"http://localhost:5000/api/v0/PrintQueue/{operationId}/result";

        using var client = new HttpClient();
        
        try
        {
            var response = await client.GetAsync(url);

            if (response.IsSuccessStatusCode)
            {
                // Odczytujemy odpowiedź jako tablicę bajtów
                byte[] fileBytes = await response.Content.ReadAsByteArrayAsync();
                
                // Asynchroniczny zapis strumienia binarnego na dysk klienta
                await File.WriteAllBytesAsync("PobranaEtykieta.pdf", fileBytes);
                Console.WriteLine("Pomyślnie zapisano plik z kolejki sPrint.");
            }
            else if (response.StatusCode == System.Net.HttpStatusCode.NotFound)
            {
                Console.WriteLine("Błąd 404: Brak raportu w pamięci bazy danych (prawdopodobnie tryb Path/S3 lub w toku).");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Błąd sieciowy podczas komunikacji z API: {ex.Message}");
        }
    }
}