Connect üzerinden PDF'teki PII'yi giderme

Connect üzerinden PDF’teki PII’yi giderme

Bir bakışta

Bu tarif, NextPDF Connect tarafından sunulan redaksiyon araçlarıyla bir belgenin metin katmanında algılanan kişisel olarak tanımlanabilir bilgileri (PII) kaldırır. Bu araçlar Enterprise katmanına aittir. ToolRegistry; redact_pdf, zone_redact_pdf ve deidentify_pdf araçlarını, Enterprise gizlilik sınıflarını (RedactionEngine + PiiDetector) class_exists() ile yoklayarak oluşturur. Her aracı enterprise katmanı altında yalnızca bu sınıflar otomatik yüklenebilir olduğunda kaydeder. Yalnızca açık kaynaklı bir kurulumda araçlar mevcut değildir: çağrı sessizce bozulmak yerine bilinmeyen araç hatasıyla başarısız olur. Üç aracın tamamı destructiveHint: true bildirir. Bu düzenleme sayfa içeriğini yeniden yazar ve düzenlenen belgeden geri alınamaz.

Bu sayfa, araç davranışını Connect yüzeyi üzerinden belgeler. Bir redaksiyon iş akışı, çağrıdan sonra belgenin kişisel veriden arınmış olduğunu onaylamaz. Algılama yalnızca ayıklanabilir metin katmanı üzerinde çalışır ve sonucun doğrulanmasından dağıtım sorumlu olmaya devam eder.

Kurulum

composer require nextpdf/server

Redaksiyon araçları yalnızca Enterprise gizlilik modülünü sunucuyla birlikte kurduğunuzda kaydolur. Bu modül nextpdf/premium içinde gelir. Araca güvenmeden önce çalışan dağıtımda mevcut olduğunu doğrulayın:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
EOF

Eğer redact_pdf, tools/list sonucunda eksikse Enterprise gizlilik sınıfları bu kurulumda çözümlenmemiştir. Kayıt defterinin katman başına araç kümesini önyükleme sırasında nasıl hesapladığını öğrenmek için /connect/tool-catalog/ adresine bakın.

Kavramsal genel bakış

Üç araç, üç redaksiyon stratejisini kapsar. Tümü Enterprise katmanına aittir ve yıkıcı ipucunu taşır:

• redact_pdf — belgenin düz metin içeriğindeki kişisel verileri yerleşik bir algılayıcıyla algılar ve kaldırır, ardından düzenlenen içeriği ve yapılandırılmış bir raporu döndürür.
• zone_redact_pdf — düz metin içeriğine koordinat tabanlı bölge redaksiyonları uygular. Bölgeyi desenle değil, konumla bildiğinizde bunu kullanın.
• deidentify_pdf — algılanan varlıklar genelinde sistematik bir kimliksizleştirme stratejisi (redaksiyon veya gizleme) uygular.

Bir sayfa içerik akışından içerik kaldırmak, o akışı yıkıcı biçimde düzenler: etkilenen baytlar yeniden yazılır ve düzenlenen belgeden kurtarılamaz (ISO 32000-2 §14.11). Tasarım gereği rapor, her kaldırma işleminin karakter sayısını ve konumunu kaydeder; kaldırılan metnin kendisini asla kaydetmez.

API yüzeyi

Her aracı tanımlayan Enterprise paketi, aracın tam istek ve yanıt şemasını da sağlar. Bu sayfa, sabit bir parametre listesini değil, Connect çağırma sözleşmesini belgeler. Çalışan kayıt defterinde doğrulanan araç adları redact_pdf, zone_redact_pdf ve deidentify_pdf olup tümü document kategorisinde ve destructiveHint: true ile yer alır. Kayıt kataloğu için /connect/tool-catalog/ adresine bakın. Bu tarif, araç sayısını yeniden belirtmez; çünkü bu değer dağıtımın çalışma zamanı özelliğidir.

Kod örneği — hızlı başlangıç

İçeriği Model Context Protocol (MCP) üzerinden algılayıp kaldırın (tools/call). Aşağıdaki bağımsız değişkenler çağrının biçimini gösterir. Yetkili bağımsız değişken şeması, dağıtımınızda tools/list tarafından döndürülen şemadır:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "redact_pdf",
    "arguments": {
      "source": "/var/lib/nextpdf/in/employee-directory.pdf"
    }
  }
}

Başarılı bir çağrı bir rapor döndürür. Her kaldırma için bir giriş; sayfayı, bir kategori etiketini, özgün karakter sayısını ve bir sınırlayıcı kutuyu kaydeder, kaldırılan metni değil.

Kod örneği — üretim

Redaksiyon çağrısını yıkıcı bir işlem olarak ele alın ve belgeyi yayımlamadan önce raporu inceleyin. Ağ üzerinden çalışan bir taşıyıcıda, taşıyıcı hatasını ve araç düzeyindeki hatayı ayrı durumlar olarak ele alın:

curl -sS -X POST https://connect.example.com/v1/tools/redact_pdf \
  -H 'Authorization: Bearer '"$NEXTPDF_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"source":"/var/lib/nextpdf/in/legal-discovery-batch.pdf"}' \
  -o /tmp/redaction-report.json -w '%{http_code}' > /tmp/redaction-status

status="$(cat /tmp/redaction-status)"
if [ "$status" != "200" ]; then
  # 4xx/5xx is a normal HTTP outcome the caller inspects, not a transport
  # failure. A connection error (curl non-zero exit) is the separate case.
  echo "redact_pdf returned HTTP $status; inspect the body, do not release the document" >&2
  exit 1
fi

Düzenlenen belgeyi yalnızca bir kişi veya sonraki aşamadaki bir denetim raporu inceledikten sonra yayımlayın. Yayımı bu incelemenin arkasında tutmak, denetimi otomatik düzenlemenin artık veri riski oluşturduğu noktaya yerleştirir (IEC 31010:2019).

Uç durumlar ve dikkat edilecekler

• Metin katmanı olmayan taranmış PDF. Algılama, ayıklanabilir metin katmanı üzerinde çalışır. Yalnızca görüntü içeren bir sayfa sıfır kaldırma üretir ve bu bir hata değildir. İçerik rasterleştirilmişse, redaksiyondan önce belge üzerinde optik karakter tanıma (OCR) çalıştırın.
• Şifrelenmiş kaynak. Belge parolasını aracın bağımsız değişken şeması aracılığıyla sağlayın. Parola olmadan çağrı, belgenin yalnızca bir kısmını işlemek yerine başarısız olur.
• Araç mevcut değil. Yalnızca açık kaynaklı bir kurulumda Enterprise gizlilik sınıfları çözümlenmez ve redact_pdf kaydedilmez; bu nedenle çağrı bilinmeyen araç hatasıyla başarısız olur. Bu, bir bozulma değil, amaçlanan sınırdır.
• Çakışan algılamalar. Birden fazla algılayıcı aynı bölgeyle eşleştiğinde araç bölgeyi bir kez kaldırır ve raporda yinelenenleri ayıklar.

Performans

Ön bilgideki performans bütçesi, bir hizmet düzeyi garantisi değil, belgeleme amaçlı bir üst sınırdır. Büyük belgeler sayfa sayfa işlenir. Genel zaman aşımını yükseltmek yerine çağrıyı bir sayfa aralığı alt kümesi üzerinde yeniden çalıştırmayı planlayın.

Güvenlik notları

Veri yerleşimi ve PII azaltma önlemleri

Connect ana makinesi belge metnini süreç içinde işler. Rapor, kaldırılan metni kasıtlı olarak atlar ve yalnızca sayıları ve konumları bildirir; böylece rapor, tanımladığı kişisel verileri yeniden ortaya çıkarmaz. Giriş ve düzenlenen çıkış için dağıtım düzeyinde veri yerleşimi, aracın bir özelliği değil, entegratörün sorumluluğudur.

Güvenli telemetri ve günlük temizleme

Kaynak belge yolunu veya rapor gövdesini, dışarıya gönderilen bir günlük düzeyinde günlüğe kaydetmeyin. Yalnızca araç adını, istek kimliğini ve pass/fail sonucunu günlüğe kaydedin.

Tehdit modeli

Metni görsel olarak örten ancak kaldırmayan bir redaksiyon, verileri ayıklanabilir bırakır. Bu araçlar, bir dikdörtgen bindirmek yerine etkilenen içerik akışını yeniden yazar; kaldırılan baytları düzenlenen belgeden kurtarmak mümkün değildir (ISO 32000-2 §14.11). Algılayıcı içeriği kaçırdığında artık risk kalır: kurallarının dışındaki bir desen ya da yalnızca rasterleştirilmiş bir görüntü olarak bulunan metin. İş akışı bu riski, eksiksizlik iddiasıyla değil, zorunlu rapor incelemesiyle azaltır.

FIPS modu davranışı

Redaksiyon herhangi bir kriptografik işlem gerçekleştirmez ve ana makinedeki Federal Information Processing Standards (FIPS) modu ilkesinden etkilenmez.

Uygunluk

İddia	Madde	reference_id
İçerik kaldırmak, etkilenen içerik akışını yeniden yazar	ISO 32000-2 §14.11
Redaksiyon önce işaretler sonra kaldırır; kaldırma bir içerik düzenlemesidir	ISO 32000-2 §14.11
Denetim, otomatik düzenlemenin risk oluşturduğu noktaya yerleştirilir	IEC 31010:2019

Redaksiyon araçlarının desteklenmesi, işlenen belgenin kişisel veriden arınmış olduğunu onaylamaz. Bu belirleme bağımsız incelemeyle yapılır.

Ticari bağlam

Redaksiyon araçları Enterprise katmanına aittir. Yalnızca nextpdf/premium sunucuyla birlikte kurulduğunda kaydolurlar. Ön bilgideki dönüşüm bağlantısına bakın.

Connect ayrıntıları

Taşıyıcı kullanılabilirliği (MCP / REST / gRPC)

Paylaşılan araç yürütücüsünü çalıştıran her taşıyıcıda araçları aynı şekilde çağırırsınız: MCP tools/call, REST araç uç noktası ve gRPC hizmeti. Bağımsız değişken şeması taşıyıcıdan bağımsızdır. Bu şema, tools/list (MCP) ya da hizmet tanımlayıcısı (gRPC) tarafından döndürülür.

HITL risk katmanı

Üç aracın tamamı destructiveHint: true bildirir. Bir operatör, yapılandırma geçersiz kılması yoluyla bir aracı approval_required risk düzeyine yükselttiğinde çağrı ConfirmationGate arkasında kapı denetimine alınır. Geçersiz kılma yalnızca riski yükseltebilir, asla düşüremez. /connect/hitl-risk-tiers/. adresine bakın.

Onay kapısı JSON zarfı

Araç kapı denetimine alınmışsa ve geçerli bir belirteç olmadan çağrılırsa kapı şu biçimde bir sınama zarfı döndürür:

{ "allowed": false, "challenge": "<human-readable text>", "token": "confirm_<nonce>" }

Çağıran taraf, arguments._confirmation_token değerini verilen belirtece ayarlayarak aynı aracı yeniden çağırır. Belirteç; araç adını, tek kullanımlık bir değeri ve 300 saniyelik bir TTL’yi bağlar — bağımsız değişkenleri değil — ve tek kullanımlıktır.

Ayrıca bakınız

• /connect/tool-catalog/ — kayıt defterinin katman başına araç kümesini nasıl hesapladığı.
• /connect/hitl-risk-tiers/ — dört düzeyli risk modeli ve kapı.
• /cookbook/connect/extract-text-content/ — redaksiyondan önce ayıklanabilir metni önizleyin.
• /cookbook/connect/digital-signature/ — gözetim zinciri için düzenlenen belgeyi imzalayın.