Privet es una API de detección de dispositivos locales en la nube que usan los servicios en la nube. Este documento está organizado en las siguientes secciones:
- Introducción: Introducción a Privet
- Descubrimiento: Mecanismos de descubrimiento locales
- Anuncios: Avisos de descubrimiento locales
- API: API de Privet para dispositivos de nube generales
- API de impresora: Incluye las API de Privet que utilizan las impresoras.
- Apéndice: diagramas complementarios
1. Introducción
Los dispositivos conectados a la nube tienen muchos beneficios. Pueden usar los servicios de conversión en línea, alojar colas de trabajos mientras el dispositivo está sin conexión y se puede acceder a ellos desde cualquier lugar del mundo. Sin embargo, dado que un usuario determinado puede acceder a muchos dispositivos en la nube, debemos proporcionar un método para encontrar el dispositivo más cercano en función de la ubicación. El objetivo del protocolo Privet es vincular la flexibilidad de los dispositivos en la nube con un mecanismo de descubrimiento local adecuado para que los dispositivos se descubran con facilidad en entornos nuevos.
Los objetivos de este protocolo son los siguientes:- hacer que los dispositivos en la nube sean detectables localmente
- registrar dispositivos en la nube con un servicio en la nube
- asociar dispositivos registrados a su representación en la nube
- habilitar funcionalidad sin conexión
- Simplifique la implementación para que los dispositivos pequeños puedan usarla.
El protocolo Privet consta de 2 partes principales: descubrimiento y API. La detección se usa para encontrar el dispositivo en la red local, y la API se usa para obtener información sobre el dispositivo y realizar algunas acciones. En este documento, el dispositivo hace referencia a un dispositivo conectado a la nube que implementa el protocolo Privet.
2. Discovery
Discovery es un protocolo basado en zeroconf (mDNS y DNS-SD). El dispositivo DEBE implementar el direccionamiento IPv4 de vínculo local. El dispositivo DEBE cumplir con las especificaciones de mDNS y DNS-SD.
- http://www.rfc-editor.org/rfc/rfc3927.txt (IPv4 Vínculo local)
- http://www.rfc-editor.org/rfc/rfc4862.txt (IPv6 Vínculo local)
- http://www.rfc-editor.org/rfc/rfc6762.txt (mDNS)
- http://www.rfc-editor.org/rfc/rfc6763.txt (DNS-SD)
El dispositivo DEBE realizar la resolución de conflictos de nombres de acuerdo con las especificaciones anteriores.
2.1. Tipo de servicio
DNS Service Discovery usa el siguiente formato para los tipos de servicio: _applicationprotocol._transportprotocol. En el caso del protocolo Privet, el tipo de servicio para DNS-SD debe ser: _privet._tcp
El dispositivo también puede implementar otros tipos de servicios. Se recomienda usar el mismo nombre de instancia de servicio para todos los tipos de servicios que implementa el dispositivo. Por ejemplo, una impresora puede implementar servicios de "Impresora XYZ._privet._tcp" e "Impresora XYZ._printer._tcp". Simplificará la configuración para el usuario. Sin embargo, los clientes de Privet solo buscarán "_privet._tcp".
Además del tipo de servicio principal, el dispositivo DEBE anunciar los registros PTR de sus subtipos correspondientes (consulta las especificaciones de DNS-SD: &7.1. Enumeración de instancias selectiva (subtipos)". El formato debe ser el siguiente: _<subtype>.sub._privet._tcp
Actualmente, el único subtipo de dispositivo compatible es printer. Por lo tanto, todas las impresoras DEBEN crear dos registros PTR:
- _privet._tcp.local
- _impresión._sub._privet._tcp.local.
2.2. registro TXT
El Descubrimiento de servicios de DNS define campos para agregar información opcional sobre un servicio en los registros TXT. Un registro TXT consta de pares clave-valor. Cada par clave-valor comienza desde el byte de longitud seguido de hasta 255 bytes de texto. La clave es el texto que aparece antes del primer carácter “=” y el valor es el texto que está después del primer carácter “=” hasta el final. La especificación no permite ningún valor en el registro; en ese caso, no será un carácter "=" O ningún texto después del carácter "=". (Consulta las especificaciones de DNS-SD: "6.1. Reglas de formato general para los registros TXT de DNS" para el formato de registro TXT de DNS & &tt;6.2. DNS-SD TXT Record Size" para la longitud recomendada).
Privet requiere que el dispositivo envíe los siguientes pares clave-valor en el registro TXT. Las strings de clave-valor no distinguen entre mayúsculas y minúsculas. Por ejemplo, “CS=online” y “cs=ONLINE” son iguales. La información del registro TXT DEBE ser la misma a la que se puede acceder a través de la /info API (consulte la sección 4.1. API).
Se recomienda mantener un tamaño de registro TXT inferior a 512 bytes.
2.2.1. txtver
Versión de la estructura TXT. Los archivos TXT DEBEN ser el primer registro de la estructura TXT. Actualmente, la única versión compatible es 1.
txtvers=1
2.2.2. ty
Proporciona un nombre legible para el dispositivo. Por ejemplo:
ty=Google Cloud Ready Printer Model XYZ
2.2.3. Nota (opcional)
Proporciona un nombre legible para el dispositivo. Por ejemplo:
note=1st floor lobby printer
Nota: Esta es una clave opcional y se puede omitir. Sin embargo, si está presente, el usuario DEBE poder modificar este valor. Se debe usar la misma descripción cuando se registra el dispositivo.
2.2.4. url
URL del servidor al que está conectado este dispositivo (incluido el protocolo). Por ejemplo:
url=https://www.google.com/cloudprint
2.2.5. Tipo
Lista de subtipos de dispositivos compatibles con este dispositivo separados por comas. El formato es: "type=_subtype1,_subtype2". Actualmente, el único subtipo de dispositivo admitido es printer.
type=printer
Cada subtipo enumerado debe anunciarse con un registro PTR correspondiente. Para cada subtipo de servicio admitido, debe haber un elemento correspondiente. El nombre del subtipo de servicio (<subtype>.sub._privet._tcp) debe ser igual al tipo de dispositivo.
2.2.6. ID
ID del dispositivo. Si el dispositivo aún no se registró, esta clave debería estar presente, pero el valor debería estar vacío. Por ejemplo:
id=11111111-2222-3333-4444-555555555555 id=
2.2.7. cs
Indica el estado de conexión actual del dispositivo. Se definen cuatro valores posibles en esta especificación.
- "online" indica que el dispositivo está conectado actualmente a la nube.
- "offline&; indica que el dispositivo está disponible en la red local, pero no puede comunicarse con el servidor.
- "Conectando" indica que el dispositivo está realizando su secuencia de inicio y aún no está completamente en línea.
- "not-configured" indica que el acceso a Internet del dispositivo aún no se configuró. Este valor no se usa actualmente, pero puede ser útil en versiones futuras de la especificación.
- cs=en línea
- cs=sin conexión
- cs=conexión
Si el dispositivo se registró con una nube, durante el inicio debe verificar la conectividad con un servidor para detectar su estado de conexión (por ejemplo, llamar a la API de Cloud para obtener la configuración del dispositivo). El dispositivo puede usar el estado de conexión de su canal de notificaciones (p.ej., XMPP) para informar este valor. Es posible que los dispositivos no registrados en el inicio hagan ping a un dominio para detectar su estado de conexión (por ejemplo, hacer ping en www.google.com para dispositivos de impresión en la nube).
3. Anuncios
Cuando se inicia el dispositivo, se apaga o cambia de estado, el dispositivo DEBE realizar el paso del anuncio como se describe en la especificación de mDNS. DEBE enviar el anuncio correspondiente al menos dos veces con un intervalo de, al menos, un segundo.
3.1. Inicio
Cuando se inicia el dispositivo, DEBES realizar los pasos de sondeo y anuncio como se describe en la especificación de mDNS. En este caso, se deben enviar los registros SRV, PTR y TXT. Se recomienda agrupar todos los registros en una respuesta de DNS, si es posible. De lo contrario, se recomienda el siguiente orden: SRV, PTR, registros TXT.
3.2. Cierre
Al apagar un dispositivo, DEBE tratar de notificar a todas las partes interesadas al respecto mediante el envío de un "paquete de despedida" con TTL=0 (como se describe en la documentación de mDNS).
3.3. Actualizar
Si se modificó la información que se describe en TXT, el dispositivo DEBE enviar un anuncio de actualización. En este caso, basta con enviar el nuevo registro TXT. Por ejemplo, después de registrar un dispositivo, DEBE enviar un anuncio de actualización con el nuevo ID de dispositivo.
4. API
Después de descubrir un dispositivo en la nube, se habilita la comunicación con el cliente directamente en la red local. Todas las API están basadas en HTTP 1.1. Los formatos de datos se basan en JSON. Las solicitudes a la API pueden ser solicitudes GET o POST.
Cada solicitud DEBE contener un encabezado X-Privet-Token válido. La ÚNICA solicitud que se permite que tenga un encabezado vacío "X-Privet-Token" es la solicitud /privet/info (ten en cuenta que el encabezado aún DEBE estar presente). Si falta el encabezado &X-Privet-Token, el dispositivo DEBE responder con el siguiente error HTTP 400:
HTTP/1.1 400 Missing X-Privet-Token header.
Si el encabezado X-Privet-Token está vacío o no es válido, el dispositivo DEBE responder con un error de X-Privet-Token no válido (invalid_x_privet_token, consulta la sección Errores para obtener más detalles). La única excepción es la API /info. Para obtener más información sobre por qué se hace esto y cómo se deben generar los tokens, consulta el Apéndice A: Prevención y ataques de XSSI y XSRF.
Si una API solicitada no existe o no es compatible, el dispositivo DEBE mostrar un error HTTP 404.
4.1. de disponibilidad de API
Antes de exponer CUALQUIER API (incluida la API /info), el dispositivo DEBE comunicarse con el servidor para verificar la configuración local. La configuración local DEBE conservarse entre los reinicios. Si el servidor no está disponible, se debe usar la última configuración local conocida. Si el dispositivo aún no se registró, debe seguir la configuración predeterminada.
Los dispositivos de Google Cloud Print DEBEN seguir estos pasos para registrar, recibir y actualizar la configuración local.
4.1.1. Registro
Cuando el dispositivo se registra, DEBE especificar el parámetro "local_settings" de la siguiente manera:
{ "current": { "local_discovery": true, "access_token_enabled": true, "printer/local_printing_enabled": true, "printer/conversion_printing_enabled": true, "xmpp_timeout_value": 300 } }Puede establecer las siguientes opciones de configuración:
Nombre del valor | Tipo de valor | Descripción |
---|---|---|
descubrimiento_local | boolean | Indica si se permite la funcionalidad de descubrimiento local. Si &false; falso, se deben inhabilitar todas las API locales (incluida /info) y la detección de DNS-SD. De forma predeterminada, los dispositivos que se registran recientemente deben pasar "true". |
acceso_token_habilitado | booleano (opcional) | Indica si la API /accesstoken debe exponerse en la red local. De forma predeterminada, debe ser "verdadero". |
impresoras/local_printing_enabled | booleano (opcional) | Indica si la funcionalidad de impresión local (/printer/createjob, /printer/submitdoc) o /printer/jobstate) debe exponerse en la red local. De forma predeterminada, debe ser "verdadero". |
impresora/conversión_habilitada | booleano (opcional) | Indica si la impresión local puede enviar un trabajo al servidor para la conversión. Solo tiene sentido cuando la impresión local está habilitada. |
xmpp_timeout_value | int (opcional) | Indica la cantidad de segundos entre los pings del canal XMPP. La configuración predeterminada DEBE ser 300 (5 minutos) o más. |
Importante: La ausencia de un valor opcional indica que el dispositivo no admite la funcionalidad correspondiente.
4.1.2. Inicio
Al iniciarse el dispositivo, debe ponerse en contacto con el servidor a fin de verificar qué API están disponibles para exponerse en la red local. Para las impresoras conectadas a Cloud Print, deben llamar a:
/cloudprint/printer?printerid=<printer_id>o
/cloudprint/list
/cloudprint/printer es preferible a /cloudprint/list, pero ambas funcionan.
Esta API muestra los parámetros actuales del dispositivo, incluida la configuración de la API local. La respuesta del servidor tendrá el siguiente formato:
"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" indica la configuración que está activa en este momento.
"pending" indica la configuración que debe aplicarse al dispositivo (puede faltar este objeto).
Una vez que el dispositivo vea la configuración “Pendiente”, DEBES actualizar su estado (consulta a continuación).
4.1.3. Actualizar
Si se necesita actualizar la configuración, se enviará una notificación XMPP al dispositivo. La notificación tendrá el siguiente formato:
<device_id>/update_settings
Al recibir esta notificación, el dispositivo DEBE consultar al servidor para obtener la última configuración. Los dispositivos de Google Cloud Print DEBEN usar:
/cloudprint/printer?printerid=<printer_id>
Una vez que el dispositivo ve la sección "pendiente" como resultado de la API /cloudprint/printer (en el inicio o debido a la notificación), DEBE actualizar su estado interno para recordar la nueva configuración. DEBE llamar a la API del servidor para confirmar la nueva configuración. En el caso de las impresoras en la nube, el dispositivo DEBE llamar a la API /cloudprint/update y usar el parámetro "local_settings" durante el registro.
Cuando vuelvas a conectarte al canal XMPP, el dispositivo DEBE llamar a la API /cloudprint/printer para verificar si se modificó la configuración local desde la última vez.
4.1.3.1. Configuración local pendiente
El parámetro "local_settings" que el dispositivo usa para llamar a la API del servidor NO DEBE contener la sección "pendiente".
4.1.3.2. Configuración local actual
ÚNICAMENTE el dispositivo puede cambiar la sección "actual" de la &configuración local. Todos los demás cambiarán la sección "pendiente" y esperarán a que el dispositivo propague los cambios en la sección "actual".
4.1.4. Sin conexión
Si no puedes comunicarte con el servidor durante el inicio, después de la notificación, el dispositivo DEBE usar la última configuración local conocida.
4.1.5. Borrando dispositivo del servicio
Si se borró el dispositivo del servicio (por ejemplo, GCP), se enviará una notificación XMPP. La notificación tendrá el siguiente formato:
<device_id>/delete
Al recibir esta notificación, el dispositivo DEBE ir al servidor para comprobar su estado. Los dispositivos de Google Cloud Print DEBEN usar:
/cloudprint/printer?printerid=<printer_id>
El dispositivo DEBE recibir una respuesta HTTP correcta, con éxito=falso y sin descripción de dispositivo/impresora. Significa que se quitó el dispositivo del servidor y que el dispositivo DEBE borrar sus credenciales y activar el modo de configuración de fábrica predeterminado.
Cada vez que el dispositivo recibe una respuesta que indica que se borró como resultado de la API /cloudprint/printer (inicio, notificación de configuración de actualización, ping diario), DEBE borrar sus credenciales y activar el modo predeterminado.
4.2. API de /privet/info
La API de información es OBLIGATORIA y DEBE implementarla por cada dispositivo. Es una solicitud HTTP GET para "/privet/info&url: GET /privet/info HTTP/1.1
La API de información muestra información básica sobre un dispositivo y las funciones que admite. Esta API NO DEBE cambiar el estado del dispositivo ni realizar ninguna acción, ya que es vulnerable a los ataques de XSRF. Esta es la ÚNICA API que puede tener un encabezado de &X-Privet-Token vacío. Los clientes deben llamar a la API de /privet/info con el encabezado "X-Privet-Token" establecido en X-Privet-Token: & &;
La API de información DEBE mostrar datos coherentes con los datos disponibles en el registro TXT durante el descubrimiento.
4.2.1. Entrada
La API de /privet/info no tiene parámetros de entrada.
4.2.2. Volver
La API de /privet/info muestra información básica sobre el dispositivo y la funcionalidad compatible.
La columna TXT indica el campo correspondiente en el registro TXT de DNS-SD.
Nombre del valor | Tipo de valor | Descripción | TXT |
---|---|---|---|
version | string | La versión más alta (principal) de la API compatible, actualmente 1.0 | |
name | string | Es el nombre legible del dispositivo. | ty |
descripción | string | (Opcional) Descripción del dispositivo. El usuario debe poder modificarlo. | nota |
url | string | URL del servidor con el que está hablando este dispositivo. La URL DEBE incluir la especificación del protocolo, por ejemplo: https://www.google.com/cloudprint. | url |
type | lista de strings | Lista de tipos de dispositivos compatibles. | type |
id | string | ID de dispositivo, vacío si aún no se registró el dispositivo. | id |
dispositivo_estado | string | Estado del dispositivo: inactivo significa que el dispositivo está listo. Procesando: significa que el dispositivo está ocupado y su funcionalidad puede estar limitada durante un tiempo. detenido significa que el dispositivo no funciona y se requiere la intervención del usuario. | |
estado_de_conexión | string | Estado de la conexión con el servidor (base_url)
en línea - conexión disponible sin conexión - sin conexión conexión - realizando pasos de inicio no configurado - aún no se configuró | cs |
fabricante | string | Nombre del fabricante del dispositivo | |
modelo | string | Modelo del dispositivo | |
número_de_serie | string | Es un identificador de dispositivo único. En esta especificación, DEBE ser un UUID. (Especificación de GCP 1.1) (opcional) Recomendamos usar el mismo ID de número de serie en todas partes para que diferentes clientes puedan identificar el mismo dispositivo. Por ejemplo, las impresoras que implementan IPP pueden usar este ID de número de serie en el campo &printt-device-id". | |
firmware | string | Versión de firmware del dispositivo | |
uptime | int | Cantidad de segundos desde el inicio del dispositivo. | |
URL_configuración | string | (Opcional) URL (incluido el protocolo) de la página con instrucciones de configuración | |
URL_de_asistencia | string | (Opcional) URL (incluido el protocolo) de la página con asistencia, información sobre las Preguntas frecuentes | |
actualizar URL | string | (Opcional) URL (incluido el protocolo) de la página con instrucciones de firmware de actualización | |
token-privet-x | string | Valor del encabezado X-Privet-Token que se debe pasar a todas las API para evitar ataques XSSI y XSRF. Consulta 6.1 para obtener más detalles. | |
api | descripción de las API | Lista de API compatibles (que se describen a continuación) | |
estado_semántico | JSON | Es un estado semántico del dispositivo en formato CloudDeviceState (opcional). |
api: Es una lista JSON que contiene la lista de las API disponibles a través de la red local. Ten en cuenta que es posible que no todas las API estén disponibles al mismo tiempo en la red local. Por ejemplo, un dispositivo conectado recientemente solo debería admitir la API de /register:
"api": [ "/privet/register", ]Una vez que se completa el registro del dispositivo, este DEBE admitir la API de /register. El dispositivo también debe verificar con el servicio qué API pueden exponerse en la red local. Por ejemplo:
"api": [ "/privet/accesstoken", "/privet/capabilities", "/privet/printer/submitdoc", ]
En este momento, están disponibles las siguientes API:
- /privet/register: API para el registro de dispositivos en la red local (consulta la API /privet/register para obtener más información). Esta API DEBE ocultarse una vez que el dispositivo se registra correctamente en la nube.
- /privet/accesstoken: API para solicitar token de acceso desde el dispositivo (consulta la API /privet/accesstoken para obtener más información)
- /privet/capabilities: API para recuperar funciones del dispositivo (consulta la API /privet/capabilities para obtener más información)
- /privet/printer/*: API específica para el tipo de dispositivo "printer" consulta las API específicas para impresoras para obtener más detalles.
{ "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", ] }Este es un ejemplo de la respuesta de /privet/info para una impresora que se quedó sin tinta (observa el campo semántica_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. Errores
/privet/info API SOLO debería mostrar un error si falta el encabezado X-Privet-Token. DEBE ser error HTTP 400:
HTTP/1.1 400 Missing X-Privet-Token header.
4.3. API de /privet/register
La API de /privet/register es OPCIONAL. Es una solicitud HTTP POST. La API de /privet/register DEBE verificar si un encabezado X-Privet-Token es válido. El dispositivo DEBE implementar esta API en la URL &pritt/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
El dispositivo debe exponer la API de /privet/register SOLO cuando permite el registro anónimo en este momento. Por ejemplo:
- Cuando el dispositivo está encendido (o después de hacer clic en un botón especial en el dispositivo) y aún no se ha registrado, debería exponer la API /privet/register para permitir que un usuario de la red local pueda reclamar la impresora.
- Una vez que se completa el registro, el dispositivo debe dejar de exponer la API de /privet/register para evitar que otro usuario de la red local reclame el dispositivo.
- Algunos dispositivos pueden tener diferentes maneras de registrar dispositivos y no deben exponer la API /privet/register (por ejemplo, el conector de Google Cloud Print).
El proceso de registro consta de 3 pasos (consulte el registro anónimo para Cloud Print).
- Iniciar el proceso de registro anónimo.
- Un cliente inicia este proceso llamando a la API /privet/register. Es posible que el dispositivo espere la confirmación del usuario en ese momento.
- Obtener token de reclamo
El cliente realiza un sondeo para saber cuándo el dispositivo está listo para continuar. Una vez que el dispositivo está listo, envía una solicitud al servidor para recuperar el token de registro y la URL de registro. El token y la URL recibidos DEBEN devolverse al cliente. Durante este paso, si el dispositivo recibe otra llamada para inicializar el registro, debería hacer lo siguiente:
- Si este es el mismo usuario que inició el registro, descarta todos los datos anteriores (si corresponde) y comienza un nuevo proceso de registro.
- Si se trata de otro usuario, se muestra el error device_busy y el tiempo de espera de 30 segundos.
Proceso completo de registro.
Una vez que el cliente haya reclamado el dispositivo, debe notificarlo para completar el registro. Una vez que se completa el proceso de registro, el dispositivo debe enviar un anuncio de actualización, incluido el ID de dispositivo recién adquirido.
Nota: Cuando el dispositivo está procesando una llamada a la API /privet/register, no se pueden procesar otras llamadas a la API /privet/register simultáneamente. El dispositivo DEBE mostrar el error device_busy y el tiempo de espera de 30 segundos.
Recomendamos encarecidamente que el usuario confirme el registro en el dispositivo. Si se implementa, el dispositivo DEBE esperar la confirmación del usuario DESPUÉS de recibir una llamada a la API /privet/register.action=start. El cliente llamará a la API de /privet/register?action=getClaimToken para saber cuándo se completó la confirmación del usuario y si el token de reclamo está disponible. Si el usuario cancela el registro en el dispositivo (por ejemplo, presiona el botón Cancelar), se DEBE mostrar el error user_cancel. Si el usuario no confirmó el registro en un plazo determinado, se DEBE mostrar el error confirm_timeout. Consulta la sección de valores predeterminados para obtener más detalles.
4.3.1. Entrada
La API de /privet/register tiene los siguientes parámetros de entrada:Nombre | Valor |
---|---|
acción | Puede ser una de las siguientes opciones: start, para iniciar el proceso de registro getClaimToken: Recuperar el token de reclamo del dispositivo cancel o cancelar el proceso de registro complete para completar el proceso de registro |
usuario | Correo electrónico del usuario que reclamará este dispositivo. |
El dispositivo DEBE verificar que la dirección de correo electrónico de todas las acciones (start, getClaimToken, cancel, complete) coincida.
4.3.2. Volver
La API de /privet/register muestra los siguientes datos:Nombre del valor | Tipo de valor | Descripción |
---|---|---|
acción | string | La misma acción que en el parámetro de entrada. |
usuario | string (opcional) | Mismo usuario que en el parámetro de entrada (puede faltar, si se omite en la entrada) |
token | string (opcional) | Token de registro (obligatorio para la respuesta “getClaimToken”, omitida por “start", “complete” y “cancel”). |
URL_reclamo | string (opcional) | URL de registro (obligatorio para la respuesta "getClaimToken", omitida por "start", "completo", "cancelar"). En el caso de las impresoras en la nube, debe ser la dirección "complete_invite_url" recibida del servidor. |
URL_reclamada_automática | string (opcional) | URL de registro (obligatorio para la respuesta "getClaimToken", omitida por "start", "completo", "cancelar"). En el caso de las impresoras en la nube, debe ser la dirección URL automatizada de invitación recibida del servidor. |
id_dispositivo | string (opcional) | ID del dispositivo nuevo (omitido para la respuesta de inicio, obligatorio para la respuesta completa). |
El dispositivo DEBE mostrar su ID de dispositivo en la respuesta de la API /privet/info SOLO después de que se completa el registro.
Ejemplo 1:
{ "action": "start", "user": "user@domain.com", }
Ejemplo 2:
{ "action": "getClaimToken", "user": "user@domain.com", "token": "AAA111222333444555666777", "claim_url": "https://domain.com/SoMeUrL", }
Ejemplo 3:
{ "action": "complete", "user": "user@domain.com", "device_id": "11111111-2222-3333-4444-555555555555", }
4.3.3. Errores
La API de /privet/register puede mostrar los siguientes errores (consulta la sección Errores para obtener más detalles):Error | Descripción |
---|---|
dispositivo_ocupado | El dispositivo está ocupado y no puede realizar la acción solicitada. Vuelve a intentarlo después del tiempo de espera. |
acción_usuario_pendiente | En respuesta a &gett;getClaimToken, este error indica que el dispositivo aún está pendiente de confirmación del usuario y se debe reintentar la solicitud después del tiempo de espera. |
cancelar_usuario | El usuario canceló explícitamente el proceso de registro del dispositivo. |
confirmación_tiempo de espera | Se agotó el tiempo de espera de la confirmación del usuario. |
acción_no válida | Se ha llamado a una acción no válida. Por ejemplo, si el cliente llamó a action=complete antes de llamar a action=start y action=getClaimToken. |
parámetros_no válidos | Los parámetros especificados en la solicitud no son válidos. (Los parámetros desconocidos se deben ignorar de forma segura para garantizar la compatibilidad en el futuro). Por ejemplo, muestra esto si el cliente llamó a action=unknown o user=. |
error_config_dispositivo | La fecha y la hora (o alguna otra configuración) son incorrectas en el dispositivo. El usuario debe ir al sitio web interno del dispositivo y establecer la configuración del dispositivo. |
sin conexión | El dispositivo no está conectado y no puede comunicarse con el servidor. |
error_servidor | Se produjo un error de servidor durante el proceso de registro. |
token_privado_x no válido | X-Privet-Token no es válido o está vacío en la solicitud. |
El dispositivo DEBE dejar de exponer la API de /privet/register después de completar el registro correctamente. Si el dispositivo no expone la API /privet/register, DEBE mostrar el error HTTP 404. Por lo tanto, si un dispositivo ya está registrado, la llamada a esta API DEBE mostrar 404. Si falta el encabezado X-Privet-Token, el dispositivo DEBE mostrar el error HTTP 400.
4.4. API de /privet/accesstoken
La API de /privet/accesstoken es OPCIONAL. Es una solicitud HTTP GET. La API de /privet/accesstoken DEBE verificar si el encabezado X-Privet-Token es válido. El dispositivo DEBE implementar esta API en la URL &pritt/accesstoken"GET /privet/accesstoken HTTP/1.1:
Cuando el dispositivo recibe la llamada a la API /accesstoken, debe llamar al servidor para recuperar el token de acceso del usuario dado y devolver el token al cliente. Luego, el cliente usará el token de acceso para acceder a este dispositivo a través de la nube.
Los dispositivos de Google Cloud Print DEBEN llamar a la siguiente API:
/cloudprint/proximitytokeny pasa el parámetro &print > userprint de la API local. Si el proceso es satisfactorio, la respuesta del servidor contendrá el siguiente objeto:
"proximity_token": { "user": "user@domain.com", "token": "AAA111222333444555666777", "expires_in": 600 }Los dispositivos de Google Cloud Print DEBEN pasar el valor del objeto "proximity_token" en la respuesta a las llamadas a la API /privet/accesstoken locales. Es más ventajoso (preparado para el futuro) que el dispositivo pase TODOS los parámetros (incluidos los que no se describen en esta especificación).
4.4.1. Entrada
La API de /privet/accesstoken tiene los siguientes parámetros de entrada:Nombre | Valor |
---|---|
usuario | Correo electrónico del usuario que tenía la intención de usar este token de acceso Puede estar vacío en la solicitud. |
4.4.2. Volver
La API de /privet/accesstoken muestra los siguientes datos:Nombre del valor | Tipo de valor | Descripción |
---|---|---|
token | string | Token de acceso que muestra el servidor |
usuario | string | Mismo usuario que en el parámetro de entrada. |
expires_in | int | Cantidad de segundos hasta que venza este token. Se recibe del servidor y se pasa en esta respuesta. |
Ejemplo:
{ "token": "AAA111222333444555666777", "user": "user@domain.com", "expires_in": 600 }
4.4.3. Errores
La API de /privet/accesstoken puede mostrar los siguientes errores (consulta la sección Errores para obtener más detalles):Error | Descripción |
---|---|
sin conexión | El dispositivo no está conectado y no puede comunicarse con el servidor. |
access_denied | Derechos insuficientes. Acceso denegado El dispositivo debería mostrar este error cuando el servidor haya rechazado explícitamente la solicitud. |
parámetros_no válidos | Los parámetros especificados en la solicitud no son válidos. (Los parámetros desconocidos se deben ignorar de forma segura para garantizar la compatibilidad en el futuro). Por ejemplo, si el cliente llamó a /accesstoken?user= o /accesstoken. |
error_servidor | Error del servidor. |
token_privado_x no válido | El token X-Privet no es válido o está vacío en la solicitud. |
Si el dispositivo no expone la API /privet/accesstoken, DEBE mostrar el error HTTP 404. Si falta el encabezado X-Privet-Token, el dispositivo DEBE mostrar el error HTTP 400.
4.5. API de /privet/capabilities
La API de /privet/capabilities es OPCIONAL. Es una solicitud HTTP GET. La API /privet/capabilities debe verificar la presencia de un encabezado de &X-Privet-Token válido. El dispositivo DEBE implementar esta API en la URL "privet/capabilities":GET /privet/capabilities HTTP/1.1Cuando el dispositivo recibe llamadas a la API de /capabilities, si el dispositivo puede hacerlo, DEBE comunicarse con el servidor para obtener funciones actualizadas. Por ejemplo, si una impresora admite la publicación de un trabajo de impresión (recibido localmente) a sí misma a través del servicio de Cloud Print, debería mostrar las funciones que el servicio de Cloud Print mostraría. En este caso, Cloud Print puede modificar las capacidades originales de la impresora, ya que agrega nuevas funciones que puede realizar antes de enviar el trabajo a la impresora. El caso más común es una lista de tipos de documentos admitidos. Si la impresora está sin conexión, debería mostrar los tipos de documentos que admite. Sin embargo, si la impresora está en línea y está registrada en Cloud Print, DEBE mostrar "*/*" como uno de los tipos compatibles. En este caso, el servicio de Cloud Print realizará la conversión necesaria. Para la impresión sin conexión, la impresora DEBE admitir, al menos, el formato “image/pwg-raster”.
4.5.1. Entrada
La API de /privet/capabilities tiene los siguientes parámetros de entrada:Nombre | Valor |
---|---|
sin conexión | (Opcional) Solo se puede "offline=1". En este caso, el dispositivo debe mostrar capacidades para uso sin conexión (si son diferentes de las capacidades "en línea"). |
4.5.2. Volver
La API de /privet/capabilities muestra las capacidades del dispositivo en el formato JSON de descripción del dispositivo en la nube (CDD) (consulta el documento de CDD para obtener más detalles). Como mínimo, las impresoras DEBEN mostrar una lista de los tipos compatibles aquí. Por ejemplo, una impresora lista para imprimir en la nube que está en línea puede mostrar algo como esto (como mínimo):{ "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": "*/*" } ] } }y, cuando se desconecta del servidor, puede mostrar lo siguiente:
{ "version": "1.0", "printer": { "supported_content_type": [ { "content_type": "application/pdf", "min_version": "1.4" }, { "content_type": "image/pwg-raster" }, { "content_type": "image/jpeg" } ] } }
Nota: Las impresoras expresan el orden de prioridad del tipo de contenido admitido. Por ejemplo, en los ejemplos anteriores, la impresora especifica que prefiere datos de "application/pdf" en lugar de "image/pwg-raster" e "image/jpeg". Si es posible, los clientes deben respetar la priorización de impresoras (consulta el documento de CDD para obtener más detalles).
4.5.3. Errores
La API de /privet/capabilities puede mostrar los siguientes errores (consulta la sección Errores para obtener más detalles):Error | Descripción |
---|---|
token_privado_x no válido | X-Privet-Token no es válido o está vacío en la solicitud. |
Si el dispositivo no expone la API /privet/capabilities, DEBE mostrar el error HTTP 404. Si falta el encabezado X-Privet-Token, el dispositivo DEBE mostrar el error HTTP 400.
4.6. Errores
Las API anteriores muestran los errores en el siguiente formato:Nombre del valor | Tipo de valor | Descripción |
---|---|---|
error | string | Tipo de error (definido por API) |
descripción | string (opcional) | Es una descripción legible del error. |
server_api | string (opcional) | En caso de error del servidor, este campo contiene la API del servidor que falló. |
código_servidor | int (opcional) | En caso de error del servidor, este campo contiene ese código de error que el servidor mostró. |
servidor_http_code | int (opcional) | En el caso del error de HTTP del servidor, este campo contiene el servidor de código de error HTTP que se muestra. |
timeout | int (opcional) | Cantidad de segundos que el cliente debe esperar antes de reintentar (solo para errores recuperables). El cliente DEBE aleatorizar el tiempo de espera real de este valor a un valor +20%. |
Todas las API DEBEN mostrar el error HTTP 400 si falta el encabezado X-Privet-Token.
HTTP/1.1 400 Falta el encabezado X-Privet-Token.
Ejemplo 1:
{ "error": "server_error", "description": "Service unavailable", "server_api": "/submit", "server_http_code": 503 }
Ejemplo 2:
{ "error": "printer_busy", "description": "Printer is currently printing other job", "timeout": 15 }
5. API de Printer
Uno de los tipos de dispositivo compatibles con este protocolo es el tipo de impresora. Los dispositivos que admiten este tipo PUEDEN implementar algunas funciones específicas para las impresoras. Lo ideal es que las impresiones en impresoras listas para imprimir en la nube pasen por un servidor de Cloud Print:
![](https://developers.google.cn/cloud-print/images/privet_image07.jpg?authuser=6&hl=es)
En algunos casos, es posible que un cliente necesite enviar un documento de manera local. Puede ser necesaria cuando el cliente no tiene un ID de Google o no puede comunicarse con el servidor de Google Cloud Print. En ese caso, el trabajo de impresión se enviará de manera local a la impresora. A su vez, la impresora usará el servicio Cloud Print para la cola y la conversión de trabajos. La impresora volverá a publicar el trabajo enviado de manera local en el servicio de Cloud Print y, luego, lo solicitará, ya que se envió a través de la nube. Este proceso proporcionará una experiencia del usuario flexible en términos de servicio (conversión) y administración/seguimiento de trabajos de impresión.
![](https://developers.google.cn/cloud-print/images/privet_image08.jpg?authuser=6&hl=es)
Debido a que el servicio de Cloud Print implementa la conversión, la impresora DEBE anunciar todos los formatos de entrada ("*/*") entre la lista de los tipos de contenido admitidos:
{ "version": "1.0", "printer": { "supported_content_type": [ { "content_type": "image/pwg-raster" }, { "content_type": "*/*" } ] } }
En algunos casos, se desea una solución completamente sin conexión. Debido a que las impresoras admiten una cantidad limitada de formatos de entrada, un cliente deberá convertir los documentos a algunos formatos de impresoras compatibles de forma nativa.
![](https://developers.google.cn/cloud-print/images/privet_image04.jpg?authuser=6&hl=es)
Esta especificación REQUIERE que todas las impresoras admitan al menos el formato PWG Raster ("image/pwg-raster") para la funda de impresión sin conexión. Una impresora puede admitir otros formatos (por ejemplo, JPEG) y, si un cliente lo admite, puede enviar documentos en ese formato. La impresora DEBE exponer los tipos admitidos a través de la API de /capabilities, por ejemplo:
{ "version": "1.0", "printer": { "supported_content_type": [ { "content_type": "image/pwg-raster" }, { "content_type": "image/jpeg" } ] } }Un cliente puede iniciar una impresión mediante la red local de dos maneras.
Impresión simple: El cliente envía el documento a través de la red local a la API /submitdoc (sin especificar el parámetro job_id). El documento enviado se imprimirá mediante la configuración predeterminada de los tickets de impresión y no se necesitan estados de trabajo de impresión. Si la impresora SOLO admite este tipo de impresión, DEBE anunciar solamente la API de /submitdoc en la respuesta de la API de /privet/info.
"api": [ "/privet/accesstoken", "/privet/capabilities", "/privet/printer/submitdoc", ]
Impresión avanzada: El cliente primero debe crear un trabajo de impresión en la impresora llamando a la API /privet/printer/createjob con un ticket de trabajo CJT válido en la solicitud. La impresora DEBE almacenar el ticket de impresión en la memoria y mostrar un job_id al cliente. Luego, el cliente llamará a la API de /printer/submitdoc y especificará el job_id recibido anteriormente. En ese momento, la impresora comenzará a imprimir. El cliente sondeará la impresora para el estado del trabajo de impresión llamando a la API /privet/printer/jobstate.
En un entorno de varios clientes, no hay garantía de cómo se llamará a esta API. Es posible que un cliente llame a /createjob entre las llamadas de otro cliente de /createjob>/submitdoc. Para eliminar los posibles interbloqueos y mejorar la usabilidad, recomendamos que tengas una pequeña cola de trabajos de impresión pendientes en la impresora (al menos de 3 a 5):
- /createjob ocupa el primer espacio disponible en la cola.
- El ciclo de vida del trabajo (en la cola) es de al menos 5 minutos.
- Si se ocupan todos los lugares de la cola, se quitará el trabajo no imprimible más antiguo y se colocará uno nuevo.
- Si hay un trabajo de impresión actualmente en impresión en el dispositivo (impresión simple o avanzada), /submitdoc debe mostrar el estado ocupado y proponer un tiempo de espera para reintentar este trabajo de impresión.
- Si /submitdoc hace referencia a un trabajo que se quitó de la cola (debido a reemplazo o tiempo de espera), la impresora debería mostrar un error invalid_print_job y el cliente reintentará el proceso con el paso /createjob. El cliente DEBE esperar un tiempo de espera aleatorio de hasta 5 segundos antes de volver a intentarlo.
Si las restricciones de memoria impiden el almacenamiento de varios trabajos pendientes en el dispositivo, es posible tener una cola de 1 trabajo de impresión. Debe seguir el mismo protocolo que el anterior. Después de que un trabajo se completa o falla con un error, la impresora debe almacenar información sobre el estado del trabajo durante al menos 5 minutos. El tamaño de la cola para almacenar estados de trabajo completados debe ser de 10 como mínimo. Si hay más estados de trabajo que se deban almacenar, el más antiguo se puede quitar de la cola antes del tiempo de espera de 5 minutos.
Nota: Por ahora, los clientes sondearán para ver el estado del trabajo. En el futuro, es posible que solicitemos a la impresora que envíe una notificación de DNS TXT cuando cambie el estado de cualquier trabajo de impresión.
5.1. API de /privet/printer/createjob
La API de /privet/printer/createjob es OPCIONAL (consulte Impresión simple más arriba). Es una solicitud HTTP POST. La API /privet/printer/createjob DEBE verificar que el encabezado X-Privet-Token sea válido. El dispositivo DEBE implementar esta API en la URL &pritt/priert/printer/createjob:
POST /privet/printer/createjob HTTP/1.1Cuando recibes una llamada a la API /privet/printer/createjob, la impresora DEBE crear un ID de trabajo de impresión nuevo, almacenar el ticket de impresión recibido en formato CJT y mostrar el ID del trabajo de impresión al cliente.
5.1.1. Entrada
La API de /privet/printer/createjob no tiene parámetros de entrada en la URL. El cuerpo de la solicitud debe contener los datos del ticket de trabajo de impresión en formato CJT.5.1.2. Volver
La API de /privet/printer/createjob muestra los siguientes datos:Nombre del valor | Tipo de valor | Descripción |
---|---|---|
job_id | string | ID del trabajo de impresión recién creado. |
expires_in | int | Cantidad de segundos de validez de este trabajo de impresión. |
Ejemplo:
{ "job_id": "123", "expires_in": 600 }
5.1.3. Errores
La API de /privet/printer/createjob puede mostrar los siguientes errores (consulta la sección Errores para obtener más detalles):Error | Descripción |
---|---|
entrada_no válida | El ticket de impresión enviado no es válido. |
impresora_ocupado | La impresora está ocupada y, por el momento, no puede procesar /createjob. Vuelve a intentarlo después del tiempo de espera. |
error_impresora | La impresora se encuentra en estado de error y requiere interacción del usuario para corregirla. La descripción debe contener una explicación más detallada (por ejemplo, "Atasco de papel en la bandeja 1"). |
token_privado_x no válido | X-Privet-Token no es válido o está vacío en la solicitud. |
Si el dispositivo no expone /privet/printer/createjob, DEBE mostrar el error HTTP 404. Si falta el encabezado X-Privet-Token, el dispositivo DEBE mostrar el error HTTP 400.
5.2. API de /privet/printer/submitdoc
Se requiere la API de /privet/printer/submitdoc para implementar la impresión a través de una red local (sin conexión o volver a publicar en Cloud Print). Es una solicitud HTTP POST. La API de /privet/printer/submitdoc DEBE verificar un encabezado "&-Privet-Token" válido. El dispositivo DEBE implementar esta API en la URL"privet/printer/submitdoc":POST /privet/printer/submitdoc HTTP/1.1Cuando reciba la llamada a la API /privet/printer/submitdoc, la impresora debería comenzar a imprimir. Si no puede comenzar a imprimir, DEBE mostrar el error print_busy y un tiempo de espera recomendado para que el cliente espere antes de volver a intentarlo.
Si la impresora no puede contener todos los datos en su búfer interno, DEBE usar mecanismos de TCP para disminuir la velocidad de la transferencia de datos hasta que imprime una parte del documento, lo que permite que parte del búfer vuelva a estar disponible. (Por ejemplo, la impresora puede configurar windowsize=0 en las capas TCP, lo que hará que el cliente espere).
Enviar un documento a la impresora puede demorar bastante tiempo. El cliente debe poder verificar el estado de la impresora y del trabajo (impresión avanzada) mientras la impresión está en curso. Para ello, la impresora DEBE permitir que el cliente llame a las API /privet/info y /privet/printer/jobstate mientras procesa las llamadas a la API /privet/printer/submitdoc. Se recomienda que todos los clientes inicien un subproceso nuevo para ejecutar la llamada a la API /privet/printer/submitdoc, de modo que el subproceso principal pueda usar las API /privet/info y /privet/printer/jobstate para verificar los estados de las impresoras y los trabajos.
Nota: Después de completar o realizar el aborto del trabajo de impresión local, se recomienda (y se requerirá en una versión futura de esta especificación) informar el estado final del trabajo a la interfaz /cloudprint/submit para fines contables y de experiencia del usuario. Los parámetros "printerid", "title" y "contentType" y "final_semantic_state" (en formato PrintJobState) son obligatorios, y los parámetros "tag" (etiqueta repetida) y "ticket" del trabajo. Ten en cuenta que el PrintJobState proporcionado debe ser definitivo, es decir, su tipo debe ser DONE o ABORTED, y se debe proporcionar una causa en el caso de que sea ABORTED (consulta JobState para obtener más detalles). Además, ten en cuenta que el uso de la interfaz /cloudprint/submit para informar trabajos de impresión locales no se menciona en su especificación, ya que esa sección tiene como objetivo describir el uso principal de la interfaz: enviar un trabajo de impresión con el documento para imprimir proporcionado en el parámetro &content.
5.2.1. Entrada
La API de /privet/printer/submitdoc tiene los siguientes parámetros de entrada:Nombre | Valor |
---|---|
job_id | (Opcional) ID de trabajo de impresión. Se puede omitir para casos de impresión simples (consulta arriba). Debe coincidir con el que muestra la impresora. |
nombre_usuario | (Opcional) Nombre de usuario legible. Esto no es definitivo y solo se debe usar para las anotaciones del trabajo de impresión. Si el trabajo se vuelve a publicar en el servicio de Cloud Print, esta string debería adjuntarse al trabajo de Cloud Print. |
nombre_cliente | (Opcional) Nombre de la aplicación cliente que realiza esta solicitud. Solo con fines de visualización. Si el trabajo se vuelve a publicar en el servicio de Cloud Print, esta string se debe adjuntar al trabajo de Cloud Print. |
nombre_trabajo | (Opcional) Nombre del trabajo de impresión que se registrará. Si el trabajo se vuelve a publicar en el servicio de Cloud Print, esta string se debe adjuntar al trabajo de Cloud Print. |
sin conexión | (Opcional) Solo se puede "offline=1". En este caso, la impresora solo debe intentar imprimir sin conexión (no se puede volver a publicar en el servidor de Cloud Print). |
El cuerpo de la solicitud debe contener un documento válido para imprimir. "Content-Length" debe incluir la longitud correcta de la solicitud. El encabezado "Content-Type" debe configurarse para documentar el tipo de MIME y coincidir con uno de los tipos en el CDD (a menos que CDD especifique "*/*").
Recomendamos a los clientes proporcionar un nombre de usuario (o correo electrónico) válido, un nombre de cliente y un nombre de trabajo con esta solicitud. Esos campos solo se usan en las IU para mejorar la experiencia del usuario.
5.2.2. Volver
La API de /privet/printer/submitdoc muestra los siguientes datos:Nombre del valor | Tipo de valor | Descripción |
---|---|---|
job_id | string | ID del trabajo de impresión recién creado (impresión simple) o job_id especificado en la solicitud (impresión avanzada). |
expires_in | int | Cantidad de segundos de validez de este trabajo de impresión. |
tipo_trabajo | string | Es el tipo de contenido del documento enviado. |
tamaño_trabajo | int 64 bits | Tamaño de los datos de impresión en bytes. |
nombre_trabajo | string | (Opcional) El mismo nombre de trabajo que en la entrada (si corresponde). |
Ejemplo:
{ "job_id": "123", "expires_in": 500, "job_type": "application/pdf", "job_size": 123456, "job_name": "My PDF document" }
5.2.3. Errores
La API de /privet/printer/submitdoc puede mostrar los siguientes errores (consulta la sección Errores para obtener más detalles):Error | Descripción |
---|---|
trabajo_impreso_no válido | Se especificó un ID de trabajo no válido o vencido en la solicitud. Vuelve a intentarlo después del tiempo de espera. |
tipo_documento_no válido | La impresora no admite el tipo de MIME del documento. |
documento_no válido | El documento enviado no es válido. |
demasiado_documento_grande | El documento supera el tamaño máximo permitido. |
impresora_ocupado | La impresora está ocupada y no puede procesar el documento en este momento. Vuelve a intentarlo después del tiempo de espera. |
error_impresora | La impresora se encuentra en estado de error y requiere interacción del usuario para corregirla. La descripción debe contener una explicación más detallada (por ejemplo, "Atasco de papel en la bandeja 1"). |
parámetros_no válidos | Los parámetros especificados en la solicitud no son válidos. (Se deben ignorar de manera segura los parámetros desconocidos para garantizar la compatibilidad en el futuro). |
cancelar_usuario | El usuario canceló explícitamente el proceso de impresión desde el dispositivo. |
error_servidor | Se produjo un error al publicar el documento en Cloud Print. |
token_privado_x no válido | X-Privet-Token no es válido o está vacío en la solicitud. |
Si el dispositivo no expone /privet/printer/submitdoc, DEBE mostrar el error HTTP 404. Si falta el encabezado X-Privet-Token, el dispositivo DEBE mostrar el error HTTP 400.
Nota: Es posible que la API de /privet/printer/submitdoc requiera un manejo especial del lado de la impresora (debido a la gran carga útil adjunta). En algunos casos (depende de la implementación y la plataforma del servidor HTTP de la impresora), la impresora puede cerrar el socket ANTES de mostrar el error HTTP. En otros casos, la impresora puede mostrar el error 503 (en lugar del error de Privet). Las impresoras DEBEN hacer todo lo posible para devolver Privet. Sin embargo, cada cliente que implemente la especificación de Privet DEBE poder manejar el cierre de socket (sin error de HTTP) y los casos de error de HTTP 503 para la API de /privet/printer/submitdoc. En este caso, el cliente DEBERÍA manejarlo como un error de Privet “printer_busy” con un tiempo de espera de 15 segundos. Para evitar los reintentos infinitos, es posible que el cliente deje de reintentar después de una cantidad razonable de intentos (por ejemplo, 3).
5.3. API de /privet/printer/jobstate
/privet/printer/jobstate API es OPCIONAL (consulte Impresión simple más arriba). Es una solicitud HTTP GET. La API de /privet/printer/jobstate DEBE verificar que el encabezado X-Privet-Token sea válido. El dispositivo DEBE implementar esta API en la URL "/privet/printer/jobstate"GET /privet/printer/jobstate HTTP/1.1Cuando reciba una llamada a la API /privet/printer/jobstate, una impresora debería mostrar el estado del trabajo de impresión solicitado o de un error invalid_print_job.
5.3.1. Entrada
La API de /privet/printer/jobstate tiene los siguientes parámetros de entrada:Nombre | Valor |
---|---|
job_id | ID de trabajo de impresión para el que se muestra el estado. |
5.3.2. Volver
La API de /privet/printer/jobstate muestra los siguientes datos:Nombre del valor | Tipo de valor | Descripción |
---|---|---|
job_id | string | La información de estado del ID de trabajo de impresión es. |
state | string | borrador: Se creó un trabajo de impresión en el dispositivo (aún no se recibieron llamadas a /privet/printer/submitdoc).
En cola: el trabajo de impresión se recibió y se puso en cola, pero aún no comenzó la impresión. in_progress: el trabajo de impresión está en progreso de impresión. detenido: el trabajo de impresión se detuvo, pero se puede reiniciar de forma manual o automática. done: el trabajo de impresión está listo. abortado: se produjo un error en el trabajo de impresión. |
descripción | string | (Opcional) Descripción legible del estado del trabajo de impresión. Deben incluir información adicional si state se detiene o se anula. Por lo general, el campo semantic_state proporciona una descripción mejor y más significativa al cliente. |
expires_in | int | Cantidad de segundos de validez de este trabajo de impresión. |
tipo_trabajo | string | (Opcional) Tipo de contenido del documento enviado. |
tamaño_trabajo | int 64 bits | (Opcional) Tamaño de los datos de impresión en bytes. |
nombre_trabajo | string | (Opcional) El mismo nombre de trabajo que en la entrada (si corresponde). |
id_trabajo_servidor | string | ID (opcional) del trabajo que muestra el servidor (si el trabajo se publicó en el servicio de Cloud Print). Se omite para la impresión sin conexión. |
estado_semántico | JSON | Es un estado semántico del trabajo en formato PrintJobState (opcional). |
Ejemplo (impresión mediante informes con 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" }
Ejemplo (error de impresión sin conexión):
{ "job_id": "123", "state": "stopped", "description": "Out of paper", "expires_in": 100, "job_type": "application/pdf", "job_size": 123456, "job_name": "My PDF document" }
Ejemplo (trabajo de impresión anulado por el usuario):
{ "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 } }
Ejemplo (trabajo de impresión detenido debido a que no hay papel). Observa la referencia al estado del dispositivo. El cliente deberá llamar a la API de /privet/info para obtener más detalles sobre el estado del dispositivo:
{ "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. Errores
La API de /privet/printer/jobstate puede mostrar los siguientes errores (consulta la sección Errores para obtener más detalles):Error | Descripción |
---|---|
trabajo_impreso_no válido | Se especificó un ID de trabajo no válido o vencido en la solicitud. |
error_servidor | Se produjo un error al obtener el estado del trabajo de impresión (para trabajos de impresión publicados en Cloud Print). |
token_privado_x no válido | X-Privet-Token no es válido o está vacío en la solicitud. |
Si el dispositivo no expone /privet/printer/jobstate, DEBE mostrar el error HTTP 404. Si falta el encabezado X-Privet-Token, el dispositivo DEBE mostrar el error HTTP 400.
6. Apéndice
6.1. Comportamiento y configuración predeterminados
En esta sección, se explica el comportamiento predeterminado que esperamos de TODOS los dispositivos compatibles con Privet.- Los dispositivos listos para usar solo deben admitir las API /privet/info y /privet/register. Se deben inhabilitar todas las demás API (p.ej., /privet/accesstoken), impresión local.
- El registro requiere interacción física con un dispositivo.
- El usuario DEBE realizar una acción física en el dispositivo (p.ej., presionar un botón) para confirmar su acceso.
- Después de que el usuario realiza la acción indicada anteriormente, la impresora debe enviar la solicitud /cloudprint/register. No debería enviar esta solicitud hasta después de que se realice la acción (consulta el diagrama de secuencia 1).
- Si el dispositivo está procesando una solicitud /privet/register (por ejemplo, esperando la acción anterior), debe rechazar todas las demás solicitudes /privet/register. En este caso, el dispositivo DEBE mostrar el error device_busy.
- El dispositivo debe agotar cualquier solicitud de /register que no reciba la acción física mencionada anteriormente en un plazo de 60 segundos. En este caso, el dispositivo DEBE mostrar el error confirm_timeout.
- Opcional: Se recomienda, pero no es obligatorio que lo siguiente pueda mejorar la experiencia del usuario:
- Es posible que la impresora encienda una luz o la pantalla para indicar que el usuario debe realizar una acción para confirmar el registro.
- Es posible que la impresora indique en la pantalla que "se está registrando en Google Cloud Print para el usuario "abc@def.com"; presiona Aceptar para continuar, donde abc@def.com es el parámetro del usuario de la llamada a la API /register. Esto le dejaría más claro a un usuario lo siguiente:
- es la solicitud de registro que confirman
- qué sucede si no activa la solicitud;
- Además de una acción física para confirmar desde la impresora (p.ej., "Presiona el botón Aceptar", es posible que una impresora también le ofrezca un botón para cancelar la solicitud (p.ej., “Presiona Cancelar para rechazar”). Esto permitiría a los usuarios que no activaron la solicitud de registro cancelarla antes del tiempo de espera de 60 segundos. En este caso, el dispositivo DEBE mostrar el error user_cancel.
- Transferencias de propiedad:
- El dispositivo se puede borrar explícitamente del servicio de Cloud.
- Si el dispositivo recibe el resultado correcto, pero no tiene una descripción como resultado de la llamada con /cloudprint/printer (para GCP), DEBE revertir al modo predeterminado (lista para usar).
- Si las credenciales del dispositivo ya no funcionan (explícitamente debido a una respuesta "no válida" del servidor), DEBE volver al modo predeterminado (lista para usar).
- El restablecimiento de la configuración de fábrica local DEBE borrar las credenciales del dispositivo y establecer el estado predeterminado.
- Opcional: El dispositivo puede proporcionar un elemento de menú para borrar las credenciales y ponerlo en modo predeterminado.
- Los dispositivos que admiten notificaciones XMPP DEBEN incluir la capacidad de hacer ping al servidor. El tiempo de espera de ping DEBE controlarse desde el servidor mediante &local;settings.
- El dispositivo puede hacer ping de forma explícita en el servidor (API de /cloudprint/impresora para GCP, además de pings XMPP) no más de una vez al día (24 horas) para asegurarse de que estén sincronizados. Se recomienda aleatorizar la ventana de verificación dentro de un período de 24 a 32 horas.
- Opcional: Para los dispositivos de Cloud Print, se recomienda tener una forma manual (botón) de permitir que el usuario inicie una verificación de nuevos trabajos de impresión desde el dispositivo, pero no es obligatorio. Algunas impresoras ya lo tienen.
- Opcional. Es posible que las impresoras empresariales tengan una opción para inhabilitar completamente el descubrimiento local. En ese caso, el dispositivo DEBE actualizar esta configuración local en el servidor. La nueva configuración local DEBE estar vacía (configurar “local_discovery” como “false”), lo que significa que se puede volver a habilitar desde el servicio de GCP.
6.1.2 Diagrama de registro predeterminado
![](https://developers.google.cn/cloud-print/images/privet_image06.png?authuser=6&hl=es)
6.2. Prevención y ataques de XSSI y XSRF
En esta sección, se explicará la posibilidad de que se produzcan ataques de XSSI y XSRF en el dispositivo, y se explica cómo protegerlos de ellos (incluidas las técnicas de generación de tokens).Puedes obtener más información en el siguiente vínculo: http://googleonlinesecurity.blogspot.com/2011/05/website-security-for-webmasters.html
Por lo general, los ataques de XSSI y XSRF son posibles cuando un sitio usa mecanismos de autenticación de cookies. Si bien Google no utiliza cookies con el servicio Cloud Print, estos ataques aún son posibles. El diseño de acceso a la red local confía implícitamente en las solicitudes.
6.2.1. XSSI
Es posible que un sitio web malicioso adivine la dirección IP y el número de puerto de un dispositivo compatible con Privet y que intente llamar a la API de Privet con una etiqueta <t;src=<api name>" dentro de una etiqueta <script>:<script type="text/javascript" src="http://192.168.1.42:8080/privet/info"></script>Sin protección, los sitios web maliciosos podrían ejecutar llamadas a la API y acceder a los resultados.
Para evitar este tipo de ataque, TODAS las llamadas a la API de Privet DEBEN solicitar el encabezado “X-Privet-Token” en la solicitud. Las etiquetas de secuencia de comandos no pueden agregar encabezados para protegerse contra este tipo de ataques.
6.2.2. XSRF
http://en.wikipedia.org/wiki/Cross-site_request_forgeryUn sitio web malicioso puede adivinar la dirección IP y el número de puerto de un dispositivo compatible con Privet e intentar llamar a la API de Privet con un <iframe>, formularios o algún otro mecanismo de carga entre sitios web. Los atacantes no podrían acceder a los resultados de la solicitud, pero si esta realizaría una acción (p.ej., la impresión), podría activarla.
Para evitar este ataque, necesitamos la siguiente protección:
- Deja la API de /privet/info abierta en XSRF
- /privet/info API NO DEBE realizar ninguna acción en el dispositivo
- Usa la API de /privet/info para recibir el token x-privet
- Todas las demás API DEBEN buscar un token x-privet válido en el encabezado "X-Privet-Token".
- El token "x-privet" DEBE ser válido únicamente durante 24 horas.
Incluso si un atacante puede ejecutar la API /privet/info, no podría leer el token x-privet de la respuesta y, por lo tanto, no podría llamar a ninguna otra API.
Se recomienda generar el token XSRF con el siguiente algoritmo:
XSRF_token = base64( SHA1(device_secret + DELIMITER + issue_timecounter) + DELIMITER + issue_timecounter )
Elementos de generación del token XSRF:
- DELIMITER es un carácter especial, generalmente ":"
- issue_timecounter es una cantidad de segundos desde que algún evento (ciclo de entrenamiento para la marca de tiempo) o tiempo de inicio del dispositivo (para contadores de CPU) issue_timecounter aumenta constantemente cuando el dispositivo está en funcionamiento (consulta la verificación de token a continuación).
- SHA1: función hash que usa el algoritmo SHA1
- base64: codificación en base64
- device_secret: el secreto específico del dispositivo El secreto del dispositivo DEBE actualizarse cada vez que se reinicia.
Formas recomendadas para generar un secreto de dispositivo:
- Genera un UUID nuevo en cada reinicio
- Genera un número aleatorio de 64 bits con cada reinicio
No es necesario que el dispositivo almacene todos los tokens XSRF emitidos. Cuando el dispositivo necesita verificar un token XSRF para su validez, debe decodificar el token en base64. Obtén el issue_timecounter de la segunda mitad (cleartext) e intenta producir el hash SHA1 de device_secret + DELIMITER + issue_timecounter donde issue_timecounter es del token. Si la SHA1 generada recientemente coincide con la del token, el dispositivo ahora debe verificar si el issue_timecounter está dentro del período de validez de (24 horas) del contador de tiempo actual. Para ello, el dispositivo toma el contador de tiempo actual (por ejemplo, el contador de CPU) y resta issue_timecounter a él. El resultado DEBE ser la cantidad de segundos desde la emisión del token.
Importante: Esta es la manera recomendada de implementar la protección XSRF. Los clientes de la especificación Privet no intentarán comprender el token XSRF; en su lugar, lo tratarán como una caja negra. En la figura 6.2.3, se ilustra una forma recomendada de implementar el token X-Privet y la verificación de una solicitud típica.
6.2.3 Diagrama de secuencia de generación y token de X-Privet
![](https://developers.google.cn/cloud-print/images/privet_image03.png?authuser=6&hl=es)
6.3 Diagramas de flujo de trabajo
En esta sección, se ilustrará un flujo de trabajo en diferentes casos.6.3.1. Flujo de trabajo de impresoras listo para usar
![](https://developers.google.cn/cloud-print/images/privet_image01.png?authuser=6&hl=es)
6.3.2. Inicio de la impresora registrada
![](https://developers.google.cn/cloud-print/images/privet_image02.png?authuser=6&hl=es)
6.3.3 Flujo de trabajo para el manejo de notificaciones de XMPP
![](https://developers.google.cn/cloud-print/images/privet_image05.png?authuser=6&hl=es)
6.3.4. Comprobar el flujo de trabajo de la configuración de la impresora
![](https://developers.google.cn/cloud-print/images/privet_image00.png?authuser=6&hl=es)