Connect로 표준 검사 실행하기

Connect로 표준 검사 실행하기

한눈에 보기

이 레시피에서는 Connect 트랜스포트를 통해 compliance-check 도구를 사용해 지정된 표준의 규칙 집합(예: PDF/A-4, PAdES 기준 수준 또는 조직 정책)에 따라 PDF를 평가합니다. 이 도구는 Enterprise 등급입니다. 이 도구는 class_exists() 프로브를 통해 발견되며, nextpdf/premium이 서버와 함께 설치된 경우에만 등록됩니다. 오픈 소스만 설치한 환경에서는 이 도구가 존재하지 않으며, 호출은 알 수 없는 도구 오류와 함께 실패합니다.

이 도구는 요청된 표준에 대해 구현된 규칙을 기준으로 규칙별 pass/fail을 보고합니다. 그 결과는 도구 자체의 검사이며, 독립적인 적합성 인증이 아닙니다. 적합성 판정은 검증기(예: PDF/A의 경우 veraPDF)가 내립니다. 이 페이지는 적합성 보증이 아닌 도구 동작을 설명합니다.

설치

composer require nextpdf/server

tools/list 호출로 실행 중인 배포에 Enterprise 적합성 도구가 있는지 확인합니다. 자세한 내용은 /connect/tool-catalog/를 참조합니다.

개념 개요

PDF/A-4와 같은 표준은 문서에 대한 요구 사항을 규정합니다. 검사기는 그 요구 사항을 기준으로 문서를 평가합니다(PDF/A-4 §6.2.3). 적합성은 표준의 요구 사항을 기준으로 판정되는 것이며, 생성 소프트웨어가 주장하는 것이 아닙니다(PDF/A-4 §6.7.3). 서명 관련 표준의 경우, 이 검사는 서명된 바이트 범위를 기준으로 서명 이후 수정이 발생했는지 확인합니다(ISO 32000-2 §12.8).

따라서 이 도구에서 “pass”는 “이 도구가 해당 표준에 대해 구현한 규칙 중 실패한 규칙이 없음”을 의미합니다. 이는 문서 전체에 대한 공식적인 적합성 인증보다 좁은 범위입니다.

API 표면

도구 이름은 tools/list를 통해 실행 중인 레지스트리 기준으로 검증됩니다. 공식 카탈로그는 /connect/tool-catalog/입니다. 이 레시피에서는 배포의 런타임 속성인 도구 개수를 다시 설명하지 않습니다.

코드 샘플 — 빠른 시작

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "compliance_check",
    "arguments": { "document_id": "<id>", "standard": "pdfa-4" }
  }
}

코드 샘플 — 프로덕션

“fail” 결과는 조치가 필요한 데이터로 취급하고, 네트워크 트랜스포트에서는 트랜스포트 실패와 정상적으로 반환된 비성공 HTTP 상태를 구분합니다.

curl -sS -X POST https://connect.example.com/v1/tools/compliance_check \
  -H 'Authorization: Bearer '"$NEXTPDF_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"source":"/var/lib/nextpdf/in/report.pdf","standard":"pdfa-4"}' \
  -o /tmp/check.json -w '%{http_code}' > /tmp/check-status || {
    echo "transport failure invoking compliance_check" >&2; exit 1; }

[ "$(cat /tmp/check-status)" = "200" ] || {
  echo "compliance_check returned non-200; inspect /tmp/check.json" >&2; }

응답에는 평가된 각 규칙, 해당 pass/fail 상태, 각 실패 사유가 나열됩니다. 실패 항목을 바탕으로 문제를 해결합니다. “pass”를 인증으로 취급해서는 안 됩니다.

엣지 케이스 및 주의 사항

• 알 수 없는 표준 이름. 도구는 인식된 식별자와 함께 알 수 없는 표준 오류를 반환합니다. 정확한 식별자(pdfa-4, PAdES 기준 수준, 조직 정책 id)를 사용해야 합니다.
• 문서를 찾을 수 없음. document_id가 이전 출력 호출에서 나온 값인지 확인하거나, 유효한 source 경로를 전달해야 합니다.
• 손상된 상호 참조. 파싱 실패는 입력이 유효한 PDF가 아니거나 잘린 상태임을 의미합니다. 소스를 다시 생성합니다.
• 도구 부재. nextpdf/premium이 없으면 Enterprise 적합성 도구가 등록되지 않으며, 호출은 알 수 없는 도구 오류와 함께 실패합니다.

성능

프런트매터 예산은 문서에 명시된 상한이며, 서비스 수준 보증이 아닙니다.

보안 참고 사항

외부로 전송되는 로그에는 소스 경로나 전체 보고서를 기록해서는 안 됩니다. 도구 이름, 요청 id, 전체 pass/fail 결과를 기록합니다. “pass”는 도구가 구현하는 규칙 집합을 설명하는 것이며, 보안 또는 법적 보증이 아닙니다.

적합성

주장	조항	reference_id
표준은 요구 사항을 규정하고, 검사기는 이를 평가합니다	PDF/A-4 §6.2.3
적합성은 요구 사항을 기준으로 판정되며, 생성자가 주장하는 것이 아닙니다	PDF/A-4 §6.7.3
서명 이후 수정은 서명된 바이트 범위를 기준으로 탐지할 수 있습니다	ISO 32000-2 §12.8

표준 검사에 대한 지원은 적합성 인증이 아닙니다. 적합성 판정은 독립적인 검증기가 내립니다.

상업적 맥락

compliance-check 도구는 Enterprise 등급이며, nextpdf/premium이 서버와 함께 설치된 경우에만 등록됩니다.

Connect 세부 사항

트랜스포트 가용성 (MCP / REST / gRPC)

이 도구는 공유 도구 실행기를 통해 MCP tools/call, REST 도구 엔드포인트 및 gRPC 서비스에서 동일하게 호출됩니다.

HITL 위험 등급

이 검사는 읽기 전용이며, 기본적으로 approval_required가 아닙니다. 운영자 재정의로 위험 수준을 높일 수 있습니다. 재정의는 높이는 방향으로만 가능하며, 절대 낮출 수 없습니다. /connect/hitl-risk-tiers/를 참조합니다.

확인 게이트 JSON 엔벨로프

운영자 재정의로 approval_required로 높이지 않는 한, 이 도구는 게이트를 트리거하지 않습니다. 챌린지 엔벨로프와 일회용 토큰 계약은 /connect/hitl-risk-tiers/에 문서화되어 있습니다.

참고 항목

• /cookbook/connect/batch-compliance/ — 여러 문서에 걸쳐 검사를 실행합니다.
• /cookbook/connect/ai-ready-certification/ — 더 광범위한 AI 준비 상태 검사입니다.
• /connect/tool-catalog/ — 등급별 도구 집합 계산을 설명합니다.
• /connect/hitl-risk-tiers/ — 위험 모델과 게이트를 설명합니다.