Opis mechanizmu

Endpoint służy do sprawdzania bieżącego stanu przetwarzania zadania wydruku zlecenia asynchronicznego, które zostało umieszczone w kolejce procesora tła (Hangfire).

Z punktu widzenia integracji, wywołanie tej metody pozwala systemowi zewnętrznemu na realizację mechanizmu odpytywania (Polling). Aplikacja kliencka może w pętli weryfikować status operacji i na tej podstawie podjąć decyzję o przejściu do kroku pobierania pliku binarnego za pomocą endpointu GET /api/v0/PrintQueue/{operationId}/result bądź wyświetleniu logu błędów użytkownikowi.

• Wersja: v0
• Metoda HTTP: GET
• Format danych odpowiedzi: application/json

Szkielet żądania (Request URI)

Weryfikacja stanu realizowana jest poprzez proste żądanie typu GET, gdzie identyfikator zadania pobrany z kolejki przekazywany jest bezpośrednio w ścieżce adresu URL:

GET /api/v0/PrintQueue/{jobId}/status HTTP/1.1
Host: localhost:5000
Accept: application/json

Parametry ścieżki (Path Parameters)

• {jobId} (string): Wymagany. Umieszczany bezpośrednio w ścieżce adresu URL. Jest to unikalny identyfikator techniczny zadania w tle nadany i zwrócony przez bramkę API sPrint w ciele odpowiedzi (payloadzie) podczas pierwotnego wywołania metody POST /enqueue.

Struktura odpowiedzi (Response Body)

Model zwrotny JSON udostępnia podstawowe parametry kontrolne oraz tablicę diagnostyczną:

{
  "status": "string",
  "operationId": "string",
  "errors": []
}

• status (string): Definiuje obecny krok procesora Hangfire w odniesieniu do zadania. Przyjmuje jedną z wartości słownikowych:
  • "Enqueued" – Zadanie oczekuje w bazie danych kolejki na zwolnienie wątku roboczego.
  • "Processing" – Silnik sPrint API aktualnie pobiera dane z bazy i renderuje dokument.
  • "Succeeded" – Operacja zakończona sukcesem. Dokument został zapisany na dysku/S3 lub oczekuje na pobranie w pamięci bajtowej.
  • "Failed" – Przetwarzanie zostało przerwane z powodu krytycznego błędu.
• operationId (string / GUID): Identyfikator biznesowy operacji powiązany z plikiem (wskazany pierwotnie przez system integrujący).
• errors (array of strings): Lista komunikatów diagnostycznych i wyjątków systemowych, uzupełniana wyłącznie wtedy, gdy pole status przyjmuje wartość "Failed".

Kody odpowiedzi (Responses)

? HTTP 200 OK

Zapytanie zostało przetworzone pomyślnie. Serwer odnalazł zadanie w rejestrze i zwraca jego pełny profil statusowy.

Format odpowiedzi: application/json

{
  "status": "Succeeded",
  "operationId": "my-report-123",
  "errors": []
}

? HTTP 404 Not Found

Zwracany w sytuacji, gdy przekazany w ścieżce identyfikator techniczny zadania ({jobId}) nie istnieje w rejestrach kolejki procesora Hangfire (np. na skutek podania błędnego numeru lub wyczyszczenia historii zadań).

Format odpowiedzi: application/json (string)

Realne Przykłady Implementacji (Sprawdzenie statusu)

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

import requests

job_id = "14"
url = f"http://localhost:5000/api/v0/PrintQueue/{job_id}/status"

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

if response.status_code == 200:
    data = response.json()
    status_zadania = data.get("status")
    operation_id = data.get("operationId")
    
    print(f"Zadanie {job_id} jest obecnie w stanie: {status_zadania}")
    
    if status_zadania == "Succeeded":
        print(f"Można pobrać plik używając Operation ID: {operation_id}")
    elif status_zadania == "Failed":
        print(f"Błędy silnika sPrint: {data.get('errors')}")
elif response.status_code == 404:
    print("Nie znaleziono takiego Job ID w bazie kolejki serwera.")

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

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

class Program
{
    public class StatusResponse
    {
        public string Status { get; set; }
        public string OperationId { get; set; }
        public string[] Errors { get; set; }
    }

    static async Task Main(string[] args)
    {
        var jobId = "14";
        var url = $"http://localhost:5000/api/v0/PrintQueue/{jobId}/status";

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

            if (response.IsSuccessStatusCode)
            {
                var data = await response.Content.ReadFromJsonAsync<StatusResponse>();
                Console.WriteLine($"Status zadania: {data?.Status}");
                
                if (data?.Status == "Failed" && data.Errors != null)
                {
                    Console.WriteLine($"Wykryte błędy: {string.Join(", ", data.Errors)}");
                }
            }
            else if (response.StatusCode == System.Net.HttpStatusCode.NotFound)
            {
                Console.WriteLine("Błąd 404: Zadanie o podanym Job ID nie istnieje w usłudze Hangfire.");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Wyjątek sieciowy: {ex.Message}");
        }
    }
}