Rejestracja agenta klienta
Agent Enrollment łączy jednego lub wielu lokalnych CloudPrint Agents z właściwym kontem klienta bez rejestracji i logowania klienta do CloudPrint.
Każdy Enrollment twórz idempotentnie
Pierwsze utworzenie konta zwraca jeden hosted agent_onboarding_url z jednorazowym tokenem. Kolejny komputer możesz dodać przez POST /partner-api/v1/accounts/{relationshipId}/agent-enrollments z wymaganym Idempotency-Key. Dokładne ponowienie zwraca ten sam Enrollment ID, termin ważności i URL. Przed pierwszym żądaniem zapisz klucz, state, nazwę, callback i opcjonalne replaces_enrollment_id; przy ponowieniu zmienia się tylko assertion aplikacji. Aby zastąpić znany, niewykorzystany Enrollment, przekaż replaces_enrollment_id.
Śledź dokładnie ten Enrollment
Zapisz zwrócony enrollment_id i sprawdzaj GET /partner-api/v1/accounts/{relationshipId}/agent-enrollments/{enrollmentId}. Kontynuuj przy pending; po ready zapisz zwrócony agent_id. Zakończ przy expired, cancelled lub failed. Dzięki temu Agent podłączony wcześniej nie zostanie pomylony z komputerem używającym nowego linku.
Wyświetlaj i odwołuj Enrollments
GET /partner-api/v1/accounts/{relationshipId}/agent-enrollments zwraca pending, claimed, expired i revoked records bez tajnych kodów. Odwołaj nieużyty kod przez DELETE /partner-api/v1/accounts/{relationshipId}/agent-enrollments/{enrollmentId}. Ponowne revoke jest bezpieczne.
Wyświetlaj i odwołuj Agents
Pokaż podłączone komputery przez GET /partner-api/v1/accounts/{relationshipId}/agents. Utracony, uszkodzony lub wymieniony komputer odwołaj przez DELETE /partner-api/v1/accounts/{relationshipId}/agents/{agentId}, a dla nowego utwórz Enrollment. Drukarki odwołanego Agent przechodzą offline.
Odzyskaj utraconą odpowiedź Enrollment
Powtórz dokładne żądanie z nowym jednorazowym assertion i tym samym Enrollment Idempotency-Key. CloudPrint zwraca pierwotny secret w okresie idempotency. Inne body lub route z tym samym kluczem zwraca 409 partner.idempotency.conflict; po niepewnej odpowiedzi nie twórz nowego klucza.
Użyj hosted onboarding bez konfiguracji Agent API
Otwórz pełny agent_onboarding_url bez zmian, wraz z fragmentem #token; nie analizuj, nie przebudowuj, nie proxy'uj ani nie loguj go. CloudPrint sam zarządza Agent API i fallback. Publiczny katalog instalatorów jest dostępny przez GET /agent-download-api/v1/releases, a plik przez GET /agent-download-api/v1/installers/{filename}. Po callback zweryfikuj state. result=ready potwierdza pierwszy uwierzytelniony heartbeat Agent, a nie dostępność drukarki. Odśwież zarządzane konto, Agents i listę drukarek; włącz drukowanie dopiero przy status=active, online_agent_count > 0 i online_printer_count > 0.
Zbierz dane dla wsparcia
Przechowuj identyfikator klienta, relationship_id, installation_id, Enrollment ID, Agent ID, wersję, last-seen i powiązane X-Request-Id. Wsparcie powinno rozróżnić lifecycle konta, Enrollment, Agent connectivity, printer discovery i Print API bez proszenia o credentials.
Lista kontrolna przed wdrożeniem
- Korzystaj z wychodzącego połączenia agenta; nie wystawiaj portów drukarki do internetu.
- Zapisuj stabilny identyfikator drukarki, a nie tylko jej nazwę.
- Sprawdzaj format dokumentu, rozmiar strony i orientację przed utworzeniem zadania.
- Jawnie obsługuj status końcowy, ponowienia i ochronę przed podwójnym drukiem.