Usługa Google Cloud Print od 31 grudnia 2020 r. nie jest już obsługiwana. Jeśli potrzebujesz pomocy przy migracji, zapoznaj się z tym artykułem.

Ta strona została przetłumaczona przez Cloud Translation API.

Priveve

Privet to interfejs Cloud Device Local Discovery API używany przez usługi w chmurze. Ten dokument składa się z takich sekcji:

Wprowadzenie: wprowadzenie do Privet
Discovery: lokalne mechanizmy odkrywania.
Ogłoszenia: ogłoszenia dotyczące wydarzeń lokalnych.
API: interfejsy API Privet dla ogólnych urządzeń w chmurze.
Printer API: interfejsy Privet API używane przez drukarki
Dodatek: diagramy dodatkowe

1. Wstęp

Urządzenia połączone z chmurą mają wiele zalet. Mogą korzystać z usług konwersji online, obsługiwać kolejki zadań w trybie offline i mieć dostęp z dowolnego miejsca na świecie. Ponieważ jednak użytkownik korzysta z wielu urządzeń w chmurze, musimy znaleźć metodę znajdowania najbliższego urządzenia na podstawie lokalizacji. Celem protokołu Privet jest powiązanie elastyczności urządzeń w chmurze z odpowiednim lokalnym mechanizmem wykrywania, tak aby urządzenia mogły być łatwo wykrywane w nowych środowiskach.

Jego celem jest:

zapewnij możliwość lokalnego wykrywania urządzeń w chmurze
Rejestrowanie urządzeń w chmurze za pomocą usługi w chmurze
powiązanie zarejestrowanych urządzeń z ich reprezentacją w chmurze,
włącz funkcje offline
uproszczona implementacja, dzięki czemu małe urządzenia mogą z niej korzystać

Protokół Privet składa się z 2 głównych części: odkrywania i interfejsu API. Funkcja wykrywania służy do znajdowania urządzenia w sieci lokalnej, a interfejs API służy do pobierania informacji o urządzeniu i wykonywania pewnych działań. W tym dokumencie urządzenie odnosi się do urządzenia połączonego z chmurą, które implementuje protokół Privet.

2. Odkrywanie

Discovery to protokół oparty na zeroconf (mDNS + DNS-SD). Urządzenie MUSI implementować lokalny adres IPv4. Urządzenie MUSI być zgodne ze specyfikacją mDNS i DNS-SD.

http://www.rfc-editor.org/rfc/rfc3927.txt (IPv4 Link-local)
http://www.rfc-editor.org/rfc/rfc4862.txt (IPv6 Link-local)
http://www.rfc-editor.org/rfc/rfc6762.txt (mDNS)
http://www.rfc-editor.org/rfc/rfc6763.txt (DNS-SD)

Urządzenie MUSISZ rozwiązać konflikt nazw zgodnie z powyższymi specyfikacjami.

2.1. Typ usługi

Wykrywanie usług DNS używa tego formatu w przypadku typów usług: _applicationprotocol._transportprotocol. W przypadku protokołu Privet typ usługi DNS-SD powinien wynosić: _privet._tcp.

Urządzenie może też zaimplementować inne typy usług. Zaleca się używanie tej samej nazwy instancji usługi we wszystkich typach usług zaimplementowanych przez urządzenie. Na przykład: drukarka może implementować usługi „Drukarka XYZ._privet._tcp" "Drukarka XYZ._printer._tcp"”. Uprości to konfigurację użytkownika. Klienty Privet będą jednak używać tylko operatora "_privet._tcp".

Oprócz głównego typu usługi urządzenie MUSISZ reklamować rekordy PTR dla odpowiednich podtypów (patrz specyfikacja DNS-SD: "7.1. Selektywne wyliczenie instancji (podtypy)&quot). Format powinien być taki: _<subtype>._sub._privet._tcp

Obecnie jedynym podtypem urządzenia jest drukarka. Wszystkie drukarki muszą więc reklamować 2 rekordy PTR:

_privet._tcp.local.
_drukarka._sub._privet._tcp.local.

2.2. Rekord TXT

DNS Service Discovery definiuje pola pozwalające dodać opcjonalne informacje o usłudze w rekordach TXT. Rekord TXT składa się z par klucz/wartość. Każda para klucz-wartość zaczyna się od długości bajta, a następnie do 255 bajtów tekstu. Klucz to tekst przed pierwszym znakiem „=”, a wartość po tekście „=” do końca. Specyfikacja nie pozwala na podawanie w wartości żadnej wartości. W takim przypadku po znaku „=” nie może znajdować się znak „=”, LUB tekst. (Zobacz specyfikację DNS-SD: &&tt;6.1. Ogólne reguły formatowania rekordów DNS typu TXT dla formatu rekordu DNS typu TXT oraz &6.2. Rozmiar zalecanego rekordu TXT DNS-SD).

Privet wymaga, aby urządzenie wysyłało takie pary klucz/wartość w rekordzie TXT. W ciągach klucz/wartość nie jest rozróżniana wielkość liter, np. „"CS=online" "cs=Online" są takie same. Informacje w rekordzie TXT MUSZĄ być takie same jak te dostępne za pomocą interfejsu /info API (patrz punkt 4.1. API).

Zalecamy, aby rozmiar rekordu TXT nie przekraczał 512 bajtów.

2.2.1. txters

Wersja struktury TXT. txtvers MUSI być pierwszym rekordem struktury TXT. Obecnie jedyną obsługiwaną wersją jest 1.

txtvers=1

2.2.2

Wyświetla nazwę urządzenia zrozumiałą dla użytkowników. Przykład:

ty=Google Cloud Ready Printer Model XYZ

2.2.3. Notatka (opcjonalnie)

Wyświetla nazwę urządzenia zrozumiałą dla użytkowników. Przykład:

note=1st floor lobby printer

Uwaga: to klucz opcjonalny i może zostać pominięty. Jeśli tak jest, użytkownik powinien powinien mieć możliwość zmiany tej wartości. Podczas rejestrowania urządzenia MUSI być używany ten sam opis.

2.2.4. URL

Adres URL serwera, z którym jest połączone to urządzenie (w tym protokół). Przykład:

url=https://www.google.com/cloudprint

2.2.5. Typ

Rozdzielana przecinkami lista podtypów urządzeń obsługiwanych przez to urządzenie. Format to: "type=_subtype1,_subtype2". Obecnie jedynym podtypem urządzenia jest drukarka.

type=printer

Każdy z podtypów powinien być reklamowany za pomocą odpowiedniego rekordu PTR. Z każdym obsługiwanym podtypem usługi musi istnieć jeden powiązany element. Nazwa podtypu usługi (<subtype>._sub._privet._tcp) powinna być równa typowi urządzenia.

2.2.6. Identyfikator

Identyfikator urządzenia. Jeśli urządzenie nie zostało jeszcze zarejestrowane, ten klucz powinien być obecny, ale wartość powinna być pusta. Przykład:

  id=11111111-2222-3333-4444-555555555555
  id=

2.2.7 cs

Wskazuje bieżący stan połączenia urządzenia. W tej specyfikacji określono cztery możliwe wartości.

"online" oznacza, że urządzenie jest obecnie połączone z chmurą.
"offline" oznacza, że urządzenie jest dostępne w sieci lokalnej, ale nie może nawiązać połączenia z serwerem.
"connecting" oznacza, że urządzenie rozpoczyna sekwencję uruchamiania i nie jest jeszcze w pełni online.
"not-configured" oznacza, że dostęp do internetu na urządzeniu nie został jeszcze skonfigurowany. Ta wartość nie jest obecnie używana, ale może być przydatna w przyszłych wersjach specyfikacji.

Przykład:

cs=online
cs=offline
cs=łączę

Jeśli urządzenie zostało zarejestrowane w chmurze, podczas uruchamiania powinno sprawdzić połączenie z serwerem, aby wykryć jego stan (na przykład wywołać interfejs Cloud API w celu uzyskania ustawień urządzenia). Aby zgłosić tę wartość, urządzenie może używać stanu połączenia kanału powiadomień (np. XMPP). Niezarejestrowane urządzenia podczas uruchamiania mogą pingować domenę, aby wykryć stan połączenia (na przykład www.google.com w przypadku urządzeń drukujących w chmurze).

3. Ogłoszenia

Przy uruchamianiu, wyłączaniu lub zmianie stanu urządzenia MUSZĄ wykonać krok ogłoszenia zgodnie ze specyfikacją mDNS. Wymagane jest wysłanie co najmniej 2-sekundowego ogłoszenia w odstępach co najmniej 1 sekundę.

3.1. Startup

Po uruchomieniu urządzenia MUSI wyszukiwać i ogłoszać kroki zgodnie ze specyfikacją mDNS. W takim przypadku należy wysłać rekordy SRV, PTR i TXT. Zalecamy zgrupowanie wszystkich rekordów w jednej odpowiedzi DNS, jeśli to możliwe. W przeciwnym razie zalecana jest taka kolejność: rekordy SRV, PTR, TXT.

3.2. Wyłączona

Po wyłączeniu urządzenia należy o tym powiadomić wszystkie zainteresowane osoby, wysyłając pakiet „TTL” (z TTL=0 zgodnie z dokumentacją mDNS).

3.3. Zaktualizuj

W przypadku zmiany informacji opisanych w rekordzie TXT urządzenie MUSI przesłać ogłoszenie o aktualizacji. W takim przypadku wystarczy wysłać tylko nowy rekord TXT. Na przykład po zarejestrowaniu urządzenia MUSI zostać wysłane powiadomienie o aktualizacji wraz z nowym identyfikatorem urządzenia.

4. API

Po wykryciu urządzenia obsługującego chmurę komunikację z nim jest włączona bezpośrednio w sieci lokalnej. Wszystkie interfejsy API są oparte na protokole HTTP 1.1. Formaty danych są oparte na formacie JSON. Żądania API mogą być żądaniami GET lub POST.

Każde żądanie musi zawierać prawidłowy nagłówek "X-Privet-Token". Żądanie TYLKO może zawierać pusty nagłówek "X-Privet-Token" W przypadku braku nagłówka "X-Privet-Token" urządzenie MUSI odpowiadać w odpowiedzi tego błędu HTTP 400:

HTTP/1.1 400 Missing X-Privet-Token header.

Jeśli nagłówek "X-Privet-Token" jest pusty lub nieprawidłowy, urządzenie MUSI odpowiadać, podając w polu „"invalid X-Privet-Token token" (nieprawidłowy_x_privet_token – szczegółowe informacje znajdziesz w sekcji Błędy). Jedynym wyjątkiem jest interfejs /info API. Więcej informacji na ten temat oraz o tym, jak wygenerować tokeny, znajdziesz w dodatku A: XSSI oraz XSRF i ataki.

Jeśli żądany interfejs API nie istnieje lub nie jest obsługiwany, urządzenie MUSI zwrócić błąd HTTP 404.

4.1. Dostępność interfejsu API

Przed ujawnieniem jakiegokolwiek interfejsu API (w tym interfejsu /info API) urządzenie MUSI skontaktować się z serwerem, aby sprawdzić ustawienia lokalne. Ustawienia lokalne MUSZĄ zachować między restartami. Jeśli serwer jest niedostępny, użyj ostatnich znanych ustawień lokalnych. Jeśli urządzenie nie zostało jeszcze zarejestrowane, powinny zostać zastosowane ustawienia domyślne.

Urządzenia w Cloud Print MUSZĄ wykonać poniższe czynności, aby rejestrować, odbierać i aktualizować ustawienia lokalne.

4.1.1 Rejestracja

Podczas rejestracji urządzenia MUSI ono określać parametr "local_settings" w ten sposób:

{
       "current": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": true,
                "printer/conversion_printing_enabled": true,
                "xmpp_timeout_value": 300
        }
}

Możesz wybrać te ustawienia:

Nazwa wartości	Typ wartości	Opis
wykrywanie_lokalne	wartość logiczna	Wskazuje, czy funkcja wykrywania lokalnego jest dozwolona. Jeśli "false" wszystkie lokalne interfejsy API (w tym /info) i wykrywanie DNS-SD muszą być wyłączone. Domyślnie nowo zarejestrowane urządzenia powinny przekazywać parametr "true".
access_token_enabled	boolean (opcjonalnie)	Wskazuje, czy interfejs /accesstoken API powinien być dostępny w sieci lokalnej. Wartość domyślna to "true".
drukarka/włączony_druk_lokalny	boolean (opcjonalnie)	Określa, czy lokalne funkcje drukowania (/printer/createjob, /printer/submitdoc, /printer/jobstate) powinny być dostępne w sieci lokalnej. Wartość domyślna to "true".
drukarka/drukowanie_konwersji_włączona	boolean (opcjonalnie)	Wskazuje, czy drukowanie lokalne może wysyłać zadanie do serwera konwersji. Ma to sens tylko wtedy, gdy włączone jest drukowanie lokalne.
xmpp_timeout_value	int (opcjonalnie)	Wskazuje liczbę sekund między pingami kanału XMPP. Domyślnie MUSI wynosić 300 (5 minut) lub więcej.

Ważne: brak wartości opcjonalnej oznacza, że urządzenie nie obsługuje żadnej funkcji.

4.1.2 Startup

Po uruchomieniu urządzenia powinno ono kontaktować się z serwerem, aby sprawdzić, które interfejsy API są dostępne w sieci lokalnej. W przypadku drukarek połączonych z Cloud Print powinny one wywołać:

/cloudprint/printer?printerid=<printer_id>

lub

/cloudprint/list

/Więcej informacji o pliku /Więcej informacji o drukarce to /Więcej informacji o parametrze //+//lista, ale obie działają.

Ten interfejs API zwraca aktualne parametry urządzenia, w tym ustawienia lokalnego interfejsu API. Odpowiedź z serwera będzie miała ten format:

"local_settings": {
        "current": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": true,
                "printer/conversion_printing_enabled": true,
                "xmpp_timeout_value": 300
         },
         "pending": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": false,
                "printer/conversion_printing_enabled": false,
                "xmpp_timeout_value": 500
         }
}

"current" obiekt wskazuje ustawienia, które są w danej chwili stosowane.

"pending" obiekt określa ustawienia, które mają zostać zastosowane na urządzeniu (może nie być żadnego obiektu).

Gdy urządzenie zobaczy ustawienia &oczekujące, MUSI zmienić jego stan (patrz poniżej).

4.1.3 Zaktualizuj

Jeśli konieczna jest aktualizacja ustawień, na urządzenie zostanie wysłane powiadomienie XMPP. Powiadomienie będzie mieć następujący format:

<device_id>/update_settings

Po otrzymaniu takiego powiadomienia urządzenie MUSI wysyłać zapytania do serwera, aby uzyskać najnowsze ustawienia. Urządzenia z Cloud Print MUSZĄ używać:

/cloudprint/printer?printerid=<printer_id>

Gdy urządzenie zobaczy sekcję &pending" w wyniku działania //+//printer API (przy uruchamianiu lub w wyniku powiadomienia), MUSI zaktualizować stan wewnętrzny, aby zapamiętać nowe ustawienia. Wymagane jest wywołanie interfejsu API serwera, aby potwierdzić nowe ustawienia. W przypadku drukarek Drukarki MUSZĄ wywoływać interfejs //+//update API i używać parametru "local_settings" podczas rejestracji.

Przy ponownym nawiązywaniu połączenia z kanałem XMPP urządzenie musi /wywołać interfejs //+//printer API, aby sprawdzić, czy ustawienia lokalne zostały zmienione od ostatniego czasu.

4.1.3.1 Ustawienia lokalne oczekujące

"local_settings" parametr, którego urządzenie używa do wywoływania interfejsu API serwera, MUSI NIE zawierać sekcji „"pending"”.

4.1.3.2 Obecne ustawienia lokalne

Tylko urządzenie może zmienić sekcję "current" w "local_settings". Wszystkie inne osoby zmienią sekcję „oczekujące” i zaczekają, aż zmiany zostaną rozpowszechnione w sekcji „"current"”.

4.1.4 Offline

Jeśli nie można skontaktować się z serwerem podczas uruchamiania, po otrzymaniu powiadomienia urządzenie MUSI korzystać z ostatnich znanych ustawień lokalnych.

4.1,5 Usuwanie urządzenia z usługi

Jeśli urządzenie zostało usunięte z usługi (na przykład GCP), zostanie do niego wysłane powiadomienie XMPP. Powiadomienie ma taki format:

<device_id>/delete

Po otrzymaniu takiego powiadomienia urządzenie MUSI należeć do serwera, aby sprawdzić jego stan. Urządzenia w Cloud Print MUSZĄ używać:

/cloudprint/printer?printerid=<printer_id>

Urządzenie MUSI otrzymać pomyślną odpowiedź HTTP z opisem powodzenia=false i brak opisu urządzenia/drukarki. Oznacza to, że urządzenie zostało usunięte z serwera, a urządzenie MUSI usunąć dane logowania i przejść do trybu domyślnego.

Za każdym razem, gdy urządzenie otrzyma odpowiedź wskazującą, że zostało usunięte w wyniku wdrożenia interfejsu //+//printer API (uruchamiania, powiadomienia o ustawieniach aktualizacji, codziennego pingu), MUSI usunąć dane logowania i przejść do trybu domyślnego.

4.2. /privet/info API

Interfejs API informacji jest OBOWIĄZKOWE i MUSI być wdrażany przez każde urządzenie. Jest to żądanie GET HTTP dla &"/privet/info" url: GET /privet/info HTTP/1.1

Interfejs Info API zwraca podstawowe informacje o urządzeniu i funkcjach, które obsługuje. Ten interfejs API MUSI nigdy nie zmieniać stanu urządzenia ani nie wykonywać żadnych działań, ponieważ jest narażony na ataki XSRF. Jest to jedyny interfejs API, który może zawierać pusty nagłówek "X-Privet-Token". Klient powinien wywołać interfejs /privet/info API z nagłówkiem "X-Privet-Token" tokenem X-Privet-Token: &""

Interfejs API informacji MUSI zwracać dane zgodne z danymi dostępnymi w rekordzie TXT podczas wykrywania.

4.2.1 Wprowadź tekst

/privet/info API nie ma parametrów wejściowych.

4.2.2 Zwróć

/privet/info API zwraca podstawowe informacje o urządzeniu i obsługiwanych funkcjach.

Kolumna TXT oznacza odpowiednie pole w rekordzie TXT DNS-SD.

Nazwa wartości	Typ wartości	Opis	TXT;
Wersja	tekst	Najwyższa obsługiwana wersja interfejsu API (obecnie 1.0)
name	tekst	Czytelna nazwa człowieka urządzenia.	ty
opis	tekst	(Opcjonalnie) Opis urządzenia. MOŻNA modyfikować go przez użytkownika.	notatka
url (adres URL)	tekst	Adres URL serwera, z którym komunikuje się to urządzenie. Adres URL MUSI zawierać specyfikację protokołu, na przykład: https://www.google.com/signin.	url (adres URL)
Typ	lista ciągów tekstowych	Lista obsługiwanych typów urządzeń.	Typ
id	tekst	Identyfikator urządzenia jest pusty, jeśli urządzenie nie zostało jeszcze zarejestrowane.	id
device_state (stan urządzenia)	tekst	Stan urządzenia. Nieaktywny oznacza, że urządzenie jest gotowe Przetwarzanie oznacza, że urządzenie jest teraz zajęte, a przez pewien czas funkcje mogą być ograniczone. Zatrzymane oznacza, że urządzenie nie działa i wymagana jest interwencja użytkownika.
connection_state (stan połączenia)	tekst	Stan połączenia z serwerem (base_url) online – dostępne połączenie offline – brak połączenia łączenie – wykonywanie czynności uruchamiania nieskonfigurowane – połączenie nie zostało jeszcze skonfigurowane Zarejestrowane urządzenie może raportować stan połączenia na podstawie stanu kanału powiadomień (np. stanu połączenia XMPP).	cs
producent	tekst	Nazwa producenta urządzenia
model	tekst	Model urządzenia.
numer seryjny	tekst	Unikalny identyfikator urządzenia. W tej specyfikacji MUSI to być identyfikator UUID. (Specyfikacja GCP 1.1) (opcjonalna) Zdecydowanie zalecamy używanie tego samego numeru seryjnego w każdym miejscu, aby różni klienci mogli zidentyfikować to samo urządzenie. Na przykład drukarki stosujące protokół IPP mogą używać identyfikatora numeru seryjnego w polu "printer-device-id".
oprogramowanie	tekst	Wersja oprogramowania urządzenia
czas działania	int,	Liczba sekund od uruchomienia urządzenia.
konfiguracja_url	tekst	(Opcjonalnie) Adres URL strony (w tym protokół) z instrukcjami konfiguracji
adres_pomocy	tekst	(Opcjonalnie) Adres URL strony (w tym protokół) z obsługą, najczęstsze pytania
update_url,	tekst	(Opcjonalnie) Adres URL strony (w tym protokół) z instrukcjami aktualizacji oprogramowania
Token-Xveveve	tekst	Wartość nagłówka X-Privet-Token, który musi być przekazany do wszystkich interfejsów API, aby zapobiec atakom XSSI i XSRF. Więcej informacji znajdziesz w sekcji 6.1.
api	opis interfejsów API	Lista obsługiwanych interfejsów API (opisanych poniżej)
semantyczny_stan	JSON	(Opcjonalnie) Stan semantyczny urządzenia w formacie CloudDeviceState.

api – lista JSON zawierająca interfejsy API dostępne w sieci lokalnej. Pamiętaj, że nie wszystkie interfejsy API mogą być dostępne jednocześnie w sieci lokalnej. Na przykład nowo połączone urządzenie może obsługiwać tylko interfejs /register api:

"api": [
        "/privet/register",
]

Po zakończeniu rejestracji urządzenie powinno zatrzymać obsługę interfejsu /register API. Urządzenie powinno też kontaktować się z usługą, aby określić, które interfejsy API mogą być widoczne w sieci lokalnej. Przykład:

"api": [
        "/privet/accesstoken",
        "/privet/capabilities",
        "/privet/printer/submitdoc",
]

Obecnie dostępne są te interfejsy API:

/privet/register – interfejs API do rejestracji urządzeń w sieci lokalnej. Więcej informacji znajdziesz na stronie /privet/register API. Interfejs API MUSI być ukryty po zarejestrowaniu urządzenia w chmurze.
/privet/accesstoken – interfejs API, który umożliwia żądanie tokena dostępu z urządzenia (szczegóły znajdziesz na stronie /privet/accesstoken API).
/privet/capcaps – interfejs API do pobierania funkcji urządzenia (szczegóły znajdziesz w opisie /privet/capabilities API).
/privet/printer/* – interfejs API dla konkretnego typu urządzenia i drukarki, aby dowiedzieć się więcej, zapoznaj się z interfejsami API dotyczącymi drukarek.

Oto przykład odpowiedzi /privet/info. (Zwróć uwagę na brak interfejsu /privet/register API, ponieważ jest to już zarejestrowane urządzenie):

4.2.3 Błędy

Atrybut /privet/info API powinien zwrócić błąd tylko wtedy, gdy brakuje nagłówka X-Privet-Token. Musi MUSZ być błędem HTTP 400:

HTTP/1.1 400 Missing X-Privet-Token header.

4.3. /privet/register API

/privet/register API jest opcjonalny. Jest to żądanie HTTP POST. /privet/register API MUSI sprawdzać prawidłowy nagłówek X-Privet-Token. Urządzenie MUSI wdrożyć ten interfejs API pod adresem &"/privet/register" url:

POST /privet/register?action=start&user=user@domain.com HTTP/1.1
POST /privet/register?action=complete&user=user@domain.com HTTP/1.1

Urządzenie powinno udostępniać interfejs /privet/register API TYLKO wtedy, gdy zezwala na anonimowe rejestrowanie. Przykład:

Gdy urządzenie jest włączone (lub po kliknięciu specjalnego przycisku na urządzeniu) i nie zostało jeszcze zarejestrowane, powinno być widoczne /privet/register API, które umożliwia użytkownikowi dostęp do sieci lokalnej.
Po zakończeniu rejestracji urządzenie powinno przestać udostępniać interfejs /privet/register API, aby inny użytkownik w sieci lokalnej nie mógł go odzyskać.
Niektóre urządzenia mogą rejestrować urządzenia w różny sposób i nie powinny w ogóle udostępniać interfejsu /privet/register API (na przykład oprogramowania sprzęgającego Chrome Cloud Print).

Proces rejestracji składa się z 3 kroków (zobacz anonimową rejestrację w Cloud Print).

Rozpocznij anonimowy proces rejestracji.
Klient inicjuje ten proces, wywołując interfejs /privet/register API. Urządzenie może zaczekać na potwierdzenie użytkownika.
Pobierz token roszczenia.

Klient przeprowadza ankietę, aby sprawdzić, czy urządzenie jest gotowe do kontynuowania. Gdy urządzenie będzie gotowe, wyśle żądanie do serwera w celu pobrania tokena rejestracji i adresu URL rejestracji. Otrzymany token i adres URL powinny zwrócić klientowi. Jeśli w tym kroku urządzenie otrzyma kolejne wywołanie w celu zainicjowania rejestracji, powinno ono:

Jeśli to ten sam użytkownik, który rozpoczął rejestrację, usuń wszystkie wcześniejsze dane (jeśli je masz) i rozpocznij nowy proces rejestracji.
Jeśli to inny użytkownik, wybierz błąd device_busy i wróć do 30-sekundowego limitu czasu.

Dokończ proces rejestracji.

Gdy klient odbierze urządzenie, powinien powiadomić je o możliwości ukończenia rejestracji. Po zakończeniu rejestracji urządzenie powinno wysłać powiadomienie o aktualizacji wraz z nowo pozyskanym identyfikatorem urządzenia.

Uwaga: podczas przetwarzania wywołania /privet/register interfejsu API żadne inne wywołania interfejsu /privet/register nie są przetwarzane jednocześnie. Urządzenie MUSI zwrócić błąd device_busy i 30 sekund oczekiwania.

Zdecydowanie zalecamy potwierdzenie rejestracji na urządzeniu. Po zaimplementowaniu urządzenie MUSI zaczekać na potwierdzenie użytkownika po otrzymaniu wywołania /privet/register?action=start API. Klient wywoła metodę /privet/register?action=getClaimToken API, aby sprawdzić, czy potwierdzenie użytkownika się zakończyło i jest dostępny token rezerwacji. Jeśli użytkownik anuluje rejestrację na urządzeniu (np. naciśnie przycisk Anuluj), błąd użytkownik_cancel MUSI być zwrócony. Jeśli użytkownik nie potwierdził rejestracji w określonym przedziale czasu, MUSI zostać zwrócony błąd potwierdzenia_czasu. Więcej informacji znajdziesz w sekcji Ustawienia domyślne.

4.3.1 Wprowadź tekst

/privet/register API zawiera te parametry wejściowe:

Nazwa	Wartość
działanie	Mogą to być: start – aby rozpocząć proces rejestracji; getOdbierzToken – pobierz token roszczenia dla urządzenia; anuluj – aby anulować proces rejestracji; ukończono – aby dokończyć proces rejestracji.
użytkownik	Adres e-mail użytkownika, który zgłosisz prawa do tego urządzenia.

Urządzenie MUSI sprawdzić, czy adres e-mail ze wszystkich działań (start, getClaimToken, anulowanie, ukończenie) jest zgodny.

4.3.2 Zwróć

/privet/register API zwraca te dane:

Nazwa wartości	Typ wartości	Opis
działanie	tekst	Takie samo działanie jak w parametrze wejściowym.
użytkownik	ciąg znaków (opcjonalnie)	Ten sam użytkownik co w parametrze wejściowym (może nie być podany, jeśli został pominięty).
token	ciąg znaków (opcjonalnie)	Token rejestracji (wymagany w przypadku "getClaimToken" odpowiedzi, pominięty w przypadku "start", "complete", "cancel").
roszczenie_url	ciąg znaków (opcjonalnie)	URL rejestracji (wymagany w przypadku "getClaimToken" odpowiedzi, pominięty w przypadku "start", "complete", "cancel"). W przypadku drukarek Cloud musi to być parametr "complete_welcome_url" odebrane z serwera.
Auto_claim_url	ciąg znaków (opcjonalnie)	URL rejestracji (wymagany w przypadku "getClaimToken" odpowiedzi, pominięty w przypadku "start", "complete", "cancel"). W przypadku drukarek Cloud musi to być parametr "Automatic_zapro_url" wysłany z serwera.
identyfikator_urządzenia	ciąg znaków (opcjonalnie)	Nowy identyfikator urządzenia (postępowany w przypadku &&tt;start" odpowiedzi, wymagany w przypadku "complete").

Urządzenie musi mu zwracać identyfikator w odpowiedzi /privet/info API TYLKO po zakończeniu rejestracji.

Przykład 1:

{
        "action": "start",
        "user": "user@domain.com",
}

Przykład 2:

{
        "action": "getClaimToken",
        "user": "user@domain.com",
        "token": "AAA111222333444555666777",
        "claim_url": "https://domain.com/SoMeUrL",
}

Przykład 3:

{
        "action": "complete",
        "user": "user@domain.com",
        "device_id": "11111111-2222-3333-4444-555555555555",
}

4.3.3 Błędy

/privet/register API może zwrócić ten błąd (szczegóły znajdziesz w sekcji Błędy):

Błąd	Opis
device_zajęty,	Urządzenie jest zajęte i nie może wykonać działania. Spróbuj ponownie po upływie limitu czasu.
pending_user_action (oczekujące_działanie)	W odpowiedzi na błąd „"getClaimToken&quot” ten błąd oznacza, że urządzenie nadal oczekuje na potwierdzenie, a żądanie "getClaimToken" należy spróbować ponownie wykonać żądanie po upływie limitu czasu.
user_cancel	Użytkownik anulował proces rejestracji na urządzeniu.
potwierdzenia_czasu	Przekroczono limit czasu potwierdzenia przez użytkownika.
nieprawidłowe_działanie	Wywołano nieprawidłowe działanie. Jeśli na przykład klient wywołał action=complete przed wywołaniem action=start i action=getClaimToken.
nieprawidłowe_parametry	W żądaniu określono nieprawidłowe parametry. Nieznane parametry należy bezpiecznie zignorować, aby zachować zgodność w przyszłości. Na przykład ustaw ten zwrot, jeśli klient ma nazwę action=unknown lub user=.
device_config_error (błąd urządzenia)	Data lub godzina (lub inne ustawienia) są nieprawidłowe po stronie urządzenia. Użytkownik musi przejść do wewnętrznej strony urządzenia i skonfigurować ustawienia urządzenia.
offline	Urządzenie jest obecnie offline i nie może połączyć się z serwerem.
serwer_błąd	Podczas serwera wystąpił błąd serwera.
nieprawidłowy_token_privet	Token X-Privet-Token jest nieprawidłowy lub pusty w żądaniu.

Po zakończeniu rejestracji urządzenie MUSI przestać udostępniać interfejs API /privet/register. Jeśli urządzenie nie ujawnia interfejsu /privet/register API, MUSI zwracać błąd HTTP 404. Dlatego też jeśli urządzenie jest już zarejestrowane, wywołanie tego interfejsu API MUSI zwrócić wartość 404. W przypadku braku nagłówka X-Privet-Token urządzenie MUSI zwrócić błąd HTTP 400.

4.4. /privet/accesstoken API

/privet/accesstoken API jest OPCJI. Jest to żądanie HTTP GET. /privet/accesstoken API MUSI sprawdzać prawidłowy nagłówek "X-Privet-Token". Urządzenie MUSI używać tego interfejsu API w adresie URL "/privet/accesstoken":

GET /privet/accesstoken HTTP/1.1

Gdy urządzenie otrzyma wywołanie /accesstoken API, powinno wywołać serwer, aby pobrać token dostępu danego użytkownika i zwrócić go klientowi. Klient użyje tokena dostępu, aby uzyskać dostęp do tego urządzenia przez chmurę.

Urządzenia w Cloud Print MUSZĄ wywołać ten interfejs API:

/cloudprint/proximitytoken

i przekaż parametr "printerid=<printer_id>" &&tt;user" z lokalnego interfejsu API. Jeśli odpowiedź się powiedzie, serwer będzie zawierał ten obiekt:

"proximity_token": {
        "user": "user@domain.com",
        "token": "AAA111222333444555666777",
        "expires_in": 600
}

Urządzenia Cloud Print MUSZĄ przekazać wartość "proximity_token" w odpowiedzi na wywołania lokalnego interfejsu /privet/accesstoken API. Jest to korzystniejsze (zabezpieczanie w przyszłości), jeśli urządzenie może przekazywać WSZYSTKIE parametry (także te, które nie są opisane w tej specyfikacji).

4.4.1 Wprowadź tekst

/privet/accesstoken API ma następujące parametry wejściowe:

Nazwa	Wartość
użytkownik	Adres e-mail użytkownika, który miał używać tego tokena dostępu. Żądanie może być puste.

4.4.2 Zwróć

/privet/accesstoken API zwraca następujące dane:

Nazwa wartości	Typ wartości	Opis
token	tekst	Token dostępu zwrócony przez serwer
użytkownik	tekst	Ten sam użytkownik co w parametrze wejściowym.
wygasa_w	int,	Liczba sekund do wygaśnięcia tego tokena. Odebrano z serwera i przekazano w tej odpowiedzi.

Przykład

{
        "token": "AAA111222333444555666777",
        "user": "user@domain.com",
        "expires_in": 600
}

4.4.3 Błędy

/privet/accesstoken API może zwracać te błędy (szczegóły znajdziesz w sekcji Błędy):

Błąd	Opis
offline	Urządzenie jest obecnie offline i nie może połączyć się z serwerem.
dostęp_odrzucony	Niewystarczające prawa. Odmowa dostępu. Urządzenie powinno zwrócić ten błąd, jeśli żądanie zostało wyraźnie odrzucone przez serwer.
nieprawidłowe_parametry	W żądaniu określono nieprawidłowe parametry. Nieznane parametry należy bezpiecznie zignorować, aby zachować zgodność w przyszłości. Na przykład jeśli klient o nazwie /accesstoken?user= lub /accesstoken.
serwer_błąd	Błąd serwera.
nieprawidłowy_token_privet	Token X-Privet jest nieprawidłowy lub pusty w żądaniu.

Jeśli urządzenie nie ujawnia interfejsu /privet/accesstoken API, MUSI zwracać błąd HTTP 404. W przypadku braku nagłówka X-Privet-Token urządzenie MUSI zwrócić błąd HTTP 400.

4.5 /privet/capabilities API

/privet/capabilities API to NIESTANDARDOWY. Jest to żądanie HTTP GET. /privet/capabilities API MUSI sprawdzać prawidłowy nagłówek "X-Privet-Token". Urządzenie MUSI implementować ten interfejs API pod adresem &&pritt/capvet/capabilities" url:

GET /privet/capabilities HTTP/1.1

Jeśli urządzenie otrzymuje wywołanie /capabilities API, jeśli takie urządzenie jest w stanie wykonać, w celu uzyskania aktualnych możliwości NALEŻY skontaktować się z serwerem. Na przykład: jeśli drukarka obsługuje publikowanie zadania drukowania (otrzymanego lokalnie) w Cloud Print, to funkcja powinna zwrócić funkcje, które ta usługa zwróci. W tym przypadku Cloud Print może zmienić oryginalne możliwości drukarek, dodając nowe funkcje, które może wykonać przed wysłaniem zadania do drukarki. Najpopularniejszym przypadkiem jest lista obsługiwanych typów dokumentów. Jeśli drukarka jest offline, powinna pokazywać obsługiwane typy dokumentów. Jeśli jednak drukarka jest online i jest zarejestrowana w Cloud Print, MUSI zwrócić „"*/*"” jako jeden z obsługiwanych typów. W takim przypadku usługa Cloud Print wykona niezbędną konwersję. W przypadku drukowania w trybie offline drukarka MUSI obsługiwać format co najmniej „"image/pwg-raster"”.

4.5.1 Wprowadź tekst

/privet/capabilities API ma następujące parametry wejściowe:

Nazwa	Wartość
offline	(opcjonalnie) Możliwe jest tylko wartości "offline=1". W takim przypadku urządzenie powinno zwrócić funkcje do użytku w trybie offline (jeśli różni się od funkcji "online").

4.5.2 Zwróć

/privet/capabilities API zwraca funkcje urządzenia w formacie JSON (CDD) opisu urządzenia Cloud (szczegółowe informacje znajdziesz w dokumencie CDD). Drukarki MUSZĄ zwrócić listę obsługiwanych typów. Na przykład drukarka działająca w chmurze, która jest aktualnie online, może zwracać coś takiego (minimalnie):

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        {
                                "content_type": "application/pdf",
                                "min_version": "1.4"
                        },
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" },
                        { "content_type": "*/*" }
                ]
        }
}

Po odłączeniu od serwera może ona zwracać te dane:

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        {
                                "content_type": "application/pdf",
                                "min_version": "1.4"
                        },
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" }
                ]
        }
}

Uwaga: drukarki określają priorytet obsługiwanych typów treści według kolejności. Na przykład w przykładach powyżej drukarka określa, że preferuje &"application/pdf" dane zamiast "image/pwg-raster" i "image/jpeg". Jeśli to możliwe, klient powinien przestrzegać priorytetów dotyczących drukarek (aby dowiedzieć się więcej, przeczytaj dokument CDD).

4.5.3 Błędy

Interfejs /privet/capabilities API może zwracać poniższe błędy (szczegóły znajdziesz w sekcji Błędy):

Błąd	Opis
nieprawidłowy_token_privet	Token X-Privet-Token jest nieprawidłowy lub pusty w żądaniu.

Jeśli urządzenie nie ujawnia interfejsu /privet/capabilities API, MUSI zwracać błąd HTTP 404. W przypadku braku nagłówka X-Privet-Token urządzenie MUSI zwrócić błąd HTTP 400.

4.6 Błędy

Błędy zwracane przez powyższe interfejsy API są podawane w następującym formacie:

Nazwa wartości	Typ wartości	Opis
błąd	tekst	Typ błędu (zdefiniowany w interfejsie API)
opis	ciąg znaków (opcjonalnie)	Czytelny dla człowieka opis błędu.
server_api,	ciąg znaków (opcjonalnie)	W przypadku błędu serwera to pole zawiera interfejs Server API, którego nie udało się przetworzyć.
server_code,	int (opcjonalnie)	W przypadku błędu serwera to pole zawiera kod błędu zwrócony przez serwer.
server_http_code [kod_URL_serwera]	int (opcjonalnie)	W przypadku błędu HTTP serwera to pole zawiera serwer kodu błędu HTTP.
przekroczono limit czasu	int (opcjonalnie)	Liczba sekund, które klient musi odczekać przed ponowną próbą (dotyczy tylko błędów możliwych do odzyskania). Klient MUSI losowo losowo zmniejszać tę wartość do wartości większej niż 20%.

Jeśli brakuje nagłówka X-Privet-Token, wszystkie interfejsy API MUSZĄ zwrócić błąd HTTP 400.

HTTP/1.1 400 Brak nagłówka X-Privet-Token.

Przykład 1:

{
        "error": "server_error",
        "description": "Service unavailable",
        "server_api": "/submit",
        "server_http_code": 503
}

Przykład 2:

{
        "error": "printer_busy",
        "description": "Printer is currently printing other job",
        "timeout": 15
}

5. Printer API

Jednym z typów urządzeń obsługiwanych przez ten protokół jest drukarka. Urządzenia zgodne z tym typem mogą mieć wdrożone niektóre funkcje związane z drukarkami. W idealnym przypadku drukowanie na drukarkach działających w chmurze przechodzi przez serwer Cloud Print:

Może się zdarzyć, że klient będzie musiał wysłać dokument lokalnie. Może być potrzebna, gdy klient nie ma identyfikatora Google lub nie może połączyć się z serwerem Cloud Print. W takim przypadku zadanie drukowania zostanie przesłane lokalnie do drukarki. Ta drukarka będzie natomiast używać usługi Cloud Print do kolejkowania zadań i konwersji. Drukarka ponownie opublikuje zadanie przesłane lokalnie do usługi Cloud Print, a potem zażąda tego, bo zostało przesłane przez chmurę. Ten proces zapewni użytkownikom elastyczność w zakresie usług (konwersji) oraz zarządzania zadaniami drukowania i śledzenia.

Usługa Cloud Print implementuje konwersje, dlatego drukarka powinna PRAWDŹ obsługiwać wszystkie formaty danych wejściowych ("*/*") na liście obsługiwanych typów treści:

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "*/*" }
                ]
        }
}

W niektórych przypadkach rozwiązanie jest całkowicie offline. Drukarki obsługują ograniczoną liczbę formatów wejściowych, więc klient musi przekonwertować dokumenty na kilka formatów natywnych, które są obsługiwane.

Ta specyfikacja wymaga wszystkich drukarek, które obsługują co najmniej format PWG Raster ("image/pwg-raster") do drukowania w trybie offline. Drukarka może obsługiwać inne formaty (np. JPEG) i jeśli klient ją obsługuje, może wysyłać dokumenty w tym formacie. Drukarka musi eksponować obsługiwane typy przez interfejs /capabilities API, na przykład:

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" }
                ]
        }
}

Klient może rozpocząć drukowanie przez sieć lokalną na dwa sposoby.

Proste drukowanie – klient wysyła dokument przez sieć lokalną do interfejsu /submitdoc API (bez podawania parametru work_id). Przesłany dokument zostanie wydrukowany przy użyciu domyślnych ustawień drukowania i nie będą potrzebne stany zadań drukowania. Jeśli drukarka obsługuje tylko ten rodzaj drukowania, MUSI wyświetlać w interfejsie /privet /info API tylko interfejs/submitdoc API.

"api": [
        "/privet/accesstoken",
        "/privet/capabilities",
        "/privet/printer/submitdoc",
]

Drukowanie zaawansowane – klient powinien najpierw utworzyć zadanie drukowania na drukarce, wywołując interfejs API /privet/printer/createjob z ważnym zgłoszeniem CJT w żądaniu. Drukarka MUSI przechowywać bilet drukowany w pamięci i zwracać identyfikator zadania_z powrotem do klienta. Następnie klient wywoła interfejs /printer/submitdoc API i określi wcześniej otrzymany identyfikator job_id. Drukarka rozpocznie od tego momentu. Klient może sprawdzić stan zadania drukowania przez wywoływanie interfejsu API /privet/printer/jobstate.

W środowisku multiklienta nie ma gwarancji, że interfejs API zostanie wywołany. Jeden klient może wywołać metodę /createjob między wywołaniami /createjob->/submitdoc. Aby uniknąć możliwych blokad i ułatwić obsługę, zalecamy utworzenie na kolejce drukarki oczekujących zadań drukowania (co najmniej 3–5):

/createjob zajmuje pierwsze miejsce w kolejce.
Czas trwania zadania (w kolejce) wynosi co najmniej 5 minut.
Jeśli wszystkie miejsca w kolejce zostaną zajęte, najstarsze zadanie drukowania nie zostanie usunięte i znajdzie się w nim nowe miejsce.
Jeśli na urządzeniu jest obecnie uruchomione zadanie drukowania (proste lub zaawansowane drukowanie), /submitdoc powinno zwracać stan „Zajęty” i zaproponować czas oczekiwania na ponowienie próby.
Jeśli identyfikator /submitdoc odnosi się do zadania, które zostało usunięte z kolejki (z powodu zastąpienia lub przekroczenia limitu czasu), drukarka powinna zwrócić błąd invalid_print_job, a klient ponowi próbę procesu z kroku /createjob. Klient musi zaczekać 5 sekund na losowy czas oczekiwania (maksymalnie 5 sekund), zanim spróbujesz ponownie.

Jeśli ograniczenia pamięci uniemożliwiają przechowywanie wielu oczekujących zadań na urządzeniu, kolejka może mieć 1 zadanie. Powinna ona korzystać z tego samego protokołu co powyżej. Jeśli po wykonaniu zadania wystąpi błąd, drukarka powinna przechowywać informacje o stanie zadania przez co najmniej 5 minut. Rozmiar kolejki zadań do przechowywania zakończonych zadań powinien wynosić co najmniej 10. Jeśli chcesz zachować więcej stanów zadania, najstarszy może zostać usunięty z kolejki przed upływem 5 minut.

Uwaga: na razie klienci mogą przeglądać ankiety pod kątem stanu zlecenia. W przyszłości możemy wymagać, aby drukarka wyświetlała powiadomienia TXT DNS po zmianie stanu zadania drukowania.

5.1. /privet/printer/createjob API

/privet/printer/createjob API jest opcjonalny (patrz powyżej). Jest to żądanie POST w protokole HTTP. /privet/printer/createjob API MUSI sprawdzać prawidłowy nagłówek "X-Privet-Token". Urządzenie MUSI wdrożyć ten interfejs API w "/privet/printer/createjob" url:

POST /privet/printer/createjob HTTP/1.1

Gdy odbierasz wywołanie interfejsu /privet/printer/createjob API, drukarka MUSI utworzyć nowy identyfikator zadania drukowania, zapisać odebrane zgłoszenie drukowania w formacie CJT i zwrócić identyfikator zadania drukowania klientowi.

5.1.1. Wprowadź tekst

Interfejs /privet/printer/createjob API nie zawiera parametrów wejściowych w adresie URL. Treść żądania powinna zawierać dane biletu na zadanie w formacie CJT.

5.1.2. Zwróć

/privet/printer/createjob API zwraca te dane:

Nazwa wartości	Typ wartości	Opis
identyfikator_zadania	tekst	Identyfikator nowo utworzonego zadania drukowania.
wygasa_w	int,	Liczba sekund tego zadania drukowania.

Przykład

{
        "job_id": "123",
        "expires_in": 600
}

5.1.3 Błędy

/privet/printer/createjob API może zwracać następujące błędy (szczegóły znajdziesz w sekcji Błędy):

Błąd	Opis
Nieprawidłowy_bilet	Przesłany bilet drukowany jest nieprawidłowy.
drukarka_zajęty	Drukarka jest zajęta i nie może teraz przetworzyć /createjob. Spróbuj ponownie po upływie limitu czasu.
drukarka_błąd	Drukarka jest w stanie błędu i wymaga interwencji użytkownika. Opis powinien zawierać bardziej szczegółowe informacje (np. „Papier papierowy w obszarze powiadomień 1”).
nieprawidłowy_token_privet	Token X-Privet-Token jest nieprawidłowy lub pusty w żądaniu.

Jeśli urządzenie nie ujawnia /privet/printer/createjob, MUSI zwracać błąd HTTP 404. W przypadku braku nagłówka X-Privet-Token urządzenie MUSI zwrócić błąd HTTP 400.

5.2. /privet/printer/submitdoc API

/privet/printer/submitdoc API jest WYMAGANE do implementacji drukowania przez sieć lokalną (offline lub w usłudze Cloud Print). Jest to żądanie HTTP POST. /privet/printer/submitdoc API MUSI sprawdzać prawidłowy nagłówek "X-Privet-Token". Urządzenie MUSI zaimplementować ten interfejs API pod adresem URL: &privet/printer/submitdoc" url:

POST /privet/printer/submitdoc HTTP/1.1

Jeśli nie można rozpocząć drukowania, MUSI zwrócić błąd_druk_druku i zalecany czas oczekiwania, zanim klient ponowi próbę.

Jeśli drukarka nie jest w stanie przechowywać wszystkich danych w swoim wewnętrznym buforze, powinna używać mechanizmów TCP, aby spowolnić przesyłanie danych do momentu wydrukowania części dokumentu, co pozwoli na ponowne udostępnienie części bufora. (Na przykład drukarka może ustawić wartość oknawindow=0 w warstwach TCP, przez co klient czeka).

Przesłanie dokumentu do drukarki może zająć dużo czasu. W trakcie drukowania klient powinien mieć możliwość sprawdzenia stanu drukarki i zadania (zaawansowanego drukowania). W tym celu drukarka MUSI zezwalać klientowi na wywoływanie interfejsów API /privet/info i /privet/printer/jobstate przy przetwarzaniu wywołań interfejsu /privet/printer/submitdoc API. Wszystkim klientom zalecamy uruchamianie nowego wątku do wykonywania wywołań interfejsu API /privet/printer/submitdoc, aby mieć pewność, że główny wątek będzie używać interfejsów /privet/info i /privet/printer/jobstate do sprawdzania stanów drukarek i zadań.

Uwaga: po zakończeniu lub aborcji lokalnego zadania drukowania zdecydowanie zalecamy (i będzie to wymagane w przyszłej wersji tej specyfikacji) do przesłania informacji o ostatecznym stanie zadania do interfejsu //+//submit w celu księgowości i wrażenia użytkownika. Parametry "printerid", "title", "contentType" i "final_semantic_state" (w formacie PrintJobState) oraz parametry "tag" (powtórzony parametr) i "bilet Pamiętaj, że podany parametr PrintJobState musi być ostateczny, czyli jego typ to GOTOWE lub ABORTED, a informację o przyczynie należy podać w przypadku błędu ABORTED (szczegóły znajdziesz na stronie JobState). Pamiętaj też, że korzystanie z interfejsu //+//submit do zgłaszania lokalnych zadań drukowania nie jest wymienione w specyfikacji, bo ta sekcja służy do opisania głównego zastosowania interfejsu: przesłania zadania drukowania z dokumentem do wydrukowania w parametrze "content"

5.2.1. Wprowadź tekst

/privet/printer/submitdoc API ma następujące parametry wejściowe:

Nazwa	Wartość
identyfikator_zadania	(Opcjonalnie) Identyfikator zadania drukowania. Może być pomijany w przypadku prostych wydruków (patrz powyżej). Musi być zgodny z adresem zwracanym przez drukarkę.
nazwa_użytkownika	(Opcjonalnie) Czytelna nazwa użytkownika. Nie jest to definitywnie określone i powinno być używane tylko w przypadku adnotacji do zadań drukowania. Jeśli zadanie zostanie ponownie opublikowane w usłudze Cloud Print, dołącz ten ciąg do zadania Cloud Print.
nazwa_klienta	(Opcjonalnie) Nazwa aplikacji klienckiej wysyłającej to żądanie. Tylko do wyświetlania. Jeśli zadanie zostanie ponownie opublikowane w usłudze Cloud Print, ten ciąg powinien być dołączony do zadania Cloud Print.
nazwa_zadania	(Opcjonalnie) Nazwa zadania drukowania, które ma zostać zarejestrowane. Jeśli zadanie zostanie ponownie opublikowane w usłudze Cloud Print, ten ciąg powinien być dołączony do zadania Cloud Print.
offline	(opcjonalnie) Możliwe wartości to "offline=1". W takim przypadku drukarka powinna spróbować drukować tylko offline (bez ponownego publikowania na serwerze Cloud Print).

Treść żądania powinna zawierać prawidłowy dokument do wydrukowania. "Content-Length" powinien zawierać prawidłową długość żądania. Nagłówek "Content-Type" powinien być ustawiony na typ MIME dokumentu i pasować do jednego z typów CDD (chyba że CDD określa "*/*").

Zdecydowanie zalecamy klientom podanie prawidłowej nazwy użytkownika (lub adresu e-mail), nazwy klienta oraz nazwy zadania wraz z tym żądaniem. Te pola są używane tylko w interfejsach użytkowników, aby zwiększyć wygodę użytkowników.

5.2.2. Zwróć

/privet/printer/submitdoc API zwraca następujące dane:

Nazwa wartości	Typ wartości	Opis
identyfikator_zadania	tekst	Identyfikator nowo utworzonego zadania drukowania (proste drukowanie) lub identyfikator zadania w żądaniu (zaawansowane drukowanie).
wygasa_w	int,	Liczba sekund tego zadania drukowania.
work_type (typ zadania)	tekst	Typ treści przesłanego dokumentu.
work_size	int 64-bitowy	Rozmiar danych wydruku w bajtach.
nazwa_zadania	tekst	(Opcjonalnie) Ta sama nazwa co w danych wejściowych (jeśli istnieje).

Przykład

{
        "job_id": "123",
        "expires_in": 500,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document"
}

5.2.3. Błędy

/privet/printer/submitdoc API może zwracać następujące błędy (szczegóły znajdziesz w sekcji Błędy):

Błąd	Opis
nieprawidłowy_druk_zadania	W żądaniu określono nieprawidłowy lub wygasły identyfikator zadania. Spróbuj ponownie po upływie limitu czasu.
nieprawidłowy_typ_dokumentu	Drukarka nie obsługuje typu MIME dokumentu.
nieprawidłowy_dokument	Przesłany dokument jest nieprawidłowy.
dokument_zbyt_duży	Rozmiar dokumentu przekracza maksymalną dozwoloną wartość.
drukarka_zajęty	Drukarka jest zajęta i nie może teraz przetworzyć dokumentu. Spróbuj ponownie po upływie limitu czasu.
drukarka_błąd	Drukarka jest w stanie błędu i wymaga interwencji użytkownika. Opis powinien zawierać bardziej szczegółowe informacje (np. „Papier papierowy w obszarze powiadomień 1”).
nieprawidłowe_parametry	W żądaniu określono nieprawidłowe parametry. Nieznane parametry należy bezpiecznie zignorować na potrzeby zgodności w przyszłości.
user_cancel	Użytkownik wyraźnie anulował proces drukowania z urządzenia.
serwer_błąd	Nie udało się opublikować dokumentu w Cloud Print.
nieprawidłowy_token_privet	Token X-Privet-Token jest nieprawidłowy lub pusty w żądaniu.

Jeśli urządzenie nie ujawnia pliku /privet/printer/submitdoc, MUSI zwracać błąd HTTP 404. W przypadku braku nagłówka X-Privet-Token urządzenie MUSI zwrócić błąd HTTP 400.

Uwaga: interfejs /privet/printer/submitdoc API może wymagać specjalnej obsługi po stronie drukarki (z powodu dużego ładunku). W niektórych przypadkach (zależy to od implementacji serwera HTTP i platformy) drukarka może zamknąć gniazdo PRZED zwracaniem błędu HTTP. W innych sytuacjach drukarka może zwrócić błąd 503 (zamiast błędu Privet). Drukarki POWÓD powinny być jak najbardziej zwrócone w ramach aplikacji Privet. Jednak każdy klient korzystający ze specyfikacji Privet powinien mieć możliwość obsługi gniazda (brak błędu HTTP) i błędów HTTP 503 w przypadku interfejsu /privet/printer/submitdoc API. W takim przypadku klient powinien podać go jako błąd &pret;printer_busy" z parametrem "timeout" ustawionym na 15 sekund. Aby uniknąć ponownych prób, klient może ponawiać próbę po rozsądnej liczbie prób (na przykład 3).

5.3. /privet/printer/jobstate API

/privet/printer/jobstate API jest opcjonalny (patrz powyżej). Jest to żądanie HTTP GET. /privet/printer/jobstate API MUSI sprawdzać prawidłowy nagłówek "X-Privet-Token". Urządzenie MUSI implementować ten interfejs API pod adresem "/privet/printer/jobstate" url:

GET /privet/printer/jobstate HTTP/1.1

Przy otrzymaniu wywołania /privet/printer/jobstate API drukarka powinna zwrócić stan żądanego zadania drukowania lub błędu error_print_job.

5.3.1. Wprowadź tekst

/privet/printer/jobstate API zawiera następujące parametry wejściowe:

Nazwa	Wartość
identyfikator_zadania	Identyfikator zadania drukowania, dla którego chcesz zwrócić stan.

5.3.2. Zwróć

/privet/printer/jobstate API zwraca te dane:

Nazwa wartości	Typ wartości	Opis
identyfikator_zadania	tekst	Identyfikator zadania drukowania, z którego pochodzą informacje o stanie.
state	tekst	wersja robocza – na urządzeniu zostało utworzone zadanie drukowania (brak odebranych połączeń /privet/printer/submitdoc). w kolejce – zadanie drukowania zostało odebrane i umieszczone w kolejce, ale drukowanie jeszcze się nie rozpoczęło. w toku – zadanie drukowania jest w toku. Zatrzymane – zadanie drukowania zostało wstrzymane, ale można je uruchomić ponownie ręcznie lub automatycznie. gotowe – zadanie drukowania zostało wykonane. Przerwano – zadanie drukowania nie powiodło się.
opis	tekst	(Opcjonalnie) Czytelny dla człowieka opis stanu zadania drukowania. Powinien zawierać dodatkowe informacje, jeśli pole state jest zatrzymane lub przerwane. Pole semantic_state zwykle zapewnia klientowi lepszy i bardziej zrozumiały opis.
wygasa_w	int,	Liczba sekund tego zadania drukowania.
work_type (typ zadania)	tekst	(Opcjonalnie) Typ treści przesłanego dokumentu.
work_size	int 64-bitowy	(Opcjonalnie) Rozmiar danych wydruku w bajtach.
nazwa_zadania	tekst	(Opcjonalnie) Ta sama nazwa co w danych wejściowych (jeśli istnieje).
identyfikator_zadania_serwera	tekst	(Opcjonalnie) Identyfikator zadania zwróconego z serwera (jeśli zadanie zostało opublikowane w usłudze Cloud Print). Pomiń drukowanie w trybie offline.
semantyczny_stan	JSON	(Opcjonalnie) Stan semantyczny zadania w formacie PrintJobState.

Przykład (drukowanie przez raportowanie w Cloud Print):

{
        "job_id": "123",
        "state": "in_progress",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document",
        "server_job_id": "1111-2222-3333-4444"
}

Przykład (błąd drukowania offline):

{
        "job_id": "123",
        "state": "stopped",
        "description": "Out of paper",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document"
}

Przykład (zadanie drukowania zostało przerwane przez użytkownika):

{
        "job_id": "123",
        "state": "aborted",
        "description": "User action",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document",
        "semantic_state": {
                "version": "1.0",
                "state": {
                        "type": "ABORTED",
                        "user_action_cause": {"action_code": "CANCELLED"}
                },
                "pages_printed": 7
        }
}

Przykład (zadanie drukowania zostało zatrzymane z powodu braku papieru). Zwróć uwagę na odwołanie do stanu urządzenia. Aby uzyskać więcej informacji o stanie urządzenia, klient musi wywołać interfejs /privet/info API:

{
        "job_id": "123",
        "state": "stopped",
        "description": "Out of paper",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": "123456",
        "job_name": "My PDF document",
        "semantic_state": {
                "version": "1.0",
                "state": {
                        "type": "STOPPED",
                        "device_state_cause": {"error_code": "INPUT_TRAY"}
                },
                "pages_printed": 7
        }
}

5.3.3. Błędy

/privet/printer/jobstate API może zwrócić ten błąd (szczegóły znajdziesz w sekcji Błędy):

Błąd	Opis
nieprawidłowy_druk_zadania	W żądaniu określono nieprawidłowy lub wygasły identyfikator zadania.
serwer_błąd	Nie udało się pobrać stanu zadania drukowania (dla zadań drukowania opublikowanych w Cloud Print).
nieprawidłowy_token_privet	Token X-Privet-Token jest nieprawidłowy lub pusty w żądaniu.

Jeśli urządzenie nie ujawnia kodu /privet/printer/jobstate, MUSI zwracać błąd HTTP 404. W przypadku braku nagłówka X-Privet-Token urządzenie MUSI zwrócić błąd HTTP 400.

6. Dodatek

6.1. Domyślne zachowanie i ustawienia

W tej sekcji wyjaśnimy domyślne zachowanie, których oczekujemy od WSZYSTKICH urządzeń zgodnych z Privet.

Gotowe urządzenia powinny obsługiwać tylko interfejsy API /privet/info i /privet/register. Wszystkie inne interfejsy API (np. /privet/accesstoken, drukowanie lokalne) powinny być wyłączone.
Rejestracja wymaga interakcji fizycznej z urządzeniem.

Użytkownik MUSI wykonywać czynności fizyczne na urządzeniu (np. naciskając przycisk), aby potwierdzić dostęp.
Gdy użytkownik wykona działanie opisane powyżej, drukarka powinna wysłać żądanie //+//register. Prośba nie powinna być wysyłana do momentu wykonania działania (patrz Diagram sekwencji 1).
Jeśli urządzenie przetwarza żądanie /privet/register (np. czekając na działanie powyżej), musi odrzucić wszystkie pozostałe żądania /privet/register. W tym przypadku urządzenie MUSI zwrócić błąd device_busy.
Urządzenie powinno przed upływem 60 sekund przekroczyć limit czasu żądania /register, które nie otrzymuje powyższego działania fizycznego. W tym przypadku urządzenie MUSI zwrócić błąd potwierdzenia_czasu.
Opcjonalnie: zalecane, ale niewymagane, mogą poprawić wygodę użytkowników:

Drukarka może zapalić diodę lub ekran, żeby wskazać, że użytkownik musi wykonać działanie, aby potwierdzić rejestrację.
Drukarka może poinformować na ekranie, że „jest zarejestrowana w Google Cloud Print dla użytkownika abc@def.com”. Naciśnij OK, aby kontynuować, gdzie abc@def.com to parametr użytkownika z wywołania /register API. Dzięki temu użytkownicy będą wiedzieć, że:

prosi o potwierdzenie rejestracji
Co się stanie, jeśli prośba nie została wywołana?

Oprócz fizycznego działania wymagającego potwierdzenia przez drukarkę (np. „Naciśnij przycisk OK”), drukarka może też udostępnić użytkownikowi przycisk do anulowania prośby (np. „Naciśnij Anuluj, aby odrzucić”). Umożliwi to użytkownikom, którzy nie wywołali prośby o rejestrację, przed upływem 60 sekund. W tym przypadku urządzenie MUSI zwrócić błąd user_cancel.

Przeniesienie własności:

Urządzenie może zostać usunięte bezpośrednio z usługi w chmurze.

Jeśli urządzenie się powiedzie, ale nie otrzyma opisu urządzenia w wyniku wywołania //+//printer (w przypadku GCP), MUSI przywrócić tryb domyślny (po uruchomieniu).
Jeśli dane logowania na urządzeniu nie działają (częściowo ze względu na nieprawidłowości w odpowiedzi z serwera), MUSISZ przywrócić tryb domyślny (Gotowe).

Lokalna fabryka resetuje dane logowania urządzenia i ustawia jego domyślny stan.
Opcjonalnie: urządzenie może udostępniać funkcję menu, aby wyczyścić dane logowania i włączyć tryb domyślny.

Urządzenia obsługujące powiadomienia XMPP MUSZĄ zawierać funkcję pingowania serwera. Czas oczekiwania na polecenie ping musi być kontrolowany przez serwer za pomocą parametru "local_settings".
Urządzenie może wysyłać pingi do serwera (/saml/printer API w GCP), a także do pingów XMPP nie częściej niż raz na 24 godziny, aby upewnić się, że są zsynchronizowane. Zalecamy losowo ustawienie okna kontrolnego w ciągu 24–32 godzin.
Opcjonalnie: w przypadku urządzeń Cloud Print zaleca się ręczne ustawianie przycisku (przycisku), aby użytkownik mógł rozpocząć sprawdzanie nowych zadań drukowania z tego urządzenia. Niektóre drukarki już go mają.
Opcjonalne. Drukarki firmowe mogą całkowicie wyłączyć wykrywanie lokalne. W takim przypadku urządzenie MUSI zaktualizować te ustawienia lokalne na serwerze. Nowe ustawienia lokalne muszą być puste (ustawienie "local_discovery" "false" oznacza, że można je ponownie włączyć w usłudze GCP).

6.1.2 Domyślny wykres rejestracyjny

6.2. XSSI i XSRF

W tej sekcji wyjaśnimy, jakie są możliwe ataki XSSI i XSRF na urządzeniu oraz jak je chronić (w tym techniki generowania tokenów).
Więcej informacji znajdziesz tutaj: http://googleonlinesecurity.blogspot.com/2011/05/website-security-for-webmasters.html
Zwykle ataki XSSI i XSRF są możliwe, gdy witryna korzysta z mechanizmów uwierzytelniania plików cookie. Google nie używa plików cookie w usłudze Cloud Print, ale takie ataki nadal są możliwe. Domyślnie dostęp do sieci lokalnej jest traktowany jako zaufany.

6.2.1. xSSI

Szkodliwe witryny mogą odgadnąć adres IP i numer portu urządzenia zgodnego z Privet, a także spróbować wywołać interfejs Privet API przy użyciu &tagu <script>tag:

<script type="text/javascript" src="http://192.168.1.42:8080/privet/info"></script>

Bez ochrony złośliwe witryny będą mogły wykonywać wywołania interfejsu API i dostęp do wyników.
Aby zapobiec takiemu ataku, WSZYSTKIE wywołania interfejsu Privet API MUSZĄ zawierać w żądaniu nagłówek &"X-Privet-Token". "src=<api>" Tagi skryptu nie mogą dodawać nagłówków, aby skutecznie zapobiegać takim atakom.

6.2.2. XSRF,

http://en.wikipedia.org/wiki/cross-site_request_forgery
Złośliwa witryna może odgadnąć adres IP i numer portu urządzenia zgodnego z Privet, używając do tego celu <iframe>; Osoby przeprowadzające atak nie mogą uzyskać dostępu do wyników żądania, ale jeśli żądanie wykonuje działanie (np. drukowanie), może je wywołać.

Aby zapobiec temu atakowi, wymagamy zabezpieczenia:

Pozostaw interfejs /privet/info API otwarty na klucz XSRF
/privet/info API NIE MUSI wykonywać żadnych działań na urządzeniu
Aby odebrać x-privet-token, użyj interfejsu /privet/info API
Wszystkie pozostałe interfejsy API MUSZĄ wyszukać prawidłowy nagłówek x-privet-token w parametrze "X-Privet-Token".
Kod x-privet-token powinien być ważny tylko przez 24 godziny.

Nawet jeśli atakujący będzie mógł wykonać interfejs /privet/info, nie będzie mógł odczytać tokenu x-privet-token, co oznacza, że nie będzie mógł wywoływać innego interfejsu API.

Zdecydowanie zalecamy wygenerowanie tokena XSRF za pomocą tego algorytmu:

XSRF_token = base64( SHA1(device_secret + DELIMITER + issue_timecounter) + DELIMITER + issue_timecounter )

Elementy generowania tokena XSRF:

DELIMITER to znak specjalny, zwykle „:”
issue_timecounter to liczba sekund od chwili, gdy jakieś zdarzenie (np. sygnatura czasowa) lub czas uruchamiania urządzenia (liczniki procesora) stale rosną, gdy urządzenie działa i działa (patrz weryfikacja tokena poniżej).
SHA1 – funkcja skrótu za pomocą algorytmu SHA1
base64 – kodowanie base64
device_secret – obiekt tajny przypisany do urządzenia. Tajny klucz urządzenia MUSI być aktualizowany przy każdym ponownym uruchomieniu.

Zalecane sposoby generowania obiektu tajnego urządzenia:

Wygeneruj nowy identyfikator UUID przy każdym ponownym uruchomieniu
Wygeneruj 64-bitową liczbę losową przy każdym ponownym uruchomieniu

Urządzenie nie musi przechowywać wszystkich wystawionych tokenów XSRF. Gdy urządzenie musi zweryfikować token XSRF, powinien on odkodować token za pomocą base64. Uzyskaj issue_timecounter z drugiej połowy (wyczyść tekst) i spróbuj wygenerować identyfikator SHA1 dla zdarzenia device_secret + Nexus + + issue_timecounter, gdzie issue_timecounter pochodzi z tokena. Jeśli nowo wygenerowany SHA1 jest zgodny z tym w tokenie, urządzenie musi teraz sprawdzić, czy issue_timecounter mieści się w okresie ważności od (24 godzin) bieżącego licznika czasu. W tym celu urządzenie pobiera bieżący licznik czasu (np. licznik procesora) i odejmuje od niego wartość issue_timecounter. Wynik musi MUSI wskazywać liczbę sekund od problemu z tokenem.

Ważne: to zalecany sposób wdrażania ochrony XSRF. Klienci ze specyfikacji Privet nie powinni zrozumieć tokena XSRF, zamiast tego będą traktować je jako blackbox. Rysunek 6.2.3 ilustruje zalecany sposób implementacji tokena X-Privet i weryfikacji typowego żądania.

6.2.3 Schemat generowania tokenów X-Privet i weryfikacji

6.3 Diagramy przepływu pracy

Ta sekcja ilustruje przepływ pracy w różnych przypadkach.

6.3.1 Drukarka od razu po uruchomieniu

6.3.2 Uruchamianie uruchomionej drukarki

6.3.3 Zarządzanie procesami powiadomień XMPP

6.3.4 Sprawdź ustawienia drukarki