Google 클라우드 프린트는 2020년 12월 31일부터 더 이상 지원되지 않습니다. 이전과 관련된 도움이 필요하면 지원 도움말을 참고하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

프라이빗

Privet은 클라우드 서비스에서 사용하는 Cloud Device Local Discovery API입니다. 이 문서는 다음 섹션으로 구성되어 있습니다.

소개: Privet 소개
검색: 로컬 검색 메커니즘
공지사항: 지역 탐색 공지사항
API: 범용 클라우드 기기용 Privet API
프린터 API: 프린터에 사용되는 Privet API
부록: 보충 다이어그램

1. 소개

클라우드 연결 기기에는 많은 이점이 있습니다. 이들은 기기가 오프라인 상태일 때 온라인 전환 서비스, 호스트 작업 대기열을 사용할 수 있으며 전 세계 어디서나 액세스할 수 있습니다. 그러나 특정 사용자가 액세스할 수 있는 클라우드 기기가 많기 때문에 위치를 기준으로 가장 가까운 기기를 찾는 방법을 제공해야 합니다. Privet 프로토콜의 목적은 클라우드 기기의 유연성을 적합한 로컬 검색 메커니즘과 바인딩하여 기기가 새로운 환경에서 쉽게 검색되도록 하는 것입니다.

이 프로토콜의 목표는 다음과 같습니다.

클라우드 기기를 로컬에서 검색 가능하도록 설정
클라우드 서비스에 클라우드 기기 등록하기
등록된 기기와 클라우드 표현을 연결
오프라인 기능 사용 설정
구현을 간소화하여 작은 기기에서도 활용 가능

Privet 프로토콜은 크게 탐색과 API라는 두 부분으로 구성됩니다. 탐색은 로컬 네트워크에서 기기를 찾는 데 사용되며 API는 기기에 대한 정보를 가져오고 몇 가지 작업을 실행하는 데 사용됩니다. 이 문서 전반에서 기기는 Privet 프로토콜을 구현하는 클라우드 연결 기기를 의미합니다.

2. 탐색

검색은 제로 DNS 기반 (mDNS + DNS-SD) 프로토콜입니다. 기기에서 IPv4 링크-로컬 주소 지정을 구현해야 합니다(MUST). 기기는 mDNS 및 DNS-SD 사양을 준수해야 합니다(MUST).

http://www.rfc-editor.org/rfc/rfc3927.txt(IPv4 링크-로컬)
http://www.rfc-editor.org/rfc/rfc4862.txt(IPv6 링크-로컬)
http://www.rfc-editor.org/rfc/rfc6762.txt(mDNS)
http://www.rfc-editor.org/rfc/rfc6763.txt(DNS-SD)

기기는 위의 사양에 따라 이름 충돌 해결을 실행해야 합니다(MUST).

2.1. 서비스 유형

DNS 서비스 검색에서는 서비스 유형에 _applicationprotocol._transportprotocol 형식을 사용합니다. Privet 프로토콜의 경우 DNS-SD의 서비스 유형은 _privet._tcp여야 합니다.

기기는 다른 서비스 유형도 구현할 수 있습니다. 기기에서 구현한 모든 서비스 유형에 동일한 서비스 인스턴스 이름을 사용하는 것이 좋습니다. 예를 들어 프린터는 '프린터 XYZ._privet._tcp" 및 '프린터 XYZ._printer._tcp" 서비스를 구현할 수 있습니다. 사용자의 설정이 간소화됩니다. 하지만 Privet 클라이언트는 "_privet._tcp"만 찾습니다.

기본 서비스 유형 외에도 기기는 해당 하위유형의 PTR 레코드를 알려야 합니다(DNS-SD 사양: 7.1 참고). 선택적 인스턴스 열거 (하위 유형)). 형식은 다음과 같아야 합니다. _<subtype>._sub._privet._tcp

현재 지원되는 유일한 기기 하위유형은 프린터입니다. 따라서 모든 프린터는 다음 두 가지 PTR 레코드를 공지해야 합니다(MUST).

_privet._tcp.local에 배포됩니다.
{0}_printer._sub._privet._tcp.local.

2.2. TXT 레코드

DNS 서비스 검색은 TXT 레코드에 서비스에 대한 선택적 정보를 추가하는 필드를 정의합니다. TXT 레코드는 키-값 쌍으로 구성됩니다. 각 키-값 쌍은 길이 바이트에서 시작하여 최대 255바이트의 텍스트가 이어집니다. 키는 첫 번째 '=' 문자 앞의 텍스트이고 값은 첫 번째 '=' 문자 뒤의 텍스트입니다. 이 사양은 레코드에 어떤 값도 허용하지 않습니다. 이러한 경우 '=' 문자가 없거나 '=' 문자 뒤에 오는 텍스트가 없습니다. (DNS-SD 사양: "6.1. DNS TXT 레코드 일반 형식 규칙" DNS TXT 레코드 형식 &6.2. DNS-SD TXT 레코드 크기').

Privet의 경우 TXT 레코드에서 기기가 다음 키-값 쌍을 전송해야 합니다. 키-값 문자열은 대소문자를 구분하지 않습니다. 예를 들어 "CS=online"와 "cs=Online"는 동일합니다. TXT 레코드의 정보는 /info API를 통해 액세스할 수 있는 정보와 동일해야 합니다 (4.1. API 섹션).

TXT 레코드 크기는 512바이트 미만으로 유지하는 것이 좋습니다.

2.2.1. txtverser

TXT 구조의 버전입니다. txtvers는 TXT 구조의 첫 번째 레코드여야 합니다. 현재 유일하게 지원되는 버전은 1입니다.

txtvers=1

2.2.2. ty

사용자가 읽을 수 있는 기기 이름을 제공합니다. 예를 들면 다음과 같습니다.

ty=Google Cloud Ready Printer Model XYZ

2.2.3. 메모 (선택사항)

사용자가 읽을 수 있는 기기 이름을 제공합니다. 예를 들면 다음과 같습니다.

note=1st floor lobby printer

참고: 이 키는 선택사항이며 건너뛰어도 됩니다. 하지만 존재하는 경우 사용자가 이 값을 수정할 수 있어야 합니다(SHOULD). 기기를 등록할 때도 동일한 설명을 사용해야 합니다.

2.2.4. URL

이 기기가 연결된 서버 URL (프로토콜 포함)입니다. 예를 들면 다음과 같습니다.

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

2.2.5. 유형

쉼표로 구분된 이 기기에서 지원하는 기기 하위유형의 목록입니다. 형식은 "type=_subtype1,_subtype2"입니다. 현재 유일하게 지원되는 기기 하위유형은 printer입니다.

type=printer

나열된 각 하위유형은 상응하는 PTR 레코드를 사용하여 광고되어야 합니다. 지원되는 서비스 하위유형마다 해당하는 항목이 하나씩 있어야 합니다. 서비스 하위유형 이름(<subtype>._sub._privet._tcp)은 기기 유형과 같아야 합니다.

2.2.6. ID

기기 ID입니다. 기기가 아직 등록되지 않은 경우 이 키가 있지만 값은 비어 있어야 합니다. 예를 들면 다음과 같습니다.

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

2.2.7. cs

기기의 현재 연결 상태를 나타냅니다. 이 사양에는 4가지 값이 정의되어 있습니다.

'온라인'은 기기가 현재 클라우드에 연결되어 있음을 나타냅니다.
'오프라인'은 기기를 로컬 네트워크에서 사용할 수 있지만 서버와 통신할 수 없음을 나타냅니다.
"connecting"는 기기가 시작 시퀀스를 실행하고 있으며 아직 완전히 온라인 상태가 되지 않음을 나타냅니다.
"not-configure'는 기기의 인터넷 액세스가 아직 구성되지 않았음을 나타냅니다. 이 값은 현재 사용되지 않지만 향후 버전의 사양에서 유용할 수 있습니다.

예를 들면 다음과 같습니다.

cs=온라인
cs=오프라인
cs=연결 중

기기가 클라우드에 등록된 경우 시작 시 서버와의 연결을 확인하여 연결 상태를 감지해야 합니다 (예: Cloud API를 호출하여 기기 설정 가져오기). 기기는 알림 채널 (예: XMPP) 연결 상태를 사용하여 이 값을 보고할 수 있습니다. 시작 시 등록되지 않은 기기는 연결 상태를 감지하기 위해 도메인을 핑할 수 있습니다 (예: 클라우드 프린트 기기의 경우 www.google.com 핑).

3. 공지사항

기기 시작, 종료 또는 상태 변경 시 기기는 mDNS 사양에 설명된 대로 공지 단계를 실행해야 합니다(MUST). 최소 1초 간격으로 상응하는 공지사항을 두 번 이상 전송해야 합니다(SHOULD).

3.1. 시작

기기 시작 시 mDNS 사양에 설명된 대로 프로브 및 공지 단계를 실행해야 합니다(MUST). 이 경우 SRV, PTR, TXT 레코드를 전송해야 합니다. 가능하면 모든 레코드를 하나의 DNS 응답으로 그룹화하는 것이 좋습니다. 그렇지 않은 경우 SRV, PTR, TXT 레코드 순서를 사용하는 것이 좋습니다.

3.2. 종료

기기가 종료되면 mDNS 문서에 설명된 대로 TTL=0으로 'goodbye 패킷'을 전송하여 모든 관련 당사자에게 알려야 합니다 (SHOULD).

3.3. 업데이트

TXT에 설명된 정보가 변경된 경우 기기에서 업데이트 알림을 보내야 합니다. 이 경우 새 TXT 레코드만 전송해도 됩니다. 예를 들어 기기가 등록된 후에는 새 기기 ID를 포함하는 업데이트 알림을 전송해야 합니다(MUST).

4. API

클라우드 기기가 검색되면 로컬 네트워크를 통해 기기와 직접 통신하도록 클라이언트 통신이 사용 설정됩니다. 모든 API는 HTTP 1.1 기반입니다. 데이터 형식은 JSON 기반입니다. API 요청은 GET 또는 POST 요청일 수 있습니다.

각 요청은 유효한 'X-Privet-Token' 헤더를 포함해야 합니다. 빈 'X-Privet-Token" 헤더는 /privet/info 요청만으로 지정할 수 있습니다 (헤더는 계속 있어야 함). "X-Privet-Token" 헤더가 없으면 기기가 다음 HTTP 400 오류로 응답해야 합니다(MUST).

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

X-Privet-Token 유일한 예외는 /info API입니다. 이를 수행하는 이유 및 토큰 생성 방법에 대한 자세한 내용은 부록 A: XSSI 및 XSRF 공격 및 방지를 참조하세요.

요청된 API가 존재하지 않거나 지원되지 않는 경우 기기에서 HTTP 404 오류를 반환해야 합니다.

4.1. API 가용성

모든 API(/info API 포함)가 노출되기 전에 기기가 서버에 접속하여 로컬 설정을 확인해야 합니다. 로컬 설정은 재시작 시 보존되어야 합니다(MUST). 서버를 사용할 수 없는 경우 마지막으로 알려진 로컬 설정이 사용됩니다. 기기가 아직 등록되지 않은 경우 기본 설정을 따라야 합니다.

클라우드 프린트 기기는 로컬 설정을 등록, 수신, 업데이트하려면 아래 단계를 따라야 합니다(MUST).

4.1.1. 등록

기기를 등록할 때 'local_settings" 매개변수를 다음과 같이 지정해야 합니다.

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

다음 설정을 지정할 수 있습니다.

값 이름	값 유형	설명
local_discovery	불리언	로컬 검색 기능이 허용되는지 여부를 나타냅니다. "false"인 경우 모든 로컬 API(/info 포함) 및 DNS-SD 검색을 사용 중지해야 합니다. 기본적으로 새로 등록하는 기기는 'true'를 통과해야 합니다.
액세스_토큰_사용 설정됨	부울 (선택사항)	로컬 네트워크에 /accesstoken API가 노출되어야 하는지 여부를 나타냅니다. 기본적으로 'true'여야 합니다.
프린터/로컬_인쇄_사용	부울 (선택사항)	로컬 인쇄 기능 (/printer/createjob, /printer/submitdoc, /printer/jobstate)이 로컬 네트워크에 노출되어야 하는지를 나타냅니다. 기본적으로 'true'여야 합니다.
프린터/전환_인쇄_사용	부울 (선택사항)	로컬 인쇄에서 변환을 위해 서버로 작업을 전송할 수 있는지를 나타냅니다. 로컬 인쇄가 사용 설정된 경우에만 적용됩니다.
xmpp_timeout_value	int (선택사항)	XMPP 채널 핑 사이의 시간(초)을 나타냅니다. 기본적으로 300 (5분) 이상이어야 합니다.

중요: 선택사항인 값이 없으면 상응하는 기능이 기기에서 완전히 지원되지 않는다는 의미입니다.

4.1.2. 시작

기기 시작 시 서버에 문의하여 로컬 네트워크에 노출할 수 있는 API를 확인해야 합니다. 클라우드 프린트에 연결된 프린터의 경우 다음을 호출해야 합니다.

/cloudprint/printer?printerid=<printer_id>

또는

/cloudprint/list

/Buganizer/printer를 사용하는 것이 선호되지만 두 옵션 모두 사용 가능합니다.

이 API는 로컬 API 설정을 비롯한 현재 기기 매개변수를 반환합니다. 서버의 응답 형식은 다음과 같습니다.

"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" 객체는 현재 적용 중인 설정을 나타냅니다.

"pending" 객체는 기기에 적용되어야 하는 설정을 나타냅니다 (이 객체는 누락될 수 있음).

기기가 '대기 중' 설정을 확인하면 상태를 업데이트해야 합니다 (아래 참고).

4.1.3 업데이트

설정 업데이트가 필요한 경우 XMPP 알림이 기기로 전송됩니다. 알림은 다음과 같은 형식으로 표시됩니다.

<device_id>/update_settings

이러한 알림을 수신하면 기기는 서버에 쿼리하여 최신 설정을 가져와야 합니다(MUST). 클라우드 프린트 기기는 다음을 사용해야 합니다(MUST).

/cloudprint/printer?printerid=<printer_id>

기기가 /Buganizer/printer API의 결과로(시작 시 또는 알림으로 인해) '대기 중' 섹션을 확인하면 새로운 설정을 기억하도록 내부 상태를 업데이트해야 합니다(MUST). 서버 API를 호출하여 새 설정을 확인해야 합니다(MUST). 클라우드 프린터의 경우 기기는 등록 시와 같이 /Buganizer/update API를 호출하고 'local_settings" 매개변수를 사용해야 합니다.

XMPP 채널에 다시 연결할 때 기기는 /Buganizer/printer API를 호출하여 마지막 설정 이후 로컬 설정이 변경되었는지 확인해야 합니다(MUST).

4.1.3.1 로컬 설정 대기 중

기기가 서버 API를 호출하는 데 사용하는 "local_settings" 매개변수에는 '대기 중' 섹션을 포함해서는 안 됩니다(MUST NOT).

4.1.3.2 로컬 설정 현재

기기만 'local_settings"의 '현재' 섹션을 변경할 수 있습니다. 나머지는 모두 '대기 중' 섹션을 변경한 다음 기기에 의해 '현재' 섹션에 변경사항이 적용될 때까지 기다립니다.

4.1.4 오프라인

시작 중에 서버에 연결할 수 없는 경우 알림 후 기기에서 마지막으로 알려진 로컬 설정을 사용해야 합니다(MUST).

4.1.5 서비스에서 기기 삭제

기기가 서비스에서 삭제된 경우 (예: GCP) XMPP 알림이 기기로 전송됩니다. 알림은 다음과 같은 형식으로 표시됩니다.

<device_id>/delete

이러한 알림을 받으면 기기는 서버로 이동해서 상태를 확인해야 합니다(MUST). 클라우드 프린트 기기는 다음을 사용해야 합니다(MUST).

/cloudprint/printer?printerid=<printer_id>

기기는 기기=프린터 설명 없이 성공=거짓인 성공적인 HTTP 응답을 수신해야 합니다(MUST). 서버에서 서버가 삭제되었으며 기기가 사용자 인증 정보를 삭제하고 기본 초기화 모드로 이동해야 합니다(MUST).

기기가 /Buganizer/printer API(시작, 업데이트 설정 알림, 일일 핑)의 결과로 삭제되었다는 응답을 받을 때 항상 사용자 인증 정보를 삭제하고 기본 모드로 전환해야 합니다(MUST).

4.2. /privet/info API

정보 API는 필수이며 모든 기기에서 구현해야 합니다(MUST). "/privet/info" url: GET /privet/info HTTP/1.1에 대한 HTTP GET 요청입니다.

Info API는 지원되는 기기 및 기능에 관한 기본 정보를 반환합니다. 이 API는 XSRF 공격에 취약하므로 기기 상태를 변경하거나 작업을 실행해서는 안 됩니다(MUST NOT). 유일하게 빈 'X-Privet-Token' 헤더를 보유할 수 있는 API입니다. 클라이언트는 "X-Privet-Token" 헤더가 X-Privet-Token으로 설정된 /privet/info API를 호출해야 합니다. "

정보 API는 탐색 중에 TXT 레코드에서 사용 가능한 데이터와 일치하는 데이터를 반환해야 합니다(MUST).

4.2.1. 입력

/privet/info API에는 입력 매개변수가 없습니다.

4.2.2. Return

/privet/info API는 기기 및 지원되는 기능에 관한 기본 정보를 반환합니다.

TXT 열에 DNS-SD TXT 레코드의 해당 입력란이 표시됩니다.

값 이름	값 유형	설명	TXT
version	문자열	지원되는 가장 높은 API 버전 (major.minor)으로 현재 1.0입니다.
이름	문자열	사람이 읽을 수 있는 기기 이름입니다.	ty
설명	문자열	(선택사항) 기기 설명 사용자가 수정할 수 있어야 합니다(SHOULD).	메모
url	문자열	이 기기에서 통신 중인 서버의 URL입니다. URL에는 프로토콜 사양(예: https://www.google.com/Buganizer)이 포함되어야 합니다(MUST).	url
유형	문자열 목록	지원되는 기기 유형 목록입니다.	유형
ID	문자열	기기 ID, 기기가 아직 등록되지 않은 경우 비어 있음	ID
기기 상태	문자열	기기 상태입니다. 유휴는 기기가 준비되었음을 의미합니다. 처리 중은 기기가 다른 작업을 하고 있으며 일정 시간 동안 기능이 제한될 수 있음을 의미합니다. 중지는 기기가 작동하지 않고 사용자 개입이 필요함을 의미합니다.
연결_상태	문자열	서버 연결 상태 (base_url) 온라인 - 연결 가능 오프라인 - 연결 없음 연결 - 시작 단계 수행 구성되지 않음 - 연결이 아직 구성되지 않음 등록된 기기가 알림 채널의 상태 (예: XMPP 연결 상태)에 따라 연결 상태를 보고할 수 있습니다.	cs
제조업체	문자열	기기 제조업체 이름
모델	문자열	기기 모델
일련번호	문자열	고유한 기기 식별자입니다. 이 사양에서 UUID여야 합니다(MUST). (GCP 1.1 사양) (선택사항) 모든 클라이언트에서 동일한 기기를 식별할 수 있도록 모든 기기에서 동일한 일련번호 ID를 사용하는 것이 좋습니다. 예를 들어 IPP를 구현하는 프린터가 "printer-device-id" 필드에 이 일련번호 ID를 사용할 수 있습니다.
펌웨어	문자열	기기 펌웨어 버전
uptime	int	기기 부팅으로부터의 시간(초)입니다.
설정_URL	문자열	(선택사항) 설정 안내가 포함된 페이지의 URL (프로토콜 포함)
support_url	문자열	(선택사항) 지원이 포함된 페이지의 URL (프로토콜 포함), FAQ 정보
업데이트_URL	문자열	(선택사항) 업데이트 펌웨어 안내가 포함된 페이지의 URL (프로토콜 포함)
X-privet-token	문자열	XSSI 및 XSRF 공격을 방지하기 위해 모든 API에 전달되어야 하는 X-Privet-Token 헤더의 값입니다. 자세한 내용은 6.1. 을 참조하세요.
api	API 설명	지원되는 API 목록 (아래에 설명되어 있음)
시맨틱_상태	JSON	(선택사항) CloudDeviceState 형식의 기기 시맨틱 상태입니다.

api - 로컬 네트워크를 통해 사용 가능한 API 목록이 포함된 JSON 목록입니다. 로컬 네트워크를 통해서는 모든 API를 동시에 사용할 수 있는 것은 아닙니다. 예를 들어 새로 연결된 기기는 /register API만 지원해야 합니다.

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

기기 등록이 완료되면 기기에서 /register API 지원을 중지해야 합니다(SHOULD). 또한 기기는 서비스에 문의하여 로컬 네트워크를 통해 노출될 수 있는 API를 제공해야 합니다. 예를 들면 다음과 같습니다.

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

현재 사용할 수 있는 API는 다음과 같습니다.

/privet/register - 로컬 네트워크를 통한 기기 등록용 API 자세한 내용은 /privet/register API를 참고하세요. 기기가 클라우드에 성공적으로 등록되면 이 API를 숨겨야 합니다(MUST).
/privet/accesstoken - 기기에서 액세스 토큰을 요청하는 API (자세한 내용은 /privet/accesstoken API 참고)
/privet/capabilities - 기기 기능을 검색하는 API (자세한 내용은 /privet/capabilities API 참고)
/privet/printer/* - 기기 유형 'printer"에 해당하는 API입니다. 자세한 내용은 프린터별 API를 참고하세요.

다음은 /privet/info 응답의 예입니다. 이미 등록된 기기이므로 /privet/register API가 없습니다.

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

다음은 잉크가 부족한 프린터의 /privet/info 응답의 예입니다(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. 오류

/privet/info API는 X-Privet-Token 헤더가 없는 경우에만 오류를 반환해야 합니다. HTTP 400 오류여야 합니다(MUST).

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

4.3. /privet/register API

/privet/register API는 선택사항입니다. HTTP POST 요청입니다. /privet/register API는 유효한 X-Privet-Token 헤더를 확인해야 합니다(MUST). 기기가 "/privet/register" url에 이 API를 구현해야 합니다(MUST).

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

기기는 현재 익명 등록이 허용되는 경우에만 /privet/register API를 노출해야 합니다. 예를 들면 다음과 같습니다.

기기가 켜져 있거나 기기에서 특수 버튼을 클릭한 후 아직 등록되지 않았다면 로컬 네트워크의 사용자가 프린터를 요청할 수 있도록 /privet/register API를 노출해야 합니다.
등록이 완료되면 로컬 네트워크에 있는 다른 사용자가 기기를 회수할 수 없도록 기기 /privet/register API 노출이 중지됩니다.
기기 등록 방법이 다를 수 있으므로 /privet/register API를 아예 노출해서는 안 됩니다 (예: Chrome 클라우드 프린트 커넥터).

등록 프로세스는 3단계로 구성됩니다 (클라우드 프린트에 대한 익명 등록 참고).

익명 등록 절차를 시작합니다.
클라이언트는 /privet/register API를 호출하여 이 프로세스를 시작합니다. 이때 사용자 확인을 기다려야 할 수도 있습니다.
클레임 토큰 가져오기

클라이언트는 기기를 계속 사용할 준비가 되었는지 확인하기 위해 폴링합니다. 기기가 준비되면 서버에 요청을 보내 등록 토큰과 등록 URL을 가져옵니다. 수신된 토큰과 URL은 클라이언트에 반환되어야 합니다(SHOULD). 이 단계 중에 기기가 등록 초기화를 위한 또 다른 호출을 수신하면 기기는 다음을 실행해야 합니다.

등록 절차를 시작한 사용자와 동일한 사용자라면 이전 데이터를 모두 삭제한 후 새 등록 프로세스를 시작합니다.
다른 사용자인 경우 device_Busy 및 30초 제한 시간을 반환합니다.

등록 절차를 완료하세요.

클라이언트는 기기의 소유권을 주장한 후 등록을 완료하도록 기기에 알려야 합니다. 등록 절차가 완료되면 기기에서 새로 획득한 기기 ID를 비롯한 업데이트 공지를 보내야 합니다.

참고: 기기에서 /privet/register API 호출을 처리할 때는 다른 /privet/register API 호출이 동시에 처리될 수 없습니다. 기기가 device_Busy 오류 및 30초 시간 제한을 반환해야 합니다(MUST).

기기 등록을 위한 사용자 확인을 적극 권장합니다. 구현되면 기기는 /privet/register?action=start API 호출을 수신한 후 사용자 확인을 기다려야 합니다. 클라이언트는 사용자 확인이 완료되고 클레임 토큰을 사용할 수 있는지 확인하기 위해 /privet/register?action=getClaimToken API를 호출합니다. 사용자가 기기에서 등록을 취소하면(예: 취소 버튼 누르기) user_cancel 오류가 반환되어야 합니다(MUST). 사용자가 특정 기간 내에 등록을 확인하지 않았다면 Confirm_timeout 오류를 반환해야 합니다(MUST). 자세한 내용은 기본 섹션을 참조하세요.

4.3.1 입력

/privet/register API에는 다음과 같은 입력 매개변수가 있습니다.

이름	값
작업	다음 중 하나일 수 있습니다. start - 등록 프로세스 시작 getClaimToken - 기기의 클레임 토큰 검색 cancel - 등록 프로세스 취소 complete - 등록 프로세스 완료
user	이 기기의 소유권을 주장할 사용자의 이메일

기기는 모든 작업의 이메일 주소(시작, getClaimToken, 취소, 완료)가 일치하는지 확인해야 합니다(MUST).

4.3.2 Return

/privet/register API는 다음 데이터를 반환합니다.

값 이름	값 유형	설명
작업	문자열	입력 매개변수와 동일한 작업
user	문자열 (선택사항)	입력 매개변수와 동일한 사용자 (입력에서 생략된 경우 누락될 수 있음)
토큰	문자열 (선택사항)	등록 토큰(&='
소유권 주장_URL	문자열 (선택사항)	등록 URL("getClaimToken" 응답의 경우 필수, 'start', 'complete', 'cancel"의 경우 생략됨) 클라우드 프린터의 경우 서버에서 수신한 "complete_Invitation_url"이어야 합니다.
자동화된_소유권 주장_URL	문자열 (선택사항)	등록 URL("getClaimToken" 응답의 경우 필수, 'start', 'complete', 'cancel"의 경우 생략됨) 클라우드 프린터의 경우 서버에서 수신된 '자동 연결_초대_URL'이어야 합니다.
기기_ID	문자열 (선택사항)	새 기기 ID("응답에서 생략됨, "complete"의 경우 필수)

기기는 등록이 완료된 후에만 /privet/info API 응답에 기기 ID를 반환해야 합니다(MUST).

예시 1:

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

예 2:

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

예 3:

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

4.3.3 오류

/privet/register API는 다음 오류를 반환할 수 있습니다 (자세한 내용은 오류 섹션 참고).

오류	설명
기기 사용 중	기기가 사용 중이어서 요청된 작업을 수행할 수 없습니다. 제한 시간 후에 다시 시도하세요.
대기_사용자_액션	"getClaimToken"에 대한 응답으로 이 오류는 기기가 아직 사용자 확인 대기 중이므로 시간 초과 후에 다시 시도해야 함을 나타냅니다.
user_cancel	사용자가 기기에서 등록 프로세스를 명시적으로 취소했습니다.
확인_시간 초과	사용자 확인 시간이 초과되었습니다.
잘못된_작업	잘못된 작업이 호출됩니다. 예를 들어 클라이언트가 action=start 및 action=getClaimToken을 호출하기 전에 action=complete를 호출한 경우
잘못된 매개변수	요청에 잘못된 매개변수가 지정되었습니다. 알 수 없는 매개변수는 향후 호환성을 위해 안전하게 무시되어야 합니다. 예를 들어 클라이언트가 action=unknown 또는 user=를 호출한 경우 이 값을 반환합니다.
기기_구성_오류	기기 측 날짜/시간 (또는 기타 설정)이 잘못되었습니다. 사용자가 기기 내부 웹사이트로 이동하여 기기 설정을 구성해야 합니다.
오프라인	기기가 현재 오프라인 상태여서 서버와 연결할 수 없습니다.
서버 오류	등록 프로세스 중에 서버 오류가 발생했습니다.
잘못된_x_privet_token	요청에서 X-Privet-Token이 잘못되었거나 비어 있습니다.

등록이 완료되면 기기에서 /privet/register API 노출을 중지해야 합니다(MUST). 기기가 /privet/register API를 노출하지 않으면 HTTP 404 오류를 반환해야 합니다(MUST). 따라서 기기가 이미 등록된 경우 이 API를 호출하면 404를 반환해야 합니다. X-Privet-Token 헤더가 없으면 기기에서 HTTP 400 오류를 반환해야 합니다(MUST).

4.4. /privet/accesstoken API

/privet/accesstoken API는 선택사항입니다. HTTP GET 요청입니다. /privet/accesstoken API는 유효한 &Xt-Privet-Token" 헤더를 확인해야 합니다(MUST). 기기는 '/privet/accesstoken" url'에서 이 API를 구현해야 합니다(MUST).

GET /privet/accesstoken HTTP/1.1

기기가 /accesstoken API 호출을 수신하면 서버를 호출하여 지정된 사용자의 액세스 토큰을 검색하고 토큰을 클라이언트에 반환해야 합니다. 이후 클라이언트에서 액세스 토큰을 사용해 클라우드를 통해 이 기기에 액세스합니다.

클라우드 프린트 기기는 다음 API를 호출해야 합니다(MUST).

/cloudprint/proximitytoken

를 실행하고 로컬 API에서 'printer_id>' 및 'user' 매개변수를 전달합니다. 성공하면 서버 응답에 다음 객체가 포함됩니다.

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

클라우드 프린트 기기는 응답의 'proximity_token" 객체의 값을 로컬 /privet/accesstoken API 호출에 전달해야 합니다(MUST). 기기가 모든 사양 (이 사양에서 설명되지 않은 매개변수 포함)을 전달할 수 있다면 이보다 유리합니다 (미래에 대비).

4.4.1. 입력

/privet/accesstoken API에는 다음과 같은 입력 매개변수가 있습니다.

이름	값
user	이 액세스 토큰을 사용하려는 사용자의 이메일입니다. 요청에서 비어 있을 수 있습니다.

4.4.2. Return

/privet/accesstoken API는 다음 데이터를 반환합니다.

값 이름	값 유형	설명
token	문자열	서버에서 반환한 액세스 토큰
user	문자열	입력 매개변수와 동일한 사용자
expires_in	int	이 토큰이 만료되기까지의 시간(초)입니다. 서버로부터 수신되어 이 응답을 전달합니다.

예:

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

4.4.3 오류

/privet/accesstoken API는 다음 오류를 반환할 수 있습니다 (자세한 내용은 오류 섹션 참고).

오류	설명
오프라인	기기가 현재 오프라인 상태이며 서버와 통신할 수 없습니다.
access_denied	권한이 부족합니다. 액세스가 거부되었습니다. 서버에서 요청을 명시적으로 거부한 경우 기기에서 이 오류를 반환해야 합니다.
잘못된 매개변수	요청에 잘못된 매개변수가 지정되었습니다. 알 수 없는 매개변수는 향후 호환성을 위해 안전하게 무시되어야 합니다. 클라이언트가 /accesstoken?user= 또는 /accesstoken을 호출한 경우를 예로 들 수 있습니다.
서버 오류	서버 오류입니다.
잘못된_x_privet_token	요청에서 X-Privet-Token이 잘못되었거나 비어 있습니다.

기기가 /privet/accesstoken API를 노출하지 않는 경우 HTTP 404 오류를 반환해야 합니다(MUST). X-Privet-Token 헤더가 없으면 기기에서 HTTP 400 오류를 반환해야 합니다(MUST).

4.5. /privet/capabilities API

/privet/capabilities API는 선택사항입니다. HTTP GET 요청입니다. /privet/capabilities API는 유효한 &Xt-Privet-Token" 헤더를 확인해야 합니다(MUST). 기기는 '/privet/capabilities" URL'에서 이 API를 구현해야 합니다(MUST).

GET /privet/capabilities HTTP/1.1

기기는 /capabilities API 호출을 받을 수 있고 가능한 경우 서버에 문의하여 업데이트된 기능을 가져와야 합니다(SHOULD). 예를 들어 프린터가 클라우드 프린트 서비스를 통해 자체적으로 수신된 인쇄 작업(로컬로 수신됨)을 지원하는 경우 클라우드 프린트 서비스가 반환하는 기능을 반환해야 합니다. 이 경우 클라우드 프린트에서 작업을 프린터로 전송하기 전에 실행할 수 있는 새로운 기능을 추가하여 원본 프린터 기능을 변경할 수 있습니다. 가장 일반적인 경우는 지원되는 문서 유형 목록입니다. 프린터가 오프라인인 경우 지원되는 문서 유형을 반환해야 합니다. 하지만 프린터가 온라인 상태이고 클라우드 프린트에 등록된 경우 지원되는 유형 중 하나인 '*/*"를 반환해야 합니다. 이 경우 클라우드 프린트 서비스가 필요한 변환을 수행합니다. 오프라인 인쇄의 경우 프린터는 최소한 'image/pwg-raster" 형식을 지원해야 합니다.

4.5.1. 입력

/privet/capabilities API에는 다음과 같은 입력 매개변수가 있습니다.

이름	값
오프라인	(선택사항) '오프라인=1'만 가능합니다. 이 경우 기기가 오프라인 사용을 위한 기능을 반환해야 합니다 (기능이 '온라인' 기능과 다른 경우).

4.5.2. Return

/privet/capabilities API는 클라우드 기기 설명 (CDD) JSON 형식으로 기기 기능을 반환합니다 (자세한 내용은 CDD 문서 참고). 프린터는 최소한 여기에서 지원되는 유형 목록을 반환해야 합니다(MUST). 예를 들어 현재 온라인에 있는 클라우드 지원 프린터는 최소한 다음과 같은 결과를 반환할 수 있습니다.

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

서버와의 연결이 끊기면 다음 결과가 반환될 수 있습니다.

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

참고: 프린터는 지원되는 콘텐츠 유형 우선순위를 순서대로 표시합니다. 예를 들어 위 샘플에서 프린터는 'image/pwg-raster" 및 'image/jpeg"보다 'application/pdf' 데이터를 선호하도록 지정합니다. 가능한 경우 고객은 프린터 우선순위를 준수해야 합니다(자세한 내용은 CDD 문서 참조).

4.5.3. 오류

/privet/capabilities API가 다음 오류를 반환할 수 있습니다 (자세한 내용은 오류 섹션 참고).

오류	설명
잘못된_x_privet_token	요청에서 X-Privet-Token이 잘못되었거나 비어 있습니다.

기기가 /privet/capabilities API를 노출하지 않는 경우 HTTP 404 오류를 반환해야 합니다(MUST). X-Privet-Token 헤더가 없으면 기기에서 HTTP 400 오류를 반환해야 합니다.

4.6. 오류

위 API에서 오류는 다음과 같은 형식으로 반환됩니다.

값 이름	값 유형	설명
error	문자열	오류 유형 (API별로 정의됨)
설명	문자열 (선택사항)	사람이 읽을 수 있는 오류 설명입니다.
server_api	문자열 (선택사항)	서버 오류 발생 시 이 필드에는 실패한 서버 API가 포함됩니다.
서버 코드	int (선택사항)	서버 오류 발생 시 이 필드에는 서버가 반환한 오류 코드가 포함됩니다.
server_http_code	int (선택사항)	서버 HTTP 오류 발생 시 이 필드에는 반환되는 HTTP 오류 코드 서버가 포함됩니다.
시간 제한	int (선택사항)	클라이언트가 재시도하기 전에 대기하는 시간(초)입니다(복구 가능한 오류만 해당). 클라이언트는 이 값에서 실제 시간 초과를 20% +

X-Privet-Token 헤더가 누락된 경우 모든 API가 HTTP 400 오류를 반환해야 합니다(MUST).

HTTP/1.1 400 X-Privet-Token 헤더가 누락되었습니다.

예시 1:

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

예시 2:

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

5. 프린터 API

이 프로토콜에서 지원하는 기기 유형 중 하나는 유형 프린터입니다. 이 유형을 지원하는 기기는 프린터와 관련된 일부 기능을 구현할 수 있습니다(MAY). 클라우드 지원 서버를 통해 클라우드 인쇄 서버를 통해 인쇄하는 것이 가장 좋습니다.

경우에 따라 클라이언트는 로컬에서 문서를 보내야 할 수 있습니다. 클라이언트가 Google ID를 가지고 있지 않거나 클라우드 프린트 서버와 연결할 수 없는 경우에 필요할 수 있습니다. 이러한 경우 인쇄 작업이 로컬에 프린터로 제출됩니다. 그러면 프린터에서 클라우드 인쇄 서비스를 작업 대기열 생성 및 변환에 사용합니다. 클라우드를 통해 제출된 작업이므로 프린터에서 로컬에 제출한 작업을 클라우드 프린트 서비스에 다시 게시한 후 요청합니다. 이 프로세스는 서비스 (변환) 및 인쇄 작업 관리/추적 측면에서 유연한 사용자 환경을 제공합니다.

클라우드 프린트 서비스에서 변환을 구현하므로 프린터는 지원되는 콘텐츠 유형 목록 중에서 모든 입력 형식("*/*")을 지원해야 합니다(SHOULD).

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

경우에 따라서는 완전 오프라인 솔루션이 필요하기도 합니다. 프린터가 제한된 수의 입력 형식을 지원하므로 클라이언트가 기본적으로 지원되는 몇 가지 프린터 형식으로 문서를 변환해야 합니다.

이 사양에서는 모든 프린터가 오프라인 인쇄 케이스에 PWG Raster ("image/pwg-raster") 형식 이상을 지원해야 합니다. 프린터가 다른 형식 (예: JPEG)을 지원할 수도 있고 클라이언트가 지원하는 경우 이 형식으로 문서를 전송할 수도 있습니다. 프린터가 /capabilities API를 통해 지원되는 유형을 노출해야 합니다(MUST). 예를 들면 다음과 같습니다.

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

클라이언트가 로컬 네트워크를 통해 인쇄를 시작하는 방법에는 두 가지가 있습니다.

간단한 인쇄 - 클라이언트가 로컬 네트워크를 통해 /submitdoc API로 문서를 전송합니다(Job_id 매개변수를 지정하지 않음). 제출된 문서는 기본 인쇄 티켓 설정을 사용하여 인쇄되며 인쇄 작업 상태가 필요하지 않습니다. 프린터가 이러한 유형의 인쇄만 지원하는 경우 /privet /info API 응답에/submitdoc API만 알려야 합니다(MUST).

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

고급 인쇄 - 클라이언트는 먼저 유효한 CJT 작업 티켓과 함께 /privet/printer/createjob API를 호출하여 프린터에서 인쇄 작업을 만들어야 합니다. 프린터가 인쇄 티켓을 메모리에 저장하고 작업 ID를 클라이언트에 다시 반환해야 합니다(MUST). 그런 다음 클라이언트는 /printer/submitdoc API를 호출하고 이전에 수신된 job_id를 지정합니다. 이때 프린터가 인쇄를 시작합니다. 클라이언트는 /privet/printer/jobstate API를 호출하여 프린터를 인쇄 작업 상태에 대해 폴링합니다.

멀티 클라이언트 환경에서는 이 API의 호출 방식을 보장하지 않습니다. 한 클라이언트가 다른 클라이언트의 /createjob->/submitdoc 호출 간에 /createjob을 호출할 수 있습니다. 교착 상태를 없애고 사용성을 개선하려면 프린터에 대기 중인 인쇄 작업 (최소 3~5개)의 소규모 대기열을 두는 것이 좋습니다.

/createjob은 큐에서 사용 가능한 첫 번째 위치를 차지합니다.
큐의 작업 수명은 5분 이상이어야 합니다.
대기열의 모든 자리를 차지하면 인쇄되지 않은 가장 오래된 작업이 삭제되고 새 작업이 그곳에 배치됩니다.
현재 기기에 인쇄 중인 인쇄 작업 (단순 또는 고급 인쇄)이 있는 경우 /submitdoc에서 Busy 상태를 반환하고 시간 초과를 제안하여 이 인쇄 작업을 다시 시도해야 합니다.
/submitdoc가 교체 또는 시간 초과로 인해 큐에서 삭제된 작업을 나타내는 경우 프린터에서 invalid_print_job 오류를 반환하고 클라이언트는 /createjob 단계에서 프로세스를 다시 시도합니다. 클라이언트는 최대 5초의 임의 시간 제한 기간이 지나야 다시 시도할 수 있습니다.

메모리 제약으로 인해 기기에 대기 중인 여러 작업이 저장되지 않는 경우 인쇄 작업의 큐가 1개 길어질 수 있습니다. 위의 프로토콜과 동일한 프로토콜을 따라야 합니다. 작업이 완료되거나 오류가 발생한 후에는 프린터가 작업 상태에 대한 정보를 최소 5분 동안 저장해야 합니다. 완료된 작업 상태를 저장하기 위한 큐 크기는 10 이상이어야 합니다. 저장해야 하는 작업 상태가 더 있는 경우 5분 제한 시간 전에 가장 오래된 작업 상태가 큐에서 삭제될 수 있습니다.

참고: 현재는 클라이언트가 작업 상태를 폴링합니다. 인쇄 작업 상태가 변경되면 향후에 프린터에서 TXT DNS 알림을 전송하도록 요구할 수 있습니다.

5.1. /privet/printer/createjob API

/privet/printer/createjob API는 선택사항입니다 (위의 간단한 인쇄 참고). HTTP POST 요청입니다. /privet/printer/createjob API는 유효한 &Xt-Privet-Token" 헤더를 확인해야 합니다(MUST). 기기는 "/privet/printer/createjob" URL에서 이 API를 구현해야 합니다(MUST).

POST /privet/printer/createjob HTTP/1.1

/privet/printer/createjob API 호출을 수신하면 프린터가 새 인쇄 작업 ID를 만들어 수신된 인쇄 티켓을 CJT 형식으로 저장하고 인쇄 작업 ID를 클라이언트에 다시 반환해야 합니다(MUST).

5.1.1. 입력

/privet/printer/createjob API에는 URL에 입력 매개변수가 없습니다. 요청 본문에는 CJT 형식의 인쇄 작업 티켓 데이터가 포함되어야 합니다.

5.1.2. Return

/privet/printer/createjob API는 다음 데이터를 반환합니다.

값 이름	값 유형	설명
job_id	문자열	새로 생성된 인쇄 작업의 ID입니다.
expires_in	int	인쇄 작업이 유효한 시간(초)입니다.

예:

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

5.1.3. 오류

/privet/printer/createjob API는 다음 오류를 반환할 수 있습니다 (자세한 내용은 오류 섹션 참조).

오류	설명
잘못된_티켓	제출된 인쇄 티켓이 잘못되었습니다.
프린터_바쁨	프린터가 사용 중이므로 현재 /createjob을 처리할 수 없습니다. 제한 시간 후에 다시 시도하세요.
프린터_오류	프린터가 오류 상태이며 수정하려면 사용자 상호작용이 필요합니다. 설명에는 자세한 설명이 포함되어야 합니다 (예: 트레이 1의 용지 걸림).
잘못된_x_privet_token	요청에서 X-Privet-Token이 잘못되었거나 비어 있습니다.

기기가 /privet/printer/createjob을 노출하지 않으면 HTTP 404 오류를 반환해야 합니다(MUST). X-Privet-Token 헤더가 없으면 기기에서 HTTP 400 오류를 반환해야 합니다(MUST).

5.2. /privet/printer/submitdoc API

로컬 네트워크를 통한 인쇄 (오프라인 또는 클라우드 프린트에 다시 게시)를 구현하려면 /privet/printer/submitdoc API가 필요합니다. HTTP POST 요청입니다. /privet/printer/submitdoc API는 유효한 &X-Privet-Token" 헤더를 확인해야 합니다(MUST). 기기는 "/privet/printer/submitdoc" url에서 이 API를 구현해야 합니다(MUST).

POST /privet/printer/submitdoc HTTP/1.1

/privet/printer/submitdoc API 호출을 수신하면 프린터가 인쇄를 시작해야 합니다. 인쇄를 시작할 수 없는 경우 오류가 발생한 후 프린터에서 사용 중인 오류를 확인하고 다시 시도하기 전에 클라이언트에서 권장되는 제한 시간 동안 대기해야 합니다.

프린터가 내부 버퍼의 일부 데이터를 저장할 수 없는 경우 TCP 메커니즘을 사용하여 문서의 일부를 출력할 때까지 데이터 전송 속도를 저하시켜 버퍼의 일부를 다시 사용할 수 있도록 해야 합니다(SHOULD). 예를 들어 프린터가 TCP 레이어에 windowsize=0을 설정하면 클라이언트가 대기하게 됩니다.

문서를 프린터로 제출하는 데 상당한 시간이 걸릴 수 있습니다. 클라이언트는 인쇄가 진행되는 동안 프린터와 작업 (고급 인쇄)의 상태를 확인할 수 있어야 합니다. 그렇게 하려면 프린터가 클라이언트가 /privet/info 및 /privet/printer/jobstate API를 호출하는 동안에 /privet/printer/submitdoc API 호출을 처리하는 것을 허용해야 합니다. 모든 스레드가 기본 스레드가 /privet/info 및/privet /printer/jobstate API를 사용하여 프린터 및 작업 상태를 확인할 수 있도록 새 스레드를 시작하여 /privet/printer/submitdoc API 호출을 실행하는 것이 좋습니다.

참고: 로컬 인쇄 작업이 완료되거나 취소되면 회계 및 사용자 환경을 위해 작업의 최종 상태를 /Buganizer/submit 인터페이스에 보고하는 것이 좋습니다 (향후 이 사양의 필수 버전도 필요함). 매개변수 'printterid', 'title', 'contentType', 'final_semantic_state'(PrintJobState 형식)는 필수사항이고 매개변수 &tagt(반복 매개변수) 및 티켓의 작업 티켓 매개변수는 필수사항입니다. 제공된 PrintJobState는 실제로 최종이어야 합니다. 즉, 유형이 DONE 또는 ABORTED여야 하며, 종료된 경우에는 원인을 제공해야 합니다 (자세한 내용은 JobState 참조). 또한 로컬 인쇄 작업을 보고하기 위해 /Buganizer/submit 인터페이스를 사용하는 것은 사양에서 언급되지 않습니다. 이 섹션의 목적은 '콘텐츠' 매개변수에 제공된 문서에 인쇄 작업을 제출하는 용도로 사용하는 것을 설명하기 위한 것이기 때문입니다.

5.2.1. 입력

/privet/printer/submitdoc API에는 다음과 같은 입력 매개변수가 있습니다.

이름	값
job_id	(선택사항) 인쇄 작업 ID입니다. 간단한 인쇄 사례에서는 생략할 수 있습니다(위 참고). 프린터에서 반환한 것과 일치해야 합니다.
사용자 이름	(선택사항) 사람이 읽을 수 있는 사용자 이름입니다. 이는 확정된 것이 아니며 인쇄 작업 주석에만 사용해야 합니다. 클라우드 프린트 서비스에 작업이 다시 게시되는 경우 이 문자열을 클라우드 프린트 작업에 연결해야 합니다.
고객 이름	(선택사항) 요청하는 클라이언트 애플리케이션의 이름입니다. 표시 목적으로만 사용됩니다. 클라우드 프린트 서비스에 작업이 다시 게시되는 경우 이 문자열을 클라우드 프린트 작업에 연결해야 합니다.
작업 이름	(선택사항) 기록할 인쇄 작업의 이름입니다. 클라우드 프린트 서비스에 작업이 다시 게시되는 경우 이 문자열을 클라우드 프린트 작업에 연결해야 합니다.
오프라인	(선택사항) '오프라인=1"만 가능합니다. 이 경우 프린터는 오프라인 인쇄를 시도해야 합니다 (클라우드 프린트 서버에 다시 게시하지 마세요).

요청 본문에는 인쇄를 위한 유효한 문서가 포함되어야 합니다. "Content-Length"에는 올바른 요청 길이가 포함되어야 합니다. "Content-Type" 헤더는 문서 MIME 유형으로 설정되고 CDD의 유형 중 하나와 일치해야 합니다 (CDD가 "*/*"를 지정하지 않는 경우).

이 요청에는 유효한 사용자 이름 (또는 이메일), 클라이언트 이름, 작업 이름을 제공할 것을 적극 권장합니다. 이러한 필드는 사용자 환경을 개선하기 위해 UI에서만 사용됩니다.

5.2.2. Return

/privet/printer/submitdoc API는 다음 데이터를 반환합니다.

값 이름	값 유형	설명
job_id	문자열	요청에 지정된 새로 만든 인쇄 작업의 ID (단순 인쇄) 또는 job_id (고급 인쇄)입니다.
expires_in	int	인쇄 작업이 유효한 시간(초)입니다.
작업 유형	문자열	제출된 문서의 콘텐츠 유형입니다.
작업_크기	int 64비트	인쇄 데이터의 크기(바이트)입니다.
작업 이름	문자열	(선택사항) 입력된 이름과 동일한 작업 이름 (있는 경우)

예:

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

5.2.3. 오류

/privet/printer/submitdoc API는 다음 오류를 반환할 수 있습니다 (자세한 내용은 오류 섹션 참조).

오류	설명
invalid_print_job	요청에 잘못되거나 만료된 작업 ID가 지정되었습니다. 제한 시간 후에 다시 시도하세요.
잘못된_문서_유형	문서 MIME 유형이 프린터에서 지원되지 않습니다.
잘못된_문서	제출된 서류가 잘못되었습니다.
문서가 너무 큼	문서가 허용되는 최대 크기를 초과합니다.
프린터_바쁨	프린터가 사용 중이라 지금은 문서를 처리할 수 없습니다. 제한 시간 후에 다시 시도하세요.
프린터_오류	프린터가 오류 상태이며 수정하려면 사용자 상호작용이 필요합니다. 설명에는 자세한 설명이 포함되어야 합니다 (예: 트레이 1의 용지 걸림).
잘못된 매개변수	요청에 잘못된 매개변수가 지정되었습니다. 향후 호환성을 위해 알 수 없는 매개변수를 안전하게 무시해야 합니다.
user_cancel	사용자가 기기에서 인쇄 프로세스를 명시적으로 취소했습니다.
서버 오류	클라우드 프린트에 문서를 게시할 수 없습니다.
잘못된_x_privet_token	요청에서 X-Privet-Token이 잘못되었거나 비어 있습니다.

기기가 /privet/printer/submitdoc를 노출하지 않는 경우 HTTP 404 오류를 반환해야 합니다(MUST). X-Privet-Token 헤더가 없으면 기기에서 HTTP 400 오류를 반환해야 합니다(MUST).

참고: /privet/printer/submitdoc API는 대용량 페이로드가 연결되어 있기 때문에 프린터 측에서 특별한 처리가 필요할 수 있습니다. 프린터 HTTP 서버 구현 및 플랫폼에 따라 프린터가 HTTP 오류를 반환하기 전에 소켓을 닫을 수도 있습니다. 다른 프린터에서 Privet 오류 대신 503 오류를 반환할 수 있습니다. 프린터가 Privet을 반환하기 위해 최대한 노력해야 합니다(SHOULD). 하지만 Privet 사양을 구현하는 모든 클라이언트는 /privet/printer/submitdoc API에 대해 소켓 닫기(HTTP 오류 없음)와 503 HTTP 오류 사례를 처리할 수 있어야 합니다(SHOULD). 이 경우 클라이언트는 'timeout'이 15초로 설정된 Privet 'printer_Busy&quot' 오류로 처리해야 합니다(SHOULD). 무한 재시도를 방지하기 위해 클라이언트는 합당한 횟수 (예: 3) 후에 재시도를 중지할 수 있습니다.

5.3. /privet/printer/jobstate API

/privet/printer/jobstate API는 선택사항입니다 (위의 간단한 인쇄 참고). HTTP GET 요청입니다. /privet/printer/jobstate API는 유효한 "X-Privet-Token" 헤더를 확인해야 합니다(MUST). 기기는 "/privet/printer/jobstate" url에서 이 API를 구현해야 합니다(MUST).

GET /privet/printer/jobstate HTTP/1.1

프린터는 /privet/printer/jobstate API 호출을 수신하면 요청된 인쇄 작업 또는 valid_print_job 오류의 상태를 반환해야 합니다.

5.3.1. 입력

/privet/printer/jobstate API에는 다음과 같은 입력 매개변수가 있습니다.

이름	값
job_id	상태를 반환할 작업 ID를 인쇄합니다.

5.3.2. Return

/privet/printer/jobstate API는 다음 데이터를 반환합니다.

값 이름	값 유형	설명
job_id	문자열	상태 정보의 인쇄 작업 ID입니다.
state	문자열	draft - 기기에서 인쇄 작업이 생성되었습니다 (아직 /privet/printer/submitdoc 호출이 수신되지 않음). 대기 중 - 인쇄 작업이 수신되어 대기 중이지만 인쇄가 아직 시작되지 않았습니다. in_progress - 인쇄 작업이 인쇄 진행 중입니다. 중지됨 - 인쇄 작업이 일시중지되었지만 수동 또는 자동으로 다시 시작할 수 있습니다. 완료 - 인쇄 작업이 완료되었습니다. 취소됨 - 인쇄 작업이 실패했습니다.
설명	문자열	(선택사항) 사람이 읽을 수 있는 인쇄 작업 상태에 관한 설명입니다. 상태가 중지 또는 취소된 경우 추가 정보를 포함해야 합니다. semantic_state 필드는 일반적으로 클라이언트에 더 좋고 의미 있는 설명을 제공합니다.
expires_in	int	인쇄 작업이 유효한 시간(초)입니다.
작업 유형	문자열	(선택사항) 제출된 문서의 콘텐츠 유형입니다.
작업_크기	int 64비트	(선택사항) 인쇄 데이터 크기(바이트)입니다.
작업 이름	문자열	(선택사항) 입력된 이름과 동일한 작업 이름 (있는 경우)
server_job_id	문자열	(선택사항) 서버에서 반환된 작업의 ID (작업이 클라우드 프린트 서비스에 게시된 경우) 오프라인 인쇄에서는 생략됩니다.
시맨틱_상태	JSON	(선택사항) PrintJobState 형식의 작업 시맨틱 상태입니다.

예 (클라우드 프린트를 통한 보고에 의한 인쇄):

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

예 (오프라인 인쇄 오류):

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

예 (사용자가 인쇄 작업을 취소함):

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

예 (용지가 부족하여 인쇄 작업이 중지됨) 기기 상태에 대한 참조를 확인합니다. 클라이언트는 기기 상태에 관한 자세한 정보를 얻으려면 /privet/info API를 호출해야 합니다.

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

5.3.3. 오류

/privet/printer/jobstate API가 다음 오류를 반환할 수도 있습니다 (자세한 내용은 오류 섹션 참조).

오류	설명
invalid_print_job	요청에 잘못되거나 만료된 작업 ID가 지정되었습니다.
서버 오류	클라우드 프린트에 게시된 인쇄 작업의 인쇄 작업 상태를 가져오지 못했습니다.
잘못된_x_privet_token	요청에서 X-Privet-Token이 잘못되었거나 비어 있습니다.

기기가 /privet/printer/jobstate를 노출하지 않는 경우 HTTP 404 오류를 반환해야 합니다(MUST). X-Privet-Token 헤더가 없으면 기기에서 HTTP 400 오류를 반환해야 합니다(MUST).

6. 부록

6.1. 기본 동작 및 설정

이 섹션에서는 모든 Privet 호환 기기에서 예상되는 기본 동작을 설명합니다.

즉시 사용 가능한 기기는 /privet/info 및 /privet/register API만 지원해야 합니다. 다른 모든 API (예: /privet/accesstoken, 로컬 인쇄)는 사용 중지해야 합니다.
등록하려면 기기와의 물리적 상호작용이 필요합니다.

사용자는 기기의 물리적인 동작(예: 버튼 누르기)을 통해 기기에 대한 액세스를 확인해야 합니다(MUST).
사용자가 위에 설명된 작업을 실행하면 프린터에서 /Buganizer/register 요청을 전송해야 합니다. 작업이 실행될 때까지 이 요청을 전송하면 안 됩니다(시퀀스 다이어그램 1 참고).
기기가 /privet/register 요청을 처리하는 경우 (예: 위의 작업 대기) 다른 모든 /privet/register 요청을 거부해야 합니다. 이 경우 기기는 device_Busy 오류를 반환해야 합니다.
기기는 60초 이내에 위에 언급된 물리적 작업을 수신하지 않는 /register 요청을 시간 초과해야 합니다. 이 경우 기기가 verification_timeout 오류를 반환해야 합니다(MUST).
선택사항: 권장되지만 필수는 아닙니다. 다음과 같은 방법으로 사용자 환경을 개선할 수 있습니다.

프린터에서 표시등이나 화면을 플래시하여 사용자가 등록을 확인하려면 조치를 취해야 한다고 나타낼 수 있습니다.
프린터에서 화면에 '사용자 abc@def.com의 Google 클라우드 프린트에 등록 중입니다'라고 표시될 수 있습니다. 계속하려면 확인을 누르세요. 여기서 abc@def.com은 /register API 호출의 사용자 매개변수입니다. 이를 통해 사용자는 다음과 같은 내용을 더욱 명확하게 이해할 수 있습니다.

등록 요청이므로 확인하는 것은
요청을 트리거하지 않은 경우 초래되는 결과

프린터에서 확인하는 물리적 작업 (예: ‘OK(확인)’ 버튼을 누르면 프린터에서 사용자에게 요청을 취소할 수 있는 버튼(예: ‘거부하려면 취소를 누르세요’). 이렇게 하면 등록 요청을 트리거하지 않은 사용자가 60초 제한 시간 전에 취소할 수 있습니다. 이 경우 기기에서 user_cancel 오류를 반환해야 합니다(MUST).

소유권 이전:

기기는 클라우드 서비스에서 명시적으로 삭제될 수 있습니다.

기기는 성공하지만 /Buganizer/printer(GCP용) 호출의 결과로 기기 설명이 표시되지 않는 경우 기본(즉시 사용) 모드로 되돌려야 합니다(MUST).
기기의 사용자 인증 정보가 더 이상 작동하지 않으면(서버의 '잘못된 사용자 인증 정보' 응답으로 인해) 기기가 기본(즉시 사용) 모드로 되돌아가야 합니다(MUST).

로컬 초기화는 기기의 사용자 인증 정보를 삭제하고 기본 상태로 설정해야 합니다(MUST).
선택사항: 기기에서 사용자 인증 정보를 삭제하고 기본 모드로 전환할 수 있도록 메뉴 항목을 제공할 수 있습니다.

XMPP 알림을 지원하는 기기에는 서버를 핑하는 기능이 포함되어야 합니다(MUST). 핑 제한 시간은 "local_settings"를 통해 서버에서 제어할 수 있어야 합니다(MUST).
기기에서 서버가 동기화되도록 하기 위해 하루에 두 번(24시간) 이상은 명시적으로 서버 핑 (GCP용 /Buganizer/printer API)을 핑할 수 있습니다. 확인 기간을 24~32시간 내로 임의로 설정하는 것이 좋습니다.
선택사항: 클라우드 프린트 기기의 경우 사용자가 기기에서 새 인쇄 작업 확인을 시작할 수 있도록 수동 방법(버튼)이 없는 것이 좋습니다. 일부 프린터에는 이미 이 기능이 있습니다.
선택사항입니다. 엔터프라이즈 프린터에서는 로컬 검색을 완전히 사용 중지할 수 있습니다. 이 경우 기기는 서버에서 로컬 설정을 업데이트해야 합니다(MUST). 새 로컬 설정은 비어 있어야 합니다 (MUST: 'local_discovery"를 'false'로 설정하면 GCP 서비스에서 다시 사용 설정할 수 있음).

6.1.2 기본 등록 다이어그램

6.2. XSSI 및 XSRF 공격 및 방지

이 섹션에서는 기기에 XSSI 및 XSRF 공격이 발생할 수 있는 가능성과 공격으로부터 이를 보호하는 방법 (토큰 생성 기술 포함)을 설명합니다.
자세한 내용은 다음 도움말을 참조하세요. http://pagetypesecurity.blogspot.com/2011/05/website-security-for-webmasters.html
일반적으로 사이트가 쿠키 인증 메커니즘을 사용할 때 XSSI와 XSRF 공격이 발생할 수 있습니다. Google에서는 클라우드 프린트 서비스에 쿠키를 사용하지 않지만 이러한 공격은 여전히 발생할 수 있습니다. 로컬 네트워크 액세스는 설계적으로 암시적으로 요청을 신뢰합니다.

6.2.1. XSSI : XSSI : XSSI

악성 웹사이트가 Privet 호환 기기의 IP 주소와 포트 번호를 추측하고 'script> 태그 내부'를 사용하여 Privet API를 호출하려고 할 수 있습니다.

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

보호 조치 없이는 악성 웹사이트가 API 호출과 액세스 결과를 실행할 수 있습니다.
이 유형의 공격을 방지하려면 모든 Privet API 호출에는 요청에 'X-Privet-Token' 헤더가 있어야 합니다(MUST). &srctlt;api> 스크립트 태그는 헤더를 추가할 수 없으므로 이러한 유형의 공격으로부터 효과적으로 보호할 수 있습니다.

6.2.2. XSR

http://en.wikipedia.org/wiki/Cross-site_request_forgery
악성 웹사이트가 Privet 호환 기기의 IP 주소와 포트 번호를 추측하고 'iframe', 양식, 기타 교차 웹사이트 로드 메커니즘을 사용하여 Privet API를 호출하려고 할 수 있습니다. 공격자는 요청 결과에 액세스할 수 없지만 요청이 작업 (예: 인쇄)을 실행하면 트리거할 수 있습니다.

이러한 공격을 막으려면 다음 보호 조치가 필요합니다.

/privet/info API를 XSRF에 열어둠
/privet/info API가 기기에서 어떠한 작업도 수행하면 안 됩니다(MUST NOT).
/privet/info API를 사용하여 x-privet-token 받기
다른 모든 API는 "X-Privet-Token" 헤더에서 유효한 x-privet-token을 확인해야 합니다.
x-privet-token은 24시간 동안만 유효해야 합니다(SHOULD).

공격자가 /privet/info API를 실행할 수 있더라도 응답에서 x-privet-token을 읽을 수 없으므로 다른 API를 호출할 수 없습니다.

다음 알고리즘을 사용하여 XSRF 토큰을 생성하는 것이 좋습니다.

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

XSRF 토큰 생성 요소:

DELIMITER은 특수문자(일반적으로 ‘:’)입니다.
issue_timecounter는 일부 이벤트(타임스탬프의 에포크) 또는 기기 부팅 시간(CPU 카운터의 경우) 이후 경과된 시간(초)입니다. issue_timeCounter는 기기가 실행 중일 때 계속 증가합니다(아래의 토큰 확인 참고).
SHA1 - SHA1 알고리즘을 사용하는 해시 함수
base64 - base64 인코딩
device_secret: 기기와 관련된 보안 비밀입니다. 다시 시작할 때마다 기기 보안 비밀을 업데이트해야 합니다(MUST).

기기 보안 비밀을 생성할 때 권장되는 방법은 다음과 같습니다.

다시 시작할 때마다 새 UUID 생성
다시 시작할 때마다 64비트 랜덤 숫자를 생성

기기는 발급된 XSRF 토큰을 모두 저장할 필요는 없습니다. 기기가 XSRF 토큰의 유효성을 검증해야 할 때는 토큰을 base64로 디코딩해야 합니다. 후반부 (일반 텍스트)에서 issue_timeCounter를 가져오고 토큰에서 issue_timecounter를 가져온 device_secret + + issue_timecounter의 SHA1 해시를 생성해 보세요. 새로 생성된 SHA1이 토큰의 SHA1과 일치하면 이제 issue_timeCounter가 현재 시간 카운터의 유효 기간 (24시간) 내에 있는지 확인해야 합니다. 이렇게 하려면 기기는 현재 시간 카운터 (예: CPU 카운터)를 사용하고 issue_timecounter를 뺍니다. 결과는 토큰 문제가 발생한 후 경과된 시간(초)입니다.

중요: XSRF 보호를 구현하는 데 권장되는 방법입니다. Privet 사양 고객은 XSRF 토큰을 이해하려고 해서는 안 되며, 대신 블랙박스로 취급해야 합니다. 그림 6.2.3은 X-Privet-Token을 구현하고 일반적인 요청을 확인하는 권장 방법을 보여줍니다.

6.2.3 X-Privet 토큰 생성 및 확인 시퀀스 다이어그램

6.3 워크플로 다이어그램

이 섹션에서는 여러 가지 경우에 해당하는 워크플로를 설명합니다.

6.3.1 즉시 사용 가능한 프린터 워크플로

6.3.2 등록된 프린터 시작

6.3.3 XMPP 알림 처리 워크플로

6.3.4 프린터 설정 워크플로 확인