Google Cloud Print tidak lagi didukung mulai tanggal 31 Desember 2020. Lihat artikel dukungan untuk mendapatkan bantuan terkait migrasi.

Halaman ini diterjemahkan oleh Cloud Translation API.

Privet

Privet adalah Cloud Device Local Discovery API yang digunakan oleh layanan cloud. Dokumen ini disusun ke dalam bagian-bagian berikut:

Pengantar: pengantar Privet
Penemuan: mekanisme penemuan lokal
Pengumuman: pengumuman penemuan lokal
API: Privet API untuk perangkat cloud umum
Printer API: Privet API yang digunakan oleh printer
Lampiran: diagram tambahan

1. Pengantar

Perangkat yang terhubung ke cloud memiliki banyak manfaat. Mereka dapat menggunakan layanan konversi online, menghosting antrean tugas saat perangkat offline, dan dapat diakses dari mana saja di dunia. Namun, dengan banyaknya perangkat cloud yang dapat diakses oleh pengguna tertentu, kita perlu menyediakan metode untuk menemukan perangkat terdekat berdasarkan lokasi. Tujuan protokol Privet adalah untuk mengikat fleksibilitas perangkat cloud dengan mekanisme penemuan lokal yang sesuai sehingga perangkat dapat ditemukan dengan mudah di lingkungan baru.

Tujuan protokol ini adalah:

membuat perangkat cloud dapat ditemukan secara lokal
mendaftarkan perangkat cloud dengan layanan cloud
mengaitkan perangkat terdaftar dengan representasi cloud-nya
mengaktifkan fungsi offline
menyederhanakan penerapan sehingga perangkat kecil dapat memanfaatkannya

Protokol Privet terdiri dari 2 bagian utama: penemuan dan API. Penemuan digunakan untuk menemukan perangkat di jaringan lokal, dan API digunakan untuk mendapatkan informasi tentang perangkat dan melakukan beberapa tindakan. Di seluruh dokumen ini, perangkat mengacu pada perangkat yang terhubung ke cloud yang menerapkan protokol Privet.

2. Discovery

Penemuan adalah protokol berbasis zeroconf (mDNS + DNS-SD). Perangkat HARUS menerapkan Pengalamatan Link-Lokal IPv4. Perangkat HARUS mematuhi spesifikasi mDNS dan 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)

Perangkat HARUS melakukan penyelesaian konflik nama sesuai dengan spesifikasi di atas.

2.1. Jenis Layanan

Penemuan Layanan DNS menggunakan format berikut untuk jenis layanan: _applicationprotocol._transportprotocol. Dalam kasus protokol Privet, jenis layanan untuk DNS-SD harus: _privet._tcp

Perangkat juga dapat menerapkan jenis layanan lainnya. Sebaiknya gunakan nama instance layanan yang sama untuk semua jenis layanan yang diterapkan oleh perangkat. Misalnya: printer dapat menerapkan layanan "Printer XYZ._privet._tcp" dan "Printer XYZ._printer._tcp". Hal ini akan menyederhanakan penyiapan bagi pengguna. Namun, klien Privet hanya akan mencari "_privet._tcp".

Selain jenis layanan utama, perangkat HARUS mengiklankan data PTR untuk subjenis yang sesuai (lihat spesifikasi DNS-SD: "7.1. Selective Instance Enumeration (Subtypes)"). Formatnya harus sebagai berikut: _<subtype>._sub._privet._tcp

Saat ini, satu-satunya subjenis perangkat yang didukung adalah printer. Jadi, semua printer HARUS mengiklankan dua data PTR:

_privet._tcp.local.
_printer._sub._privet._tcp.local.

2.2. Data TXT

Penemuan Layanan DNS menentukan kolom untuk menambahkan informasi opsional tentang layanan dalam data TXT. Data TXT terdiri dari key-value pair. Setiap pasangan nilai kunci dimulai dari byte panjang yang diikuti dengan teks hingga 255 byte. Kuncinya adalah teks sebelum karakter ‘=’ pertama dan nilainya adalah teks setelah karakter ‘=’ pertama hingga akhir. Spesifikasi tidak mengizinkan nilai dalam rekaman, dalam hal ini tidak akan ada karakter '=' ATAU tidak ada teks setelah karakter '='. (Lihat spesifikasi DNS-SD: "6.1. Aturan Format Umum untuk Data TXT DNS" untuk format data TXT DNS dan "6.2. DNS-SD TXT Record Size" untuk panjang yang direkomendasikan).

Privet mengharuskan perangkat mengirim key/value pair berikut dalam data TXT. String Kunci/Nilai tidak peka huruf besar/kecil, misalnya "CS=online" dan "cs=ONLINE" sama. Informasi dalam catatan TXT HARUS sama dengan yang dapat diakses melalui /info API (lihat 4.1. bagian API).

Sebaiknya jaga ukuran data TXT di bawah 512 byte.

2.2.1. txtvers

Versi struktur TXT. txtvers HARUS menjadi data pertama dari struktur TXT. Saat ini, hanya versi 1 yang didukung.

txtvers=1

2.2.2. ty

Memberikan nama perangkat yang dapat dibaca pengguna. Contoh:

ty=Google Cloud Ready Printer Model XYZ

2.2.3. catatan (opsional)

Memberikan nama perangkat yang dapat dibaca pengguna. Contoh:

note=1st floor lobby printer

Catatan: Ini adalah kunci opsional dan dapat dilewati. Namun, jika ada, pengguna HARUS dapat mengubah nilai ini. Deskripsi yang sama HARUS digunakan saat mendaftarkan perangkat.

2.2.4. url

URL server yang terhubung ke perangkat ini (termasuk protokol). Contoh:

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

2.2.5. type

Daftar subtype perangkat yang dipisahkan koma yang didukung oleh perangkat ini. Formatnya adalah: "type=_subtype1,_subtype2". Saat ini, satu-satunya subjenis perangkat yang didukung adalah printer.

type=printer

Setiap subjenis yang tercantum harus diiklankan menggunakan data PTR yang sesuai. Untuk setiap subjenis layanan yang didukung, harus ada satu item yang sesuai. Nama subjenis layanan (<subtype>._sub._privet._tcp) harus sama dengan jenis perangkat di sini.

2.2.6. id

ID perangkat. Jika perangkat belum didaftarkan, kunci ini harus ada, tetapi nilainya harus kosong. Contoh:

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

2.2.7. cs

Menunjukkan status koneksi perangkat saat ini. Empat kemungkinan nilai ditentukan dalam spesifikasi ini.

"online" menunjukkan bahwa perangkat saat ini terhubung ke cloud.
"offline" menunjukkan bahwa perangkat tersedia di jaringan lokal, tetapi tidak dapat berkomunikasi dengan server.
"menghubungkan" menunjukkan bahwa perangkat sedang melakukan urutan startup dan belum sepenuhnya online.
"not-configured" menunjukkan bahwa akses internet perangkat belum dikonfigurasi. Nilai ini saat ini tidak digunakan, tetapi mungkin berguna dalam versi spesifikasi mendatang.

Contoh:

cs=online
cs=offline
cs=connecting

Jika perangkat telah didaftarkan ke cloud, saat dimulai, perangkat harus memeriksa konektivitas dengan server untuk mendeteksi status koneksinya (misalnya, memanggil cloud API untuk mendapatkan setelan perangkat). Perangkat dapat menggunakan status koneksi saluran notifikasinya (misalnya, XMPP) untuk melaporkan nilai ini. Perangkat yang tidak terdaftar saat startup dapat melakukan ping ke domain untuk mendeteksi status koneksinya (misalnya, melakukan ping ke www.google.com untuk perangkat cloud print).

3. Pengumuman

Saat perangkat dimulai, dimatikan, atau statusnya berubah, perangkat HARUS melakukan langkah pengumuman seperti yang dijelaskan dalam spesifikasi mDNS. SHOULD mengirimkan pengumuman yang sesuai setidaknya dua kali dengan interval minimal satu detik di antara pengumuman tersebut.

3.1. Startup

Saat perangkat dimulai, perangkat HARUS melakukan langkah-langkah probing dan pengumuman seperti yang dijelaskan dalam spesifikasi mDNS. Data SRV, PTR, dan TXT harus dikirim dalam kasus ini. Sebaiknya kelompokkan semua data ke dalam satu respons DNS jika memungkinkan. Jika tidak, urutan berikut direkomendasikan: SRV, PTR, TXT.

3.2. Nonaktif

Saat perangkat dimatikan, perangkat HARUS mencoba memberi tahu semua pihak yang berkepentingan dengan mengirimkan "paket perpisahan" dengan TTL=0 (seperti yang dijelaskan dalam dokumentasi mDNS).

3.3. Perbarui

Jika ada informasi yang dijelaskan dalam TXT telah berubah, perangkat HARUS mengirimkan pengumuman pembaruan. Dalam hal ini, cukup kirimkan data TXT baru. Misalnya, setelah perangkat didaftarkan, perangkat tersebut HARUS mengirimkan pengumuman pembaruan yang menyertakan ID perangkat baru.

4. API

Setelah perangkat cloud ditemukan, komunikasi klien diaktifkan dengan perangkat langsung melalui jaringan lokal. Semua API berbasis HTTP 1.1. Format data berbasis JSON. Permintaan API dapat berupa permintaan GET atau POST.

Setiap permintaan HARUS berisi header "X-Privet-Token" yang valid. Satu-satunya permintaan yang diizinkan untuk memiliki header "X-Privet-Token" kosong adalah permintaan /privet/info (perhatikan bahwa header tersebut HARUS tetap ada). Jika header "X-Privet-Token" tidak ada, perangkat HARUS merespons dengan error HTTP 400 berikut:

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

Jika header "X-Privet-Token" kosong atau tidak valid, perangkat HARUS merespons dengan "error X-Privet-Token tidak valid" (invalid_x_privet_token, lihat bagian Error untuk detailnya). Satu-satunya pengecualian adalah /info API. Untuk melihat info selengkapnya tentang alasan hal ini dilakukan dan cara membuat token, lihat Lampiran A: Serangan dan pencegahan XSSI dan XSRF.

Jika API yang diminta tidak ada atau tidak didukung, perangkat HARUS menampilkan error HTTP 404.

4.1. Ketersediaan API

Sebelum API APA PUN diekspos (termasuk /info API), perangkat HARUS menghubungi server untuk memeriksa setelan lokal. Setelan lokal HARUS dipertahankan di antara mulai ulang. Jika server tidak tersedia, setelan lokal terakhir yang diketahui harus digunakan. Jika perangkat belum didaftarkan, perangkat akan mengikuti setelan default.

Perangkat Cloud Print HARUS mengikuti langkah-langkah di bawah ini untuk mendaftar, menerima, dan memperbarui setelan lokal.

4.1.1. Pendaftaran

Saat mendaftarkan diri, perangkat HARUS menentukan parameter "local_settings", sebagai berikut:

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

Setelan berikut dapat ditetapkan:

Nama Nilai	Jenis Nilai	Deskripsi
local_discovery	boolean	Menunjukkan apakah fungsi penemuan lokal diizinkan. Jika "false", semua API lokal (termasuk /info) dan penemuan DNS-SD harus dinonaktifkan. Secara default, perangkat yang baru didaftarkan harus meneruskan "true".
access_token_enabled	boolean (opsional)	Menunjukkan apakah API /accesstoken harus diekspos di jaringan lokal. Secara default harus "benar".
printer/local_printing_enabled	boolean (opsional)	Menunjukkan apakah fungsi pencetakan lokal (/printer/createjob, /printer/submitdoc, /printer/jobstate) harus diekspos di jaringan lokal. Secara default harus "benar".
printer/conversion_printing_enabled	boolean (opsional)	Menunjukkan apakah pencetakan lokal dapat mengirimkan tugas ke server untuk konversi. Hanya masuk akal jika pencetakan lokal diaktifkan.
xmpp_timeout_value	int (opsional)	Menunjukkan jumlah detik antara ping channel XMPP. Secara default HARUS 300 (5 menit) atau lebih.

Penting: Tidak adanya nilai opsional menunjukkan bahwa fungsi yang sesuai tidak didukung sepenuhnya oleh perangkat.

4.1.2. Startup

Saat perangkat dimulai, perangkat harus menghubungi server untuk memeriksa API apa yang tersedia untuk diekspos di jaringan lokal. Untuk printer yang terhubung ke Cloud Print, printer tersebut harus memanggil:

/cloudprint/printer?printerid=<printer_id>

atau

/cloudprint/list

/cloudprint/printer lebih disukai daripada /cloudprint/list, tetapi keduanya akan berfungsi.

API ini menampilkan parameter perangkat saat ini, termasuk setelan untuk API lokal. Balasan dari server akan memiliki format berikut:

"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
         }
}

Objek "current" menunjukkan setelan yang berlaku saat ini.

Objek "pending" menunjukkan setelan yang harus diterapkan ke perangkat (objek ini mungkin tidak ada).

Setelah melihat setelan "tertunda", perangkat HARUS memperbarui statusnya (lihat di bawah).

4.1.3. Perbarui

Jika pembaruan setelan diperlukan, notifikasi XMPP akan dikirim ke perangkat. Notifikasi akan menggunakan format berikut:

<device_id>/update_settings

Saat menerima notifikasi tersebut, perangkat HARUS mengirimkan kueri ke server untuk mendapatkan setelan terbaru. Perangkat Cloud Print HARUS menggunakan:

/cloudprint/printer?printerid=<printer_id>

Setelah melihat bagian "tertunda" sebagai hasil dari API /cloudprint/printer (saat startup atau karena notifikasi), perangkat HARUS memperbarui status internalnya untuk mengingat setelan baru. Harus memanggil API server untuk mengonfirmasi setelan baru. Untuk Printer Cloud, perangkat HARUS memanggil API /cloudprint/update dan menggunakan parameter "local_settings" seperti saat pendaftaran.

Saat terhubung kembali ke saluran XMPP, perangkat HARUS memanggil API /cloudprint/printer untuk memeriksa apakah setelan lokal telah berubah sejak terakhir kali.

4.1.3.1. Setelan Lokal Tertunda

Parameter "local_settings" yang digunakan perangkat untuk memanggil server API TIDAK BOLEH berisi bagian "pending".

4.1.3.2. Setelan Lokal Saat Ini

HANYA perangkat yang dapat mengubah bagian "current" dari "local_settings". Semua orang akan mengubah bagian "tertunda", dan menunggu hingga perubahan disebarkan ke bagian "saat ini" oleh perangkat.

4.1.4. Offline

Jika tidak dapat menghubungi server selama proses startup, setelah notifikasi, perangkat HARUS menggunakan setelan lokal terakhir yang diketahui.

4.1.5. Menghapus perangkat dari layanan

Jika perangkat telah dihapus dari layanan (misalnya, GCP), notifikasi XMPP akan dikirim ke perangkat. Notifikasi akan menggunakan format berikut:

<device_id>/delete

Setelah menerima notifikasi tersebut, perangkat HARUS membuka server untuk memeriksa statusnya. Cloud Perangkat cetak HARUS menggunakan:

/cloudprint/printer?printerid=<printer_id>

Perangkat HARUS menerima jawaban HTTP yang berhasil dengan success=false dan tanpa deskripsi perangkat/printer. Artinya, perangkat telah dihapus dari server, dan perangkat HARUS menghapus kredensialnya dan beralih ke mode setelan pabrik default.

SETIAP kali perangkat menerima respons yang menunjukkan bahwa perangkat telah dihapus sebagai akibat dari API /cloudprint/printer (startup, notifikasi update setelan, ping harian), perangkat HARUS menghapus kredensialnya dan beralih ke mode default.

4.2. /privet/info API

API info bersifat WAJIB dan HARUS diterapkan oleh setiap perangkat. Ini adalah permintaan HTTP GET untuk URL "/privet/info": GET /privet/info HTTP/1.1

Info API menampilkan informasi dasar tentang perangkat dan fungsi yang didukungnya. API ini TIDAK BOLEH mengubah status perangkat atau melakukan tindakan apa pun, karena rentan terhadap serangan XSRF. Ini adalah SATU-SATUNYA API yang diizinkan memiliki header "X-Privet-Token" kosong. Klien harus memanggil API /privet/info dengan header "X-Privet-Token" yang ditetapkan ke X-Privet-Token: ""

Info API HARUS menampilkan data yang konsisten dengan data yang tersedia dalam catatan TXT selama penemuan.

4.2.1. Input

API /privet/info tidak memiliki parameter input.

4.2.2. Pulang pergi

API /privet/info menampilkan informasi dasar tentang perangkat dan fungsi yang didukung.

Kolom TXT menunjukkan kolom yang sesuai dalam data TXT DNS-SD.

Nama Nilai	Jenis Nilai	Deskripsi	TXT
versi	string	Versi tertinggi (major.minor) API yang didukung, saat ini 1.0
nama	string	Nama perangkat yang dapat dibaca manusia.	ty
deskripsi	string	(opsional) Deskripsi perangkat. HARUS dapat dimodifikasi oleh pengguna.	catatan
url	string	URL server yang digunakan perangkat ini untuk berkomunikasi. URL HARUS menyertakan spesifikasi protokol, misalnya: https://www.google.com/cloudprint.	url
jenis	daftar string	Daftar jenis perangkat yang didukung.	jenis
id	string	ID perangkat, kosong jika perangkat belum terdaftar.	id
device_state	string	Status perangkat. idle berarti perangkat siap processing berarti perangkat sedang sibuk dan fungsionalitasnya mungkin terbatas untuk beberapa waktu stopped berarti perangkat tidak berfungsi dan intervensi pengguna diperlukan
connection_state	string	Status koneksi ke server (base_url) online - koneksi tersedia offline - tidak ada koneksi connecting - sedang melakukan langkah-langkah startup not-configured - koneksi belum dikonfigurasi Perangkat terdaftar dapat melaporkan status koneksinya berdasarkan status channel notifikasi (misalnya, status koneksi XMPP).	cs
produsen	string	Nama produsen perangkat
model	string	Model perangkat
serial_number	string	ID perangkat unik. Dalam spesifikasi ini, nilai ini HARUS berupa UUID. (Spesifikasi GCP 1.1) (opsional) Sebaiknya gunakan ID nomor seri yang sama di mana pun, sehingga klien yang berbeda dapat mengidentifikasi perangkat yang sama. Misalnya, printer yang menerapkan IPP dapat menggunakan ID nomor seri ini di kolom "printer-device-id".
firmware	string	Versi firmware perangkat
waktu beroperasi	int	Jumlah detik sejak perangkat di-boot.
setup_url	string	(opsional) URL (termasuk protokol) halaman dengan petunjuk penyiapan
support_url	string	(opsional) URL (termasuk protokol) halaman dengan dukungan, informasi FAQ
update_url	string	(opsional) URL (termasuk protokol) halaman dengan petunjuk update firmware
x-privet-token	string	Nilai header X-Privet-Token yang harus diteruskan ke semua API untuk mencegah serangan XSSI dan XSRF. Lihat 6.1 untuk mengetahui detailnya.
api	Deskripsi API	Daftar API yang didukung (dijelaskan di bawah)
semantic_state	JSON	(opsional) Status semantik perangkat dalam format CloudDeviceState.

api - adalah daftar JSON yang berisi daftar API yang tersedia melalui jaringan lokal. Perhatikan bahwa tidak semua API mungkin tersedia secara bersamaan melalui jaringan lokal. Misalnya, perangkat yang baru terhubung hanya boleh mendukung API /register:

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

Setelah pendaftaran perangkat selesai, perangkat SEBAIKNYA berhenti mendukung /register API. Perangkat juga harus memeriksa dengan layanan untuk menyediakan API apa yang dapat diekspos melalui jaringan lokal. Contoh:

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

API berikut tersedia saat ini:

/privet/register - API untuk pendaftaran perangkat melalui jaringan lokal. (lihat API /privet/register untuk mengetahui detailnya). API ini HARUS disembunyikan setelah perangkat berhasil didaftarkan di cloud.
/privet/accesstoken - API untuk meminta token akses dari perangkat (lihat /privet/accesstoken API untuk mengetahui detailnya).
/privet/capabilities - API untuk mengambil kemampuan perangkat (lihat API /privet/capabilities untuk mengetahui detailnya).
/privet/printer/* - API khusus untuk jenis perangkat "printer", lihat printer spesifik API untuk mengetahui detailnya.

Berikut adalah contoh respons /privet/info. (Perhatikan tidak adanya API /privet/register, karena ini adalah perangkat yang sudah terdaftar):

{
        "version": "1.0",
        "name": "Gene’s printer",
        "description": "Printer connected through Chrome connector",
        "url": "https://www.google.com/cloudprint",
        "type": [
                "printer"
        ],
        "id": "11111111-2222-3333-4444-555555555555",
        "device_state": "idle",
        "connection_state": "online",
        "manufacturer": "Google",
        "model": "Google Chrome",
        "serial_number": "1111-22222-33333-4444",
        "firmware": "24.0.1312.52",
        "uptime": 600,
        "setup_url": "http://support.google.com/cloudprint/answer/1686197/?hl=en",
        "support_url": "http://support.google.com/cloudprint/?hl=en",
        "update_url": "http://support.google.com/cloudprint/?hl=en",
        "x-privet-token": "AIp06DjQd80yMoGYuGmT_VDAApuBZbInsQ:1358377509659",
        "api": [
                "/privet/accesstoken",
                "/privet/capabilities",
                "/privet/printer/submitdoc",
        ]
}

Berikut adalah contoh respons /privet/info untuk printer yang kehabisan tinta (perhatikan kolom semantic_state):

{
        "version": "1.0",
        "name": "Gene’s printer",
        "description": "Printer connected through Chrome connector",
        "url": "https://www.google.com/cloudprint",
        "type": [
                "printer"
        ],
        "id": "11111111-2222-3333-4444-555555555555",
        "device_state": "stopped",
        "connection_state": "online",
        "manufacturer": "Google",
        "model": "Google Chrome",
        "serial_number": "1111-22222-33333-4444",
        "firmware": "24.0.1312.52",
        "uptime": 600,
        "setup_url": "http://support.google.com/cloudprint/answer/1686197/?hl=en",
        "support_url": "http://support.google.com/cloudprint/?hl=en",
        "update_url": "http://support.google.com/cloudprint/?hl=en",
        "x-privet-token": "AIp06DjQd80yMoGYuGmT_VDAApuBZbInsQ:1358377509659",
        "api": [
                "/privet/accesstoken",
                "/privet/capabilities",
                "/privet/printer/submitdoc",
        ],
        "semantic_state": {
                "version": "1.0",
                "printer": {
                        "state": "STOPPED",
                        "marker_state": {
                                "item": [
                                        {
                                                "vendor_id": "ink",
                                                "state": "EXHAUSTED",
                                                "level_percent": 0
                                        }
                                ]
                        }
                }
        }
}

4.2.3. Error

API /privet/info HANYA akan menampilkan error jika header X-Privet-Token tidak ada. HARUS berupa error HTTP 400:

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

4.3. /privet/register API

/privet/register API bersifat OPSIONAL. Ini adalah permintaan POST HTTP. /privet/register API HARUS memeriksa header X-Privet-Token yang valid. Perangkat HARUS menerapkan API ini di URL "/privet/register":

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

Perangkat harus mengekspos /privet/register API HANYA jika mengizinkan pendaftaran anonim saat ini. Contoh:

Saat perangkat diaktifkan (atau setelah mengklik tombol khusus di perangkat) dan belum terdaftar, perangkat harus mengekspos /privet/register API untuk memungkinkan pengguna dari jaringan lokal mengklaim printer.
Setelah pendaftaran selesai, perangkat akan berhenti mengekspos API /privet/register untuk mencegah pengguna lain di jaringan lokal mengklaim kembali perangkat.
Beberapa perangkat mungkin memiliki cara yang berbeda untuk mendaftarkan perangkat dan tidak boleh mengekspos API /privet/register sama sekali (misalnya, konektor Chrome Cloud Print).

Proses pendaftaran terdiri dari 3 langkah (lihat pendaftaran anonim untuk Cloud Print).

Memulai proses pendaftaran anonim.
Klien memulai proses ini dengan memanggil API /privet/register. Perangkat dapat menunggu konfirmasi pengguna pada saat itu.
Dapatkan token klaim.

Klien melakukan polling untuk mengetahui kapan perangkat siap melanjutkan. Setelah perangkat siap, perangkat mengirim permintaan ke server untuk mengambil token pendaftaran dan URL pendaftaran. Token dan URL yang diterima HARUS ditampilkan kepada klien. Selama langkah ini, jika perangkat menerima panggilan lain untuk menginisialisasi pendaftaran, perangkat harus:

Jika ini adalah pengguna yang sama yang memulai pendaftaran - hapus semua data sebelumnya (jika ada) dan mulai proses pendaftaran baru.
Jika pengguna ini berbeda - menampilkan error device_busy dan waktu tunggu 30 detik.

Selesaikan proses pendaftaran.

Setelah mengklaim perangkat, klien harus memberi tahu perangkat untuk menyelesaikan pendaftaran. Setelah proses pendaftaran selesai, perangkat harus mengirimkan pengumuman pembaruan, termasuk ID perangkat yang baru didapatkan.

Catatan: Saat perangkat memproses panggilan API /privet/register, tidak ada panggilan API /privet/register lain yang dapat diproses secara bersamaan. Perangkat HARUS menampilkan error device_busy dan waktu tunggu 30 detik.

Konfirmasi pengguna untuk pendaftaran di perangkat SANGAT disarankan. Jika diterapkan, perangkat HARUS menunggu konfirmasi pengguna SETELAH menerima panggilan API /privet/register?action=start. Klien akan memanggil API /privet/register?action=getClaimToken untuk mengetahui kapan konfirmasi pengguna selesai dan token klaim tersedia. Jika pengguna membatalkan pendaftaran di perangkat (misalnya, menekan tombol Batal), error user_cancel HARUS ditampilkan. Jika pengguna belum mengonfirmasi pendaftaran dalam jangka waktu tertentu, error confirmation_timeout HARUS ditampilkan. Lihat bagian default untuk mengetahui detail selengkapnya.

4.3.1. Input

API /privet/register memiliki parameter input berikut:

Nama	Nilai
action	Dapat berupa salah satu dari berikut ini: start - untuk memulai proses pendaftaran getClaimToken - mengambil token klaim untuk perangkat cancel - untuk membatalkan proses pendaftaran complete - untuk menyelesaikan proses pendaftaran
pengguna	Email pengguna yang akan mengklaim perangkat ini.

Perangkat HARUS memeriksa apakah alamat email dari semua tindakan (start, getClaimToken, cancel, complete) cocok.

4.3.2. Pulang pergi

/privet/register API menampilkan data berikut:

Nama nilai	Jenis nilai	Deskripsi
action	string	Tindakan yang sama seperti di parameter input.
pengguna	string (opsional)	Pengguna yang sama seperti di parameter input (mungkin tidak ada, jika tidak ada di input).
token	string (opsional)	Token pendaftaran (wajib untuk respons "getClaimToken", tidak ada untuk "start", "complete", "cancel").
claim_url	string (opsional)	URL pendaftaran (wajib untuk respons "getClaimToken", tidak ada untuk "start", "complete", "cancel"). Untuk Printer Cloud, URL ini harus berupa "complete_invite_url" yang diterima dari server.
automated_claim_url	string (opsional)	URL pendaftaran (wajib untuk respons "getClaimToken", tidak ada untuk "start", "complete", "cancel"). Untuk Printer Cloud, nilai ini harus berupa "automated_invite_url" yang diterima dari server.
device_id	string (opsional)	ID perangkat baru (dihapus untuk respons "start", wajib untuk "complete").

Perangkat HARUS menampilkan ID perangkatnya dalam respons API /privet/info HANYA setelah pendaftaran selesai.

Contoh 1:

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

Contoh 2:

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

Contoh 3:

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

4.3.3. Error

API /privet/register dapat menampilkan error berikut (lihat bagian Error untuk mengetahui detailnya):

Error	Deskripsi
device_busy	Perangkat sedang sibuk dan tidak dapat melakukan tindakan yang diminta. Coba lagi setelah waktu tunggu habis.
pending_user_action	Sebagai respons terhadap "getClaimToken", error ini menunjukkan bahwa perangkat masih menunggu konfirmasi pengguna, dan permintaan "getClaimToken" harus dicoba lagi setelah waktu tunggu habis.
user_cancel	Pengguna secara eksplisit membatalkan proses pendaftaran dari perangkat.
confirmation_timeout	Konfirmasi pengguna kehabisan waktu.
invalid_action	Tindakan tidak valid dipanggil. Misalnya, jika klien memanggil action=complete sebelum memanggil action=start dan action=getClaimToken.
invalid_params	Parameter tidak valid yang ditentukan dalam permintaan. (Parameter yang tidak diketahui harus diabaikan dengan aman untuk kompatibilitas pada masa mendatang). Misalnya, tampilkan ini jika klien memanggil action=unknown atau user=.
device_config_error	Tanggal/Waktu (atau beberapa setelan lainnya) salah di sisi perangkat. Pengguna harus membuka (situs internal perangkat) dan mengonfigurasi setelan perangkat.
offline	Perangkat saat ini offline dan tidak dapat berkomunikasi dengan server.
server_error	Terjadi error server selama proses pendaftaran.
invalid_x_privet_token	X-Privet-Token tidak valid atau kosong dalam permintaan.

Perangkat HARUS berhenti mengekspos API /privet/register setelah pendaftaran berhasil diselesaikan. Jika perangkat tidak mengekspos API /privet/register, perangkat HARUS menampilkan error HTTP 404. Oleh karena itu, jika perangkat sudah terdaftar, pemanggilan API ini HARUS menampilkan 404. Jika header X-Privet-Token tidak ada, perangkat HARUS menampilkan error HTTP 400.

4.4. /privet/accesstoken API

API /privet/accesstoken bersifat OPSIONAL. Ini adalah permintaan HTTP GET. /privet/accesstoken API HARUS memeriksa header "X-Privet-Token" yang valid. Perangkat HARUS menerapkan API ini di URL "/privet/accesstoken":

GET /privet/accesstoken HTTP/1.1

Saat menerima panggilan API /accesstoken, perangkat harus memanggil server untuk mengambil token akses untuk pengguna tertentu dan menampilkan token ke klien. Klien kemudian akan menggunakan token akses untuk mengakses perangkat ini melalui cloud.

Perangkat Cloud Print HARUS memanggil API berikut:

/cloudprint/proximitytoken

dan teruskan parameter "printerid=<printer_id>" dan "user" dari API lokal. Jika berhasil, respons server akan berisi objek berikut:

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

Perangkat Cloud Print HARUS meneruskan nilai objek "proximity_token" dalam respons ke panggilan API local /privet/accesstoken. Akan lebih menguntungkan (siap untuk masa depan) jika perangkat dapat meneruskan SEMUA parameter (termasuk yang tidak dijelaskan dalam spesifikasi ini).

4.4.1. Input

API /privet/accesstoken memiliki parameter input berikut:

Nama	Nilai
pengguna	Email pengguna yang ingin menggunakan token akses ini. Mungkin kosong dalam permintaan.

4.4.2. Pulang pergi

API /privet/accesstoken menampilkan data berikut:

Nama nilai	Jenis nilai	Deskripsi
token	string	Token akses yang ditampilkan oleh server
pengguna	string	Pengguna yang sama seperti di parameter input.
expires_in	int	Jumlah detik hingga masa berlaku token ini berakhir. Diterima dari server dan diteruskan dalam respons ini.

Contoh:

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

4.4.3. Error

API /privet/accesstoken dapat menampilkan error berikut (lihat bagian Error untuk mengetahui detailnya):

Error	Deskripsi
offline	Perangkat saat ini sedang offline dan tidak dapat berkomunikasi dengan server.
access_denied	Hak tidak memadai. Akses ditolak. Perangkat harus menampilkan error ini jika permintaan telah ditolak secara eksplisit oleh server.
invalid_params	Parameter tidak valid yang ditentukan dalam permintaan. (Parameter yang tidak diketahui harus diabaikan dengan aman untuk kompatibilitas pada masa mendatang). Misalnya, jika klien memanggil /accesstoken?user= atau /accesstoken.
server_error	Error server.
invalid_x_privet_token	X-Privet-Token tidak valid atau kosong dalam permintaan.

Jika perangkat tidak mengekspos API /privet/accesstoken, perangkat HARUS menampilkan error HTTP 404. Jika header X-Privet-Token tidak ada, perangkat HARUS menampilkan error HTTP 400.

4.5. /privet/capabilities API

API /privet/capabilities bersifat OPSIONAL. Ini adalah permintaan HTTP GET. API /privet/capabilities HARUS memeriksa header "X-Privet-Token" yang valid. Perangkat HARUS menerapkan API ini di URL "/privet/capabilities":

GET /privet/capabilities HTTP/1.1

Saat perangkat menerima panggilan API /capabilities, jika perangkat mampu, perangkat HARUS menghubungi server untuk mendapatkan kemampuan yang diupdate. Misalnya, jika printer mendukung posting tugas cetak (diterima secara lokal) ke dirinya sendiri melalui layanan Cloud Print, printer tersebut harus menampilkan kemampuan yang akan ditampilkan oleh layanan Cloud Print. Dalam hal ini, Cloud Print dapat mengubah kemampuan printer asli dengan menambahkan fitur baru yang dapat dilakukan sebelum mengirimkan tugas ke printer. Kasus yang paling umum adalah daftar jenis dokumen yang didukung. Jika printer offline, printer harus menampilkan jenis dokumen yang didukungnya. Namun, jika printer sedang online dan terdaftar di Cloud Print, printer tersebut HARUS menampilkan "*/*" sebagai salah satu jenis yang didukung. Layanan Cloud Print akan melakukan konversi yang diperlukan dalam kasus ini. Untuk pencetakan offline, printer HARUS mendukung setidaknya format "image/pwg-raster".

4.5.1. Input

API /privet/capabilities memiliki parameter input berikut:

Nama	Nilai
offline	(opsional) Hanya dapat berupa "offline=1". Dalam hal ini, perangkat harus menampilkan kemampuan untuk penggunaan offline (jika berbeda dengan kemampuan "online").

4.5.2. Pulang pergi

API /privet/capabilities menampilkan kemampuan perangkat dalam format JSON Cloud Device Description (CDD) (lihat dokumen CDD untuk mengetahui detailnya). Printer minimal HARUS menampilkan daftar jenis yang didukung di sini. Misalnya, printer Cloud Ready yang saat ini online dapat menampilkan sesuatu seperti ini (setidaknya):

{
        "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": "*/*" }
                ]
        }
}

dan saat koneksi terputus dari server, respons yang mungkin ditampilkan adalah:

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

Catatan: Printer menyatakan prioritas jenis konten yang didukung menggunakan urutan. Misalnya, dalam contoh di atas, printer menentukan bahwa printer lebih memilih data "application/pdf" daripada "image/pwg-raster" dan "image/jpeg". Klien harus mematuhi prioritas printer jika memungkinkan (lihat dokumen CDD untuk mengetahui detailnya).

4.5.3. Error

API /privet/capabilities dapat menampilkan error berikut (lihat bagian Error untuk mengetahui detailnya):

Error	Deskripsi
invalid_x_privet_token	X-Privet-Token tidak valid atau kosong dalam permintaan.

Jika perangkat tidak mengekspos API /privet/capabilities, perangkat HARUS menampilkan error HTTP 404. Jika header X-Privet-Token tidak ada, perangkat HARUS menampilkan error HTTP 400.

4.6. Error

Error ditampilkan dari API di atas dalam format berikut:

Nama nilai	Jenis nilai	Deskripsi
error	string	Jenis error (ditentukan per API)
deskripsi	string (opsional)	Deskripsi error yang dapat dibaca manusia.
server_api	string (opsional)	Jika terjadi error server, kolom ini berisi API server yang gagal.
server_code	int (opsional)	Jika terjadi error server, kolom ini berisi kode error yang ditampilkan server.
server_http_code	int (opsional)	Jika terjadi error HTTP server, kolom ini berisi kode error HTTP yang ditampilkan server.
timeout	int (opsional)	Jumlah detik yang harus ditunggu klien sebelum mencoba lagi (hanya untuk error yang dapat dipulihkan). Klien HARUS mengacak waktu tunggu sebenarnya dari nilai ini ke nilai yang + 20%.

Semua API HARUS menampilkan error HTTP 400 jika header X-Privet-Token tidak ada.

HTTP/1.1 400 Header X-Privet-Token tidak ada.

Contoh 1:

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

Contoh 2:

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

5. Printer API

Salah satu jenis perangkat yang didukung oleh protokol ini adalah printer jenis. Perangkat yang mendukung jenis ini DAPAT menerapkan beberapa fungsi khusus untuk printer. Idealnya, pencetakan ke printer cloud-ready akan dilakukan melalui server Cloud Print:

Dalam beberapa kasus, klien mungkin perlu mengirim dokumen secara lokal. Hal ini mungkin diperlukan saat klien tidak memiliki ID Google atau tidak dapat berkomunikasi dengan server Cloud Print. Dalam kasus tersebut, tugas cetak akan dikirimkan secara lokal ke printer. Selanjutnya, printer akan menggunakan layanan Cloud Print untuk pengantrean dan konversi tugas. Printer akan memposting ulang tugas yang dikirimkan secara lokal ke layanan Cloud Print, lalu memintanya, karena tugas tersebut dikirimkan melalui cloud. Proses ini akan memberikan pengalaman pengguna yang fleksibel dalam hal layanan (konversi) dan pengelolaan/pelacakan tugas cetak.

Karena layanan Cloud Print menerapkan konversi, printer HARUS mengiklankan dukungan semua format input ("*/*") di antara daftar jenis konten yang didukung:

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

Dalam beberapa kasus, solusi yang sepenuhnya offline lebih diinginkan. Karena printer mendukung sejumlah format input yang terbatas, klien harus mengonversi dokumen ke beberapa format printer yang didukung secara native.

Spesifikasi ini MENGHARUSKAN semua printer mendukung setidaknya format PWG Raster ("image/pwg-raster") untuk kasus pencetakan offline. Printer dapat mendukung format lain (misalnya JPEG) dan jika klien mendukungnya, printer dapat mengirim dokumen dalam format tersebut. Printer HARUS mengekspos jenis yang didukung melalui API /capabilities, misalnya:

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

Ada dua cara klien dapat memulai pencetakan melalui jaringan lokal.

Pencetakan sederhana - klien mengirim dokumen melalui jaringan lokal ke /submitdoc API (tanpa menentukan parameter job_id). Dokumen yang dikirimkan akan dicetak menggunakan setelan tiket cetak default dan tidak diperlukan status tugas cetak. Jika printer HANYA mendukung jenis pencetakan ini, printer tersebut HANYA boleh mengiklankan API /submitdoc di respons API /privet/info.

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

Pencetakan lanjutan - klien harus membuat tugas cetak terlebih dahulu di printer dengan memanggil API /privet/printer/createjob dengan tiket tugas CJT yang valid dalam permintaan. Printer HARUS menyimpan tiket cetak dalam memori dan menampilkan job_id kembali ke klien. Kemudian, klien akan memanggil API /printer/submitdoc dan menentukan job_id yang diterima sebelumnya. Pada saat itu printer akan mulai mencetak. Klien akan melakukan polling pada printer untuk mengetahui status tugas cetak dengan memanggil API /privet/printer/jobstate.

Dalam lingkungan multiklien, tidak ada jaminan bagaimana API ini dipanggil. Satu klien dapat memanggil /createjob di antara panggilan /createjob->/submitdoc klien lain. Untuk menghilangkan kemungkinan kebuntuan dan meningkatkan kegunaan, sebaiknya siapkan antrean kecil tugas cetak yang tertunda di printer (minimal 3-5):

/createjob mengambil tempat pertama yang tersedia dalam antrean.
Masa aktif tugas (dalam antrean) minimal 5 menit.
Jika semua tempat dalam antrean sudah terisi, tugas non-pencetakan yang paling lama akan dihapus dan tugas baru akan ditempatkan di sana.
Jika ada pekerjaan cetak yang sedang dicetak di perangkat (pencetakan sederhana atau lanjutan), /submitdoc harus menampilkan status sibuk dan menyarankan waktu tunggu untuk mencoba lagi pekerjaan cetak ini.
Jika /submitdoc merujuk ke tugas yang telah dihapus dari antrean (karena penggantian atau waktu tunggu habis), printer harus menampilkan error invalid_print_job dan klien akan mencoba lagi proses dari langkah /createjob. Klien HARUS menunggu periode waktu tunggu acak hingga 5 detik sebelum mencoba lagi.

Jika batasan memori mencegah penyimpanan beberapa pekerjaan tertunda di perangkat, antrean dapat memiliki panjang 1 pekerjaan cetak. Perangkat ini tetap akan mengikuti protokol yang sama seperti di atas. Setelah tugas selesai atau gagal karena error, printer harus menyimpan informasi tentang status tugas selama minimal 5 menit. Ukuran antrean untuk menyimpan status pekerjaan yang selesai harus minimal 10. Jika ada lebih banyak status tugas yang perlu disimpan, status tugas terlama dapat dihapus dari antrean sebelum waktu tunggu 5 menit.

Catatan: Untuk saat ini, klien akan melakukan polling untuk status tugas. Di masa mendatang, kami mungkin mewajibkan printer mengirimkan notifikasi DNS TXT saat status pekerjaan cetak APA PUN telah berubah.

5.1. /privet/printer/createjob API

API /privet/printer/createjob bersifat OPSIONAL (lihat Pencetakan Sederhana di atas). Ini adalah permintaan HTTP POST. API /privet/printer/createjob HARUS memeriksa header "X-Privet-Token" yang valid. Perangkat HARUS menerapkan API ini di URL "/privet/printer/createjob":

POST /privet/printer/createjob HTTP/1.1

Saat menerima panggilan API /privet/printer/createjob, printer HARUS membuat ID tugas cetak baru, menyimpan tiket cetak yang diterima dalam format CJT, dan menampilkan ID tugas cetak kembali ke klien.

5.1.1. Input

API /privet/printer/createjob tidak memiliki parameter input di URL. Isi permintaan harus berisi data tiket tugas cetak dalam format CJT.

5.1.2. Pulang pergi

API /privet/printer/createjob menampilkan data berikut:

Nama nilai	Jenis nilai	Deskripsi
job_id	string	ID tugas cetak yang baru dibuat.
expires_in	int	Jumlah detik tugas cetak ini valid.

Contoh:

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

5.1.3. Error

/privet/printer/createjob API dapat menampilkan error berikut (lihat bagian Error untuk mengetahui detailnya):

Error	Deskripsi
invalid_ticket	Tiket cetak yang dikirimkan tidak valid.
printer_busy	Printer sedang sibuk dan saat ini tidak dapat memproses /membuat tugas. Coba lagi setelah waktu tunggu habis.
printer_error	Printer dalam status error dan memerlukan interaksi pengguna untuk memperbaikinya. Deskripsi harus berisi penjelasan yang lebih mendetail (misalnya, "Kertas macet di Baki 1").
invalid_x_privet_token	X-Privet-Token tidak valid atau kosong dalam permintaan.

Jika perangkat tidak mengekspos /privet/printer/createjob, perangkat HARUS menampilkan error HTTP 404. Jika header X-Privet-Token tidak ada, perangkat HARUS menampilkan error HTTP 400.

5.2. /privet/printer/submitdoc API

API /privet/printer/submitdoc WAJIB diterapkan untuk mencetak melalui jaringan lokal (offline atau diposting ulang ke Cloud Print). Ini adalah permintaan POST HTTP. /privet/printer/submitdoc API HARUS memeriksa header "X-Privet-Token" yang valid. Perangkat HARUS menerapkan API ini di URL "/privet/printer/submitdoc":

POST /privet/printer/submitdoc HTTP/1.1

Saat menerima panggilan API /privet/printer/submitdoc, printer harus mulai mencetak. Jika tidak dapat memulai pencetakan, printer HARUS menampilkan error printer_busy dan jangka waktu tunggu yang direkomendasikan agar klien menunggu sebelum mencoba lagi.

Jika printer tidak dapat menyimpan semua data dalam buffer internalnya, printer HARUS menggunakan mekanisme TCP untuk memperlambat transfer data hingga mencetak sebagian dokumen, sehingga sebagian buffer tersedia kembali. (Misalnya, printer dapat menyetel windowsize=0 di lapisan TCP, yang akan membuat klien menunggu.)

Mengirimkan dokumen ke printer dapat memerlukan waktu yang cukup lama. Klien harus dapat memeriksa status printer dan tugas (pencetakan lanjutan) saat pencetakan sedang berlangsung. Untuk melakukannya, printer HARUS mengizinkan klien memanggil API /privet/info dan /privet/printer/jobstate saat memproses panggilan API /privet/printer/submitdoc. Semua klien sebaiknya memulai thread baru untuk mengeksekusi panggilan API /privet/printer/submitdoc, sehingga thread utama dapat menggunakan API /privet/info dan /privet/printer/jobstate untuk memeriksa status printer dan tugas.

Catatan: Setelah penyelesaian atau pembatalan tugas cetak lokal, sangat direkomendasikan (dan akan diwajibkan dalam versi spesifikasi ini di masa mendatang) untuk melaporkan status akhir tugas ke antarmuka /cloudprint/submit untuk tujuan akuntansi dan pengalaman pengguna. Parameter "printerid", "title", "contentType", dan "final_semantic_state" (dalam format PrintJobState) diperlukan, dan parameter "tag" (parameter berulang) dan "ticket" (tiket tugas dalam format CloudJobTicket). Perhatikan bahwa PrintJobState yang diberikan harus benar-benar final, yaitu jenisnya harus DONE atau ABORTED, dan penyebab harus diberikan jika statusnya ABORTED (lihat JobState untuk mengetahui detailnya). Perhatikan juga bahwa penggunaan antarmuka /cloudprint/submit ini untuk melaporkan tugas cetak lokal tidak disebutkan dalam spesifikasinya karena bagian tersebut dimaksudkan untuk menjelaskan penggunaan utama antarmuka: mengirimkan tugas cetak dengan dokumen yang akan dicetak yang diberikan dalam parameter "content".

5.2.1. Input

API /privet/printer/submitdoc memiliki parameter input berikut:

Nama	Nilai
job_id	(opsional) ID tugas cetak. Dapat dihilangkan untuk kasus pencetakan sederhana (lihat di atas). Harus cocok dengan yang ditampilkan oleh printer.
user_name	(opsional) Nama pengguna yang dapat dibaca manusia. Hal ini tidak pasti, dan hanya boleh digunakan untuk anotasi pekerjaan cetak. Jika tugas diposting ulang ke layanan Cloud Print, string ini harus dilampirkan ke tugas Cloud Print.
client_name	(opsional) Nama aplikasi klien yang membuat permintaan ini. Hanya untuk tujuan tampilan. Jika tugas diposting ulang ke layanan Cloud Print, string ini harus dilampirkan ke tugas Cloud Print.
job_name	(opsional) Nama tugas cetak yang akan direkam. Jika tugas diposting ulang ke layanan Cloud Print, string ini harus dilampirkan ke tugas Cloud Print.
offline	(opsional) Hanya dapat berupa "offline=1". Dalam hal ini, printer hanya boleh mencoba mencetak secara offline (tidak memposting ulang ke server Cloud Print).

Isi permintaan harus berisi dokumen yang valid untuk dicetak. "Content-Length" harus mencakup panjang permintaan yang benar. Header "Content-Type" harus disetel ke jenis MIME dokumen dan cocok dengan salah satu jenis di CDD (kecuali jika CDD menentukan "*/*").

Klien SANGAT DISARANKAN untuk memberikan nama pengguna (atau email) yang valid, nama klien, dan nama pekerjaan dengan permintaan ini. Kolom tersebut hanya digunakan di UI untuk meningkatkan pengalaman pengguna.

5.2.2. Pulang pergi

API /privet/printer/submitdoc menampilkan data berikut:

Nama nilai	Jenis nilai	Deskripsi
job_id	string	ID tugas cetak yang baru dibuat (pencetakan sederhana) atau job_id yang ditentukan dalam permintaan (pencetakan lanjutan).
expires_in	int	Jumlah detik tugas cetak ini valid.
job_type	string	Jenis konten dokumen yang dikirimkan.
job_size	int 64 bit	Ukuran data cetak dalam byte.
job_name	string	(opsional) Nama tugas yang sama seperti di input (jika ada).

Contoh:

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

5.2.3. Error

/privet/printer/submitdoc API dapat menampilkan error berikut (lihat bagian Error untuk mengetahui detailnya):

Error	Deskripsi
invalid_print_job	ID tugas yang tidak valid/telah berakhir ditentukan dalam permintaan. Coba lagi setelah waktu tunggu habis.
invalid_document_type	Jenis MIME dokumen tidak didukung oleh printer.
invalid_document	Dokumen yang dikirimkan tidak valid.
document_too_large	Dokumen melebihi ukuran maksimum yang diizinkan.
printer_busy	Printer sedang sibuk dan saat ini tidak dapat memproses dokumen. Coba lagi setelah waktu tunggu habis.
printer_error	Printer dalam status error dan memerlukan interaksi pengguna untuk memperbaikinya. Deskripsi harus berisi penjelasan yang lebih mendetail (misalnya, "Kertas macet di Baki 1").
invalid_params	Parameter tidak valid yang ditentukan dalam permintaan. (Parameter yang tidak diketahui dapat diabaikan dengan aman untuk kompatibilitas mendatang)
user_cancel	Pengguna secara eksplisit membatalkan proses pencetakan dari perangkat.
server_error	Gagal memposting dokumen ke Cloud Print.
invalid_x_privet_token	X-Privet-Token tidak valid atau kosong dalam permintaan.

Jika perangkat tidak mengekspos /privet/printer/submitdoc, perangkat HARUS menampilkan error HTTP 404. Jika header X-Privet-Token tidak ada, perangkat HARUS menampilkan error HTTP 400.

Catatan: /privet/printer/submitdoc API mungkin memerlukan penanganan khusus di sisi printer (karena payload besar yang dilampirkan). Dalam beberapa kasus (bergantung pada penerapan dan platform server HTTP printer), printer dapat menutup soket SEBELUM menampilkan error HTTP. Di sisi lain, printer dapat menampilkan error 503 (bukan error Privet). Printer HARUS mencoba semaksimal mungkin untuk mengembalikan Privet. Namun, setiap klien yang menerapkan spesifikasi Privet HARUS dapat menangani penutupan soket (tanpa error HTTP) dan kasus error HTTP 503 untuk API /privet/printer/submitdoc. Dalam hal ini, klien HARUS menanganinya sebagai error "printer_busy" Privet dengan "timeout" yang disetel ke 15 detik. Untuk menghindari percobaan ulang tanpa batas, klien dapat berhenti mencoba ulang setelah sejumlah percobaan yang wajar (misalnya, 3).

5.3. /privet/printer/jobstate API

API /privet/printer/jobstate bersifat OPSIONAL (lihat Pencetakan Sederhana di atas). Ini adalah permintaan HTTP GET. API /privet/printer/jobstate HARUS memeriksa header "X-Privet-Token" yang valid. Perangkat HARUS menerapkan API ini di URL "/privet/printer/jobstate":

GET /privet/printer/jobstate HTTP/1.1

Saat menerima panggilan API /privet/printer/jobstate, printer harus menampilkan status tugas cetak yang diminta atau error invalid_print_job.

5.3.1. Input

/privet/printer/jobstate API memiliki parameter input berikut:

Nama	Nilai
job_id	ID tugas cetak untuk menampilkan status.

5.3.2. Pulang pergi

/privet/printer/jobstate API menampilkan data berikut:

Nama nilai	Jenis nilai	Deskripsi
job_id	string	ID pekerjaan cetak yang status informasinya ditujukan untuk.
dengan status tersembunyi akhir	string	draf - tugas cetak telah dibuat di perangkat (belum ada panggilan /privet/printer/submitdoc yang diterima). dalam antrean - tugas cetak telah diterima dan dimasukkan dalam antrean, tetapi pencetakan belum dimulai. in_progress - tugas cetak sedang dalam proses pencetakan. dihentikan - tugas cetak telah dijeda, tetapi dapat dimulai ulang secara manual atau otomatis. done - tugas cetak selesai. dibatalkan - tugas cetak gagal.
deskripsi	string	(opsional) Deskripsi status tugas cetak yang dapat dibaca manusia. Harus menyertakan informasi tambahan jika state< adalah stopped atau aborted. Kolom semantic_state biasanya memberikan deskripsi yang lebih baik dan lebih bermakna kepada klien.
expires_in	int	Jumlah detik tugas cetak ini valid.
job_type	string	(opsional) Jenis konten dokumen yang dikirimkan.
job_size	int 64 bit	(opsional) Ukuran data cetak dalam byte.
job_name	string	(opsional) Nama tugas yang sama seperti di input (jika ada).
server_job_id	string	(opsional) ID tugas yang ditampilkan dari server (jika tugas telah diposting ke layanan Cloud Print). Dihilangkan untuk pencetakan offline.
semantic_state	JSON	(opsional) Status semantik tugas dalam format PrintJobState.

Contoh (mencetak dengan melaporkan melalui 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"
}

Contoh (error pencetakan 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"
}

Contoh (tugas cetak dibatalkan oleh pengguna):

{
        "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
        }
}

Contoh (tugas cetak dihentikan karena kehabisan kertas). Perhatikan referensi ke status perangkat. Klien harus memanggil API /privet/info untuk mendapatkan detail selengkapnya tentang status perangkat:

{
        "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. Error

/privet/printer/jobstate API dapat menampilkan error berikut (lihat bagian Error untuk mengetahui detailnya):

Error	Deskripsi
invalid_print_job	ID tugas yang tidak valid/telah berakhir ditentukan dalam permintaan.
server_error	Mendapatkan status tugas cetak (untuk tugas cetak yang diposting ke Cloud Print) telah gagal.
invalid_x_privet_token	X-Privet-Token tidak valid atau kosong dalam permintaan.

Jika perangkat tidak mengekspos /privet/printer/jobstate, perangkat HARUS menampilkan error HTTP 404. Jika header X-Privet-Token tidak ada, perangkat HARUS menampilkan error HTTP 400.

6. Lampiran

6.1. Perilaku dan setelan default

Bagian ini akan menjelaskan perilaku default yang kami harapkan dari SEMUA perangkat yang kompatibel dengan Privet.

Perangkat siap pakai hanya boleh mendukung API /privet/info dan /privet/register. Semua API lainnya (misalnya /privet/accesstoken, pencetakan lokal) harus dinonaktifkan.
Pendaftaran memerlukan interaksi fisik dengan perangkat.

Pengguna HARUS melakukan tindakan fisik di perangkat (misalnya, menekan tombol) untuk mengonfirmasi akses mereka ke perangkat.
Setelah pengguna melakukan tindakan yang disebutkan di atas, printer akan mengirim permintaan /cloudprint/register. Permintaan ini tidak boleh dikirim hingga tindakan dilakukan (lihat Diagram Urutan 1).
Jika perangkat sedang memproses permintaan /privet/register (misalnya, menunggu tindakan di atas), perangkat harus menolak semua permintaan /privet/register lainnya. Perangkat HARUS menampilkan error device_busy dalam kasus ini.
Perangkat akan menghentikan permintaan /register yang tidak menerima tindakan fisik yang disebutkan di atas dalam waktu 60 detik. Perangkat HARUS menampilkan error confirmation_timeout dalam kasus ini.
Opsional: Direkomendasikan, tetapi tidak wajib, hal berikut dapat meningkatkan pengalaman pengguna:

Printer mungkin mengedipkan lampu atau layarnya untuk menunjukkan bahwa pengguna perlu melakukan tindakan untuk mengonfirmasi pendaftaran.
Printer mungkin menyatakan di layarnya bahwa 'printer sedang didaftarkan ke Google Cloud Print untuk pengguna 'abc@def.com' - tekan OK untuk melanjutkan', dengan abc@def.com adalah parameter pengguna dari panggilan API /register. Hal ini akan memperjelas bagi pengguna bahwa:

bahwa mereka mengonfirmasi permintaan pendaftaran mereka
apa yang terjadi jika dia tidak memicu permintaan.

Selain tindakan fisik untuk mengonfirmasi dari printer (misalnya, ‘Tekan tombol OK’), printer juga dapat menawarkan tombol kepada pengguna untuk membatalkan permintaan (misalnya, 'Tekan Batal untuk menolak'). Hal ini akan memungkinkan pengguna yang tidak memicu permintaan pendaftaran untuk membatalkannya sebelum waktu tunggu 60 detik. Perangkat HARUS menampilkan error user_cancel dalam kasus ini.

Transfer kepemilikan:

Perangkat mungkin dihapus secara eksplisit dari layanan Cloud.

Jika perangkat menerima keberhasilan, tetapi tidak ada deskripsi perangkat sebagai hasil dari panggilan /cloudprint/printer (untuk GCP), perangkat HARUS kembali ke mode default (langsung pakai).
Jika kredensial perangkat tidak lagi berfungsi (secara eksplisit karena respons "kredensial tidak valid" dari server), perangkat HARUS kembali ke mode default (langsung digunakan).

Reset ke setelan pabrik lokal HARUS menghapus kredensial perangkat dan menyetelnya ke status default.
Opsional: Perangkat dapat menyediakan item menu untuk menghapus kredensial dan mengaktifkan mode default.

Perangkat yang mendukung notifikasi XMPP HARUS menyertakan kemampuan untuk melakukan ping ke server. Waktu tunggu ping HARUS dapat dikontrol dari server melalui "local_settings".
Perangkat dapat secara eksplisit melakukan ping ke server (API /cloudprint/printer untuk GCP, selain ping XMPP) tidak lebih dari sekali sehari (24 jam) untuk memastikan sinkronisasi. Sebaiknya acak periode pemeriksaan dalam jangka waktu 24-32 jam.
Opsional: Untuk perangkat Cloud Print, sebaiknya sediakan cara manual (tombol) agar pengguna dapat memulai pemeriksaan tugas cetak baru dari perangkat, tetapi hal ini tidak wajib. Beberapa printer sudah memilikinya.
Opsional. Printer perusahaan mungkin memiliki opsi untuk menonaktifkan penemuan lokal sepenuhnya. Dalam kasus tersebut, perangkat HARUS memperbarui setelan lokal ini di server. Setelan lokal baru HARUS kosong (menyetel "local_discovery" ke "false", berarti setelan tersebut dapat diaktifkan kembali dari Layanan GCP).

6.1.2 Diagram Pendaftaran Default

6.2. Serangan dan pencegahan XSSI dan XSRF

Bagian ini akan menjelaskan kemungkinan serangan XSSI dan XSRF pada perangkat serta cara melindungi diri dari serangan tersebut (termasuk teknik pembuatan token).
Detail selengkapnya ada di sini: http://googleonlinesecurity.blogspot.com/2011/05/website-security-for-webmasters.html
Biasanya, serangan XSSI dan XSRF dapat terjadi saat situs menggunakan mekanisme autentikasi cookie. Meskipun Google tidak menggunakan cookie dengan Layanan Cloud Print-nya, serangan semacam itu tetap mungkin terjadi. Akses jaringan lokal, berdasarkan desainnya, secara implisit mempercayai permintaan.

6.2.1. XSSI

Situs berbahaya dapat menebak alamat IP dan nomor port perangkat yang kompatibel dengan Privet dan mencoba memanggil Privet API menggunakan "src=<api name>" di dalam tag <script>:

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

Tanpa perlindungan, situs berbahaya dapat mengeksekusi panggilan API dan mengakses hasilnya.
Untuk mencegah jenis serangan ini, SEMUA panggilan Privet API HARUS memerlukan header "X-Privet-Token" dalam permintaan. Tag skrip "src=<api>" tidak dapat menambahkan header, sehingga secara efektif melindungi dari jenis serangan ini.

6.2.2. XSRF

http://en.wikipedia.org/wiki/Cross-site_request_forgery
Situs berbahaya dapat menebak alamat IP dan nomor port perangkat yang kompatibel dengan Privet dan mencoba memanggil Privet API menggunakan <iframe>, formulir, atau mekanisme pemuatan lintas situs lainnya. Penyerang tidak akan dapat mengakses hasil permintaan, tetapi jika permintaan akan melakukan tindakan (misalnya, mencetak), mereka dapat memicunya.

Untuk mencegah serangan ini, kami memerlukan perlindungan berikut:

Membiarkan API /privet/info terbuka terhadap XSRF
API /privet/info TIDAK BOLEH melakukan tindakan apa pun di perangkat
Menggunakan API /privet/info untuk menerima x-privet-token
Semua API lainnya HARUS memeriksa x-privet-token yang valid di header "X-Privet-Token".
x-privet-token HARUS valid hanya selama 24 jam.

Meskipun penyerang dapat mengeksekusi API /privet/info, mereka tidak akan dapat membaca x-privet-token dari respons dan oleh karena itu tidak akan dapat memanggil API lain.

Sangat disarankan untuk membuat token XSRF menggunakan algoritma berikut:

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

Elemen Pembuatan Token XSRF:

DELIMITER adalah karakter khusus, biasanya ‘:’
issue_timecounter adalah jumlah detik sejak peristiwa tertentu (epoch untuk stempel waktu) atau waktu booting perangkat (untuk penghitung CPU). issue_timecounter terus bertambah saat perangkat aktif dan berjalan (lihat verifikasi token di bawah).
SHA1 - fungsi hash menggunakan algoritma SHA1
base64 - encoding base64
device_secret - rahasia khusus untuk perangkat. Secret perangkat HARUS diperbarui setiap kali dimulai ulang.

Cara yang direkomendasikan untuk membuat secret perangkat:

Membuat UUID baru setiap kali dimulai ulang
Membuat angka acak 64 bit pada setiap mulai ulang

Perangkat tidak diwajibkan untuk menyimpan semua token XSRF yang telah dikeluarkannya. Saat perangkat perlu memverifikasi validitas token XSRF, perangkat harus mendekode token base64. Dapatkan issue_timecounter dari paruh kedua (cleartext), dan coba buat hash SHA1 dari device_secret + PEMISAH + issue_timecounter dengan issue_timecounter berasal dari token. Jika SHA1 yang baru dibuat cocok dengan SHA1 dalam token, perangkat kini harus memeriksa apakah issue_timecounter berada dalam periode validitas dari (24 jam) penghitung waktu saat ini. Untuk melakukannya, perangkat mengambil penghitung waktu saat ini (misalnya, penghitung CPU) dan mengurangkan issue_timecounter dari penghitung waktu tersebut. Hasilnya HARUS berupa jumlah detik sejak penerbitan token.

Penting: Ini adalah cara yang direkomendasikan untuk menerapkan perlindungan XSRF. Klien spesifikasi Privet tidak boleh mencoba memahami token XSRF, tetapi harus memperlakukannya sebagai blackbox. Gambar 6.2.3 mengilustrasikan cara yang direkomendasikan untuk menerapkan X-Privet-Token dan verifikasi permintaan umum.

6.2.3 Diagram Urutan Pembuatan dan Verifikasi Token X-Privet

6.3. Diagram alur kerja

Bagian ini akan menggambarkan alur kerja dalam berbagai kasus.

6.3.1. Alur kerja printer siap pakai

6.3.2. Memulai printer terdaftar

6.3.3 Alur kerja penanganan notifikasi XMPP

6.3.4. Alur kerja pemeriksaan setelan printer

Privet Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

1. Pengantar

2. Discovery

2.1. Jenis Layanan

2.2. Data TXT

2.2.1. txtvers

2.2.2. ty

2.2.3. catatan (opsional)

2.2.4. url

2.2.5. type

2.2.6. id

2.2.7. cs

3. Pengumuman

3.1. Startup

3.2. Nonaktif

3.3. Perbarui

4. API

4.1. Ketersediaan API

4.1.1. Pendaftaran

4.1.2. Startup

4.1.3. Perbarui

4.1.3.1. Setelan Lokal Tertunda

4.1.3.2. Setelan Lokal Saat Ini

4.1.4. Offline

4.1.5. Menghapus perangkat dari layanan

4.2. /privet/info API

4.2.1. Input

4.2.2. Pulang pergi

4.2.3. Error

4.3. /privet/register API

4.3.1. Input

4.3.2. Pulang pergi

4.3.3. Error

4.4. /privet/accesstoken API

4.4.1. Input

4.4.2. Pulang pergi

4.4.3. Error

4.5. /privet/capabilities API

4.5.1. Input

4.5.2. Pulang pergi

4.5.3. Error

4.6. Error

5. Printer API

5.1. /privet/printer/createjob API

5.1.1. Input

5.1.2. Pulang pergi

5.1.3. Error

5.2. /privet/printer/submitdoc API

5.2.1. Input

5.2.2. Pulang pergi

5.2.3. Error

5.3. /privet/printer/jobstate API

5.3.1. Input

5.3.2. Pulang pergi

5.3.3. Error

6. Lampiran

6.1. Perilaku dan setelan default

6.1.2 Diagram Pendaftaran Default

6.2. Serangan dan pencegahan XSSI dan XSRF

6.2.1. XSSI

6.2.2. XSRF

6.2.3 Diagram Urutan Pembuatan dan Verifikasi Token X-Privet

6.3. Diagram alur kerja

6.3.1. Alur kerja printer siap pakai

6.3.2. Memulai printer terdaftar

6.3.3 Alur kerja penanganan notifikasi XMPP

6.3.4. Alur kerja pemeriksaan setelan printer

Privet