ข้อมูลอ้างอิง API ของ Cloudflare
ภาพรวมโดยย่อ
หัวข้อที่มีชื่อว่า “ภาพรวมโดยย่อ”แพ็กเกจ NextPDF\Cloudflare ทำหน้าที่เชื่อมการเรนเดอร์บน edge กระบวนการ PHP จะเก็บ Hypertext Markup Language (HTML) ไว้เอง และ Cloudflare Worker จะเรียกใช้เบราว์เซอร์แบบ headless แพ็กเกจนี้มีตัวเรนเดอร์ HTML ที่ทำงานบน Worker (CloudflareHtmlRenderer) พร้อมออบเจ็กต์ค่าที่ส่งคืน ชั้นการป้องกันคำขอสำหรับปลายทางการเรนเดอร์ (ApiProtection) บริการจัดเก็บถาวร R2 สำหรับไฟล์ Portable Document Format (PDF) ที่เรนเดอร์แล้ว (R2ArchiveManager) และตัวช่วยการขนส่งแบบปักหมุดสำหรับเพิ่มความแข็งแกร่งด้าน Transport Layer Security (TLS) และ Domain Name System (DNS) การกำหนดค่าอยู่ในออบเจ็กต์ที่ไม่เปลี่ยนแปลงสามรายการ (CloudflareRendererConfig, ApiProtectionConfig, R2ArchiveConfig)
เริ่มต้นโดยสร้าง CloudflareRendererConfig เชื่อมเข้ากับ CloudflareHtmlRenderer แล้วเรียก render() การเรียกนี้จะส่ง HTML ไปยัง Worker และคืนค่า CloudflareRenderResult พร้อมไบต์ของ PDF การป้องกัน การจัดเก็บถาวร และการปักหมุดทั้งหมดจะทำงานเป็นชั้นประกอบรอบการเรียกนี้
งานที่พบบ่อย
หัวข้อที่มีชื่อว่า “งานที่พบบ่อย”ตัวอย่างโค้ดเหล่านี้ครอบคลุมเวิร์กโฟลว์ที่ใช้บ่อยที่สุด แต่ละรายการครบถ้วนในตัวเอง ผ่านการตรวจสอบกับ src/Cloudflare/ และอ่านค่าความลับจากสภาพแวดล้อม
เรนเดอร์สตริง HTML เป็น PDF บน edge ด้วยการเรียกมาตรฐาน:
<?php
declare(strict_types=1);
use GuzzleHttp\Client;use GuzzleHttp\Psr7\HttpFactory;use NextPDF\Cloudflare\CloudflareHtmlRenderer;use NextPDF\Cloudflare\CloudflareRendererConfig;
$httpFactory = new HttpFactory();
$renderer = new CloudflareHtmlRenderer( config: new CloudflareRendererConfig( workerUrl: 'https://pdf-renderer.example.workers.dev/render', apiToken: getenv('CF_PDF_TOKEN') ?: throw new RuntimeException('CF_PDF_TOKEN not set'), ), httpClient: new Client(), requestFactory: $httpFactory, streamFactory: $httpFactory, responseFactory: $httpFactory,);
$result = $renderer->render('<h1>Hello from the edge</h1>', widthPt: 595.28);
if ($result->isValid()) { file_put_contents('output.pdf', $result->pdfData);}การทำงานนี้ส่ง HTML ไปยัง Worker ผ่าน Hypertext Transfer Protocol Secure (HTTPS) และเขียนไบต์ของ PDF ขนาด A4 ที่คืนค่ามาลงดิสก์หลังจาก isValid() ยืนยันว่าเป็น PDF จริง
จัดเก็บ PDF ที่เรนเดอร์แล้วลงใน R2 และคืนค่าลิงก์อายุสั้น:
<?php
declare(strict_types=1);
use NextPDF\Cloudflare\R2ArchiveConfig;use NextPDF\Cloudflare\R2ArchiveManager;
$archive = new R2ArchiveManager( config: R2ArchiveConfig::fromArray([ 'bucket_name' => 'pdf-archive', 'account_id' => getenv('CF_ACCOUNT_ID') ?: '', 'access_key_id' => getenv('R2_ACCESS_KEY_ID') ?: '', 'secret_access_key' => getenv('R2_SECRET_ACCESS_KEY') ?: '', ]), httpClient: $httpClient, // PSR-18 ClientInterface requestFactory: $requestFactory, // PSR-17 RequestFactoryInterface streamFactory: $streamFactory, // PSR-17 StreamFactoryInterface);
$upload = $archive->upload($result->pdfData, 'invoice-1234.pdf');
$signedUrl = $upload->isValid() ? $archive->generateSignedUrl($upload->key, expiresInSeconds: 600) : null;การทำงานนี้อัปโหลดไบต์ของ PDF ไปยังคีย์ R2 ที่แบ่งพาร์ติชันตามวันที่ และเมื่อสำเร็จจะสร้าง uniform resource locator (URL) แบบ pre-signed อายุ 10 นาทีสำหรับการดาวน์โหลดชั่วคราว
ป้องกันปลายทางการเรนเดอร์ก่อนเริ่มงาน Worker ที่มีต้นทุนสูง:
<?php
declare(strict_types=1);
use NextPDF\Cloudflare\ApiKeyValidator;use NextPDF\Cloudflare\ApiProtection;use NextPDF\Cloudflare\ApiProtectionConfig;
$protection = new ApiProtection( config: new ApiProtectionConfig(maxRequestsPerMinute: 30), keyValidator: new ApiKeyValidator([getenv('RENDER_API_KEY') ?: '']),);
$decision = $protection->checkRequest( clientId: $clientIp, payloadSize: strlen($html), apiKey: $presentedApiKey,);
if (!$decision->allowed) { // Reject with 429 and rate-limit headers before any render call. return [429, $decision->toHeaders(), $decision->denialReason];}การทำงานนี้ตรวจสอบความถูกต้องของคีย์ API และขนาดเพย์โหลด ตรวจสอบขีดจำกัดอัตราต่อไคลเอ็นต์ แล้วคืนค่าการตัดสินใจหนึ่งรายการพร้อมส่วนหัวการตอบสนองสำหรับแนบเมื่อคำขอถูกปฏิเสธ
ตัวเรนเดอร์
หัวข้อที่มีชื่อว่า “ตัวเรนเดอร์”ตารางนี้ครอบคลุมความสามารถหลักของตัวเรนเดอร์ ใช้เมื่อต้องสร้างคอนฟิก สร้างตัวเรนเดอร์ หรือเรียกใช้การเรนเดอร์และการตรวจสอบการเข้าถึง
| สัญลักษณ์ | พารามิเตอร์ | พฤติกรรมเริ่มต้น | คืนค่า | ข้อยกเว้นหรือความล้มเหลว | หมายเหตุ |
|---|---|---|---|---|---|
new CloudflareRendererConfig(string $workerUrl, string $apiToken, int $renderTimeout = 30, string $defaultCss = '', int $maxHtmlSize = 5000000, ?string $r2FontBucket = null, bool $fallbackToLocal = true, array $pinnedPublicKeys = [], array $backupPublicKeys = []) | URL ของ Worker, bearer token, ค่าหมดเวลา, Cascading Style Sheets (CSS), ขีดจำกัดขนาด, R2 font bucket แบบไม่บังคับ, แฟล็กสำรอง, ชุดการปักหมุด | การสำรองแบบโลคัลเปิดใช้งานอยู่ การปักหมุดจะปิดเมื่ออาร์เรย์การปักหมุดว่างเปล่า | CloudflareRendererConfig | ไม่คาดว่าจะเกิด | เก็บ API token ไว้เป็นความลับ และควรใช้ URL ของ worker แบบ HTTPS |
CloudflareRendererConfig::fromArray(array $config) | worker_url, api_token, render_timeout, default_css, max_html_size, r2_font_bucket, fallback_to_local, อาร์เรย์การปักหมุด | คีย์แบบไม่บังคับที่ไม่ได้ระบุจะใช้ค่าเริ่มต้นของคอนสตรักเตอร์ | CloudflareRendererConfig | ไม่คาดว่าจะเกิด | ใช้สำหรับอาร์เรย์คอนฟิกของเฟรมเวิร์ก |
CloudflareRendererConfig::isValid() | ไม่มี | ต้องมี URL ของ worker และ API token ที่ไม่ว่างเปล่า | bool | ไม่คาดว่าจะเกิด | คอนฟิกที่ไม่ถูกต้องจะทำให้ตัวเรนเดอร์ใช้การสำรองหรือล้มเหลว |
CloudflareRendererConfig::allPublicKeyPins() | ไม่มี | รวมการปักหมุดคีย์สาธารณะหลักและคีย์สำรองเข้าด้วยกัน | list<string> | ไม่คาดว่าจะเกิด | รายการที่ว่างเปล่าจะปิดใช้งานการปักหมุด |
new CloudflareHtmlRenderer(CloudflareRendererConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?LocalRendererFactoryInterface $localRendererFactory = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null) | คอนฟิก, การพึ่งพา Hypertext Transfer Protocol (HTTP) แบบ PHP Standards Recommendation (PSR), logger แบบไม่บังคับ, factory สำหรับการสำรองแบบโลคัลที่ไม่บังคับ, นโยบาย HTML แบบไม่บังคับ, response factory แบบไม่บังคับ | ใช้ DefaultHtmlSecurityPolicy เมื่อไม่ได้ระบุนโยบาย HTML | CloudflareHtmlRenderer | ข้อผิดพลาดในการเชื่อมต่อคอนเทนเนอร์ | response factory จะเปิดใช้งานการขนส่งแบบ cURL ที่ปักหมุดเมื่อจำเป็น |
CloudflareHtmlRenderer::render(string $html, float $widthPt = 595.28, float $heightPt = 0, array $fontFiles = []) | HTML, ความกว้างของหน้า, ความสูงของหน้า, ไฟล์ฟอนต์ใน R2 | ความกว้าง A4, ความสูงอัตโนมัติ, ไม่มีไฟล์ฟอนต์ | CloudflareRenderResult | CloudflareNotAvailableException, CloudflareRenderException, ความล้มเหลวในการตรวจสอบความถูกต้อง | ตรวจสอบความถูกต้องของขนาด HTML และ URL ของ worker ก่อนทำ input/output (I/O) ผ่านเครือข่าย |
CloudflareHtmlRenderer::getHtmlSecurityPolicy() | ไม่มี | คืนค่านโยบายชั้นการแยกวิเคราะห์ที่กำหนดค่าไว้ | HtmlSecurityPolicyInterface | ไม่คาดว่าจะเกิด | ใช้ควบคู่กับการป้องกันปลายทางและการตรวจสอบความถูกต้องของ URL ของ Worker |
CloudflareHtmlRenderer::isAvailable() | ไม่มี | ส่งคำขอ HEAD ไปยัง worker เมื่อคอนฟิกถูกต้อง | bool | คืนค่า false เมื่อเกิดข้อผิดพลาด | ใช้สำหรับการตรวจสอบความพร้อม ไม่ใช่มาตรการป้องกันขณะรันไทม์เพียงอย่างเดียว |
ออบเจ็กต์ค่าและความปลอดภัยของตัวเรนเดอร์
หัวข้อที่มีชื่อว่า “ออบเจ็กต์ค่าและความปลอดภัยของตัวเรนเดอร์”ใช้ตารางนี้สำหรับออบเจ็กต์ค่าของคำขอและผลลัพธ์ (CloudflareRenderResult, CloudflareRenderPayload) และการตรวจสอบชั้นการขนส่งแบบสแตติก ซึ่งตรวจสอบความถูกต้องของ HTML, URL ของ Worker และการปักหมุด DNS ก่อน I/O เครือข่าย
| สัญลักษณ์ | พารามิเตอร์ | พฤติกรรมเริ่มต้น | คืนค่า | ข้อยกเว้นหรือความล้มเหลว | หมายเหตุ |
|---|---|---|---|---|---|
new CloudflareRenderResult(string $pdfData, float $widthPt, float $heightPt, float $contentHeightPx = 0.0, string $renderLocation = '', float $renderTimeMs = 0.0) | ไบต์ของ PDF, ความกว้าง, ความสูง, ความสูงของเนื้อหาที่วัดได้, ตำแหน่ง edge, เวลาในการเรนเดอร์ | ข้อมูลเมตาจะว่างเปล่าเมื่อ Worker ไม่รายงานข้อมูลดังกล่าว | CloudflareRenderResult | ไม่คาดว่าจะเกิด | โดยปกติ CloudflareResponseParser::parse() จะคืนค่านี้ |
CloudflareRenderResult::isValid() | ไม่มี | ตรวจสอบว่าไบต์ของ PDF ไม่ว่างเปล่าและเริ่มต้นด้วยส่วนหัว PDF | bool | ไม่คาดว่าจะเกิด | ใช้ก่อนการจัดเก็บถาวรหรือส่งไบต์ไปยังชั้นอื่น |
CloudflareRenderResult::size() | ไม่มี | นับไบต์ของ PDF ที่เรนเดอร์แล้ว | int | ไม่คาดว่าจะเกิด | ป้อนเข้าสู่ตรรกะโควตาและการตรวจสอบ |
new CloudflareRenderPayload(string $html, float $widthPt, float $heightPt = 0, string $defaultCss = '', ?string $r2FontBucket = null, array $fontFiles = []) | HTML, ขนาด, CSS, R2 font bucket แบบไม่บังคับ, รายการไฟล์ฟอนต์ | ความสูงอัตโนมัติ, ไม่มี CSS เริ่มต้น, ไม่มี R2 font bucket, ไม่มีไฟล์ฟอนต์ | CloudflareRenderPayload | ไม่คาดว่าจะเกิด | ออบเจ็กต์ค่าเพย์โหลดของคำขอ |
CloudflareRenderPayload::toJson() | ไม่มี | serialize HTML, ขนาด, CSS และการอ้างอิงฟอนต์เป็น JavaScript Object Notation (JSON) สำหรับ Worker | string | ข้อผิดพลาดในการเข้ารหัส JSON | API เพย์โหลดของคำขอระดับล่าง |
CloudflareResponseParser::parse(ResponseInterface $response, float $requestedWidthPt) | การตอบสนองของ Worker และความกว้างที่ร้องขอ | ยอมรับการตอบสนอง PDF แบบไบนารีและการตอบสนอง JSON แบบมีโครงสร้าง | CloudflareRenderResult | CloudflareRenderException สำหรับเอาต์พุตของ Worker ที่ล้มเหลวหรือไม่ถูกต้อง | ตัวแยกวิเคราะห์ส่วนกลางที่ตัวเรนเดอร์ใช้ |
CloudflareSecurityPolicy::validate(string $html, int $maxSize) | อินพุต HTML และขีดจำกัดขนาด | ใช้นโยบายอินพุต HTML ของแพ็กเกจ | void | ข้อยกเว้นการตรวจสอบความถูกต้อง | คงการตรวจสอบอินพุตที่ไม่น่าเชื่อถือไว้นอกขอบเขตของ Worker |
CloudflareSecurityPolicy::validateWorkerUrl(string $url) | URL ของ Worker | แยกวิเคราะห์และตรวจสอบความถูกต้องของปลายทาง | array | ข้อยกเว้นการตรวจสอบความถูกต้อง | ปิดกั้นรูปแบบปลายทางที่ไม่ปลอดภัยก่อน I/O เครือข่าย |
CloudflareSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps) | โฮสต์และรายการ IP ที่ปักหมุด | ยืนยันการปักหมุด DNS ที่คาดหวัง | void | ข้อยกเว้นการตรวจสอบความถูกต้องเมื่อการปักหมุดล้าสมัยหรือไม่ถูกต้อง | ใช้ระหว่างการตรวจสอบด้านปฏิบัติการสำหรับการปรับใช้ที่ปักหมุด |
การป้องกัน API
หัวข้อที่มีชื่อว่า “การป้องกัน API”ใช้ตารางนี้เมื่อป้องกันปลายทางการเรนเดอร์: การตรวจสอบความถูกต้องของคีย์ API, การตรวจสอบขนาดเพย์โหลดและขีดจำกัดอัตรา รวมถึงออบเจ็กต์ผลลัพธ์และส่วนหัวที่ขั้นตอนเหล่านี้สร้างขึ้น
| สัญลักษณ์ | พารามิเตอร์ | พฤติกรรมเริ่มต้น | คืนค่า | ข้อยกเว้นหรือความล้มเหลว | หมายเหตุ |
|---|---|---|---|---|---|
new ApiProtection(ApiProtectionConfig $config, ?ApiKeyValidator $keyValidator = null, ?Closure $clock = null) | คอนฟิกการป้องกัน, ตัวตรวจสอบคีย์แบบไม่บังคับ, นาฬิกาแบบไม่บังคับ | ใช้เวลาระบบเมื่อไม่ได้ระบุนาฬิกา | ApiProtection | ไม่คาดว่าจะเกิด | ฉีดค่านาฬิกาแบบกำหนดได้แน่นอนในการทดสอบ |
ApiProtection::checkRequest(string $clientId, int $payloadSize, string $apiKey = '') | ตัวระบุไคลเอ็นต์, ขนาดเพย์โหลด, คีย์ API แบบไม่บังคับ | คีย์ API ที่ว่างเปล่าได้รับอนุญาตเฉพาะเมื่อคอนฟิกไม่ต้องการคีย์เท่านั้น | ApiProtectionResult | ไม่คาดว่าจะเกิด | ตรวจสอบคีย์ API และขนาด จากนั้นจึงจำกัดอัตรา |
ApiProtection::getRateLimit(string $clientId) | ตัวระบุไคลเอ็นต์ | ไม่บันทึกคำขอ | RateLimitResult | ไม่คาดว่าจะเกิด | ใช้เพื่อเพิ่มส่วนหัวขีดจำกัดอัตรา |
new ApiKeyValidator(array $validKeys = []) | รายการคีย์ข้อความธรรมดาที่ถูกต้อง | รายการที่ว่างเปล่าจะปฏิเสธคีย์ทั้งหมด | ApiKeyValidator | ไม่คาดว่าจะเกิด | จัดเก็บความลับไว้นอกโค้ดและเติมค่าผ่านการกำหนดค่า |
ApiKeyValidator::validate(string $key) | คีย์ดิบ | เปรียบเทียบกับคีย์ข้อความธรรมดาที่กำหนดค่าไว้โดยใช้ตรรกะที่ปลอดภัยต่อเวลา | bool | ไม่คาดว่าจะเกิด | พารามิเตอร์นี้มีความอ่อนไหว อย่าบันทึกคีย์ดิบลงในล็อก |
ApiKeyValidator::addKey(string $key) | คีย์ดิบ | เพิ่มคีย์ที่ผ่านการแฮชลงในอินสแตนซ์ตัวตรวจสอบใหม่ | self | ไม่คาดว่าจะเกิด | ถือว่าอินสแตนซ์ที่คืนค่ามาเป็นตัวตรวจสอบที่อัปเดตแล้ว |
ApiKeyValidator::revokeKey(string $key) | คีย์ดิบ | ลบแฮชที่ตรงกันออกจากอินสแตนซ์ตัวตรวจสอบใหม่ | self | ไม่คาดว่าจะเกิด | ถือว่าอินสแตนซ์ที่คืนค่ามาเป็นตัวตรวจสอบที่อัปเดตแล้ว |
ApiKeyValidator::hashKey(string $key) | คีย์ดิบ | สร้างตัวแทนแฮชสำหรับจัดเก็บ | string | ไม่คาดว่าจะเกิด | อย่าเปิดเผยแฮชในล็อกหรือการตอบสนองต่อไคลเอ็นต์ |
ApiKeyValidator::validateHashed(string $key, array $hashedKeys) | คีย์ดิบและแฮชที่ใช้ตรวจสอบ | เปรียบเทียบกับแฮชที่ระบุในเวลาคงที่ | bool | ไม่คาดว่าจะเกิด | ตัวช่วยระดับล่างสำหรับที่เก็บคีย์แบบกำหนดเอง |
new ApiProtectionConfig(int $maxRequestsPerMinute = 60, int $maxRequestsPerHour = 1000, int $maxPayloadSizeBytes = 10485760, array $allowedOrigins = [], bool $requireApiKey = true, string $apiKeyHeader = 'X-Api-Key', int $rateLimitWindowSeconds = 60) | ขีดจำกัดคำขอ, ขีดจำกัดเพย์โหลด, ออริจินที่อนุญาต, ข้อกำหนดคีย์ API, ชื่อส่วนหัว, ความยาวหน้าต่าง | 60/minute, 1000/hour, เพย์โหลด 10 MiB, ต้องใช้คีย์ API | ApiProtectionConfig | ไม่คาดว่าจะเกิด | สร้างโดยตรงในการทดสอบหรือเติมค่าด้วย fromArray() |
ApiProtectionConfig::fromArray(array $data) | max_requests_per_minute, max_requests_per_hour, max_payload_size_bytes, allowed_origins, require_api_key, api_key_header, rate_limit_window_seconds | คีย์ที่ไม่ได้ระบุจะใช้ค่าเริ่มต้นของคอนสตรักเตอร์ | ApiProtectionConfig | ไม่คาดว่าจะเกิด | ใช้สำหรับการเติมค่าคอนฟิกของเฟรมเวิร์ก |
ApiProtectionConfig::isValid() | ไม่มี | ต้องมีขีดจำกัดที่เป็นค่าบวก รวมถึงค่าขนาดและค่าหน้าต่างที่สอดคล้องกัน | bool | ไม่คาดว่าจะเกิด | ตรวจสอบความถูกต้องก่อนเปิดเผยปลายทาง |
new ApiProtectionResult(bool $allowed, string $denialReason = '', ?RateLimitResult $rateLimit = null) | การตัดสินใจ, เหตุผลการปฏิเสธ, ผลลัพธ์ขีดจำกัดอัตราแบบไม่บังคับ | เหตุผลการปฏิเสธว่างเปล่าและไม่มีผลลัพธ์ขีดจำกัดอัตรา | ApiProtectionResult | ไม่คาดว่าจะเกิด | โดยปกติ ApiProtection::checkRequest() จะคืนค่านี้ |
ApiProtectionResult::toHeaders() | ไม่มี | ส่งออกส่วนหัวขีดจำกัดอัตราเมื่อมีข้อมูลอัตราอยู่ | array<string, string> | ไม่คาดว่าจะเกิด | แนบกับการตอบสนองของ Worker หรือเฟรมเวิร์ก |
new RateLimitResult(bool $allowed, int $remainingRequests, int $retryAfterSeconds, string $clientId) | การตัดสินใจ, จำนวนที่เหลือ, การหน่วงเวลาก่อนลองใหม่, ตัวระบุไคลเอ็นต์ (ID) | ไม่มีค่าเริ่มต้น | RateLimitResult | ไม่คาดว่าจะเกิด | ผลลัพธ์ที่ไม่เปลี่ยนแปลงสำหรับการตรวจสอบหนึ่งครั้ง |
RateLimitResult::toHeaders() | ไม่มี | ส่งออกส่วนหัวขีดจำกัดที่เหลือและการรีเซ็ต | array<string, string> | ไม่คาดว่าจะเกิด | ใช้สำหรับการสังเกตการณ์และการถอยกลับของไคลเอ็นต์ |
new RateLimitEntry(string $clientId, int $requestCount = 0, int $windowStart = 0, int $hourlyCount = 0, int $hourlyWindowStart = 0) | ID ไคลเอ็นต์และตัวนับที่เปลี่ยนแปลงได้ | ตัวนับเริ่มต้นที่ศูนย์ | RateLimitEntry | ไม่คาดว่าจะเกิด | ออบเจ็กต์การติดตามในหน่วยความจำ |
RateLimitEntry::increment() | ไม่มี | เพิ่มค่าตัวนับในหน่วยความจำต่อหนึ่ง client/window | void | ไม่คาดว่าจะเกิด | ตัวช่วยระดับล่างที่ ApiProtection ใช้ |
RateLimitEntry::isExpired(int $windowSeconds) | ความยาวหน้าต่างเป็นวินาที | เปรียบเทียบกับเวลาปัจจุบัน | bool | ไม่คาดว่าจะเกิด | ตัวช่วยการหมดอายุขณะรันไทม์ |
RateLimitEntry::isExpiredAt(int $now, int $windowSeconds) | ค่านาฬิกาและความยาวหน้าต่าง | เปรียบเทียบกับค่านาฬิกาที่ระบุ | bool | ไม่คาดว่าจะเกิด | ตัวช่วยการทดสอบแบบกำหนดได้แน่นอน |
RateLimitEntry::reset() | ไม่มี | รีเซ็ตจำนวนและเวลาเริ่มต้นหน้าต่าง | void | ไม่คาดว่าจะเกิด | ใช้เมื่อหน้าต่างใหม่เริ่มต้น |
การจัดเก็บถาวร R2
หัวข้อที่มีชื่อว่า “การจัดเก็บถาวร R2”ใช้ตารางนี้เมื่อจัดเก็บ PDF ที่เรนเดอร์แล้วใน Cloudflare R2: บริการจัดเก็บถาวร, คอนฟิกของบริการและชนิดคีย์ออบเจ็กต์ รวมถึงผลลัพธ์การอัปโหลดที่ต้องตรวจสอบก่อนเปิดเผย URL
| สัญลักษณ์ | พารามิเตอร์ | พฤติกรรมเริ่มต้น | คืนค่า | ข้อยกเว้นหรือความล้มเหลว | หมายเหตุ |
|---|---|---|---|---|---|
new R2ArchiveManager(R2ArchiveConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory) | คอนฟิก R2 และ HTTP factories/client แบบ PSR | ไม่มีการเรียกเครือข่ายระหว่างการสร้าง | R2ArchiveManager | ข้อผิดพลาดในการเชื่อมต่อคอนเทนเนอร์ | บริการจัดเก็บถาวรหลัก |
R2ArchiveManager::upload(string $pdfData, string $filename, array $metadata = []) | ไบต์ของ PDF ดิบ, ชื่อไฟล์เดิม, ข้อมูลเมตาแบบสตริง | ข้อมูลเมตาว่างเปล่า คีย์ที่แบ่งพาร์ติชันตามวันที่ | R2UploadResult | คืนค่าผลลัพธ์ที่ไม่สำเร็จเมื่อเกิดความล้มเหลวด้านคอนฟิก ขนาด, HTTP หรือการขนส่ง | ไม่เกิดข้อยกเว้นสำหรับความล้มเหลวในการอัปโหลดตามปกติ |
R2ArchiveManager::generateSignedUrl(string $key, int $expiresInSeconds = 3600) | คีย์ออบเจ็กต์และเวลาคงอยู่ (TTL) ของ URL | URL ที่ลงนามแล้วอายุหนึ่งชั่วโมง | string | ข้อผิดพลาดในการลงนามจากคอนฟิกที่ไม่ถูกต้อง | ใช้ TTL ที่สั้นสำหรับ PDF ที่มีความอ่อนไหว |
R2ArchiveManager::buildObjectKey(string $filename) | ชื่อไฟล์เดิม | ใช้คำนำหน้าเส้นทางที่กำหนดค่าไว้และวันที่ปัจจุบัน | R2ObjectKey | ไม่คาดว่าจะเกิด | ใช้สำหรับการแบ่งพาร์ติชันการจัดเก็บถาวรที่คาดการณ์ได้ |
R2ArchiveManager::createPutRequest(R2ObjectKey $key, string $data, array $metadata = []) | คีย์ออบเจ็กต์, ไบต์ดิบ, ข้อมูลเมตา | ลงนามคำขอ PUT | RequestInterface | ข้อผิดพลาดในการสร้างคำขอ | API ระดับล่างสำหรับการขนส่งแบบกำหนดเอง |
new R2ArchiveConfig(string $bucketName, string $accountId, string $accessKeyId, string $secretAccessKey, string $endpoint = '', string $pathPrefix = 'pdfs/', int $maxFileSizeBytes = 104857600) | บัคเก็ต, ID บัญชี, ข้อมูลรับรอง, การแทนที่ปลายทาง, คำนำหน้าคีย์, ขนาดออบเจ็กต์สูงสุด | ปลายทางที่สร้างขึ้น, คำนำหน้า pdfs/, ขนาดออบเจ็กต์สูงสุด 100 MiB | R2ArchiveConfig | InvalidArgumentException สำหรับชื่อบัคเก็ตที่ไม่ถูกต้อง | ถือว่าข้อมูลรับรองเป็นคอนฟิกที่มีความลับ |
R2ArchiveConfig::fromArray(array $data) | ID บัญชี, บัคเก็ต, ข้อมูลรับรอง, คำนำหน้าเส้นทาง, การแทนที่ปลายทาง, ขนาดสูงสุด | ค่าที่ขาดหายไปจะใช้ค่าเริ่มต้นของคอนสตรักเตอร์ | R2ArchiveConfig | ชื่อบัคเก็ตไม่ถูกต้องเมื่อมีการระบุ | ใช้สำหรับการเติมค่าคอนฟิกของแอปพลิเคชัน |
R2ArchiveConfig::isValid() | ไม่มี | ต้องมีบัญชี, บัคเก็ต, คีย์การเข้าถึง และคีย์ลับที่ไม่ว่างเปล่า | bool | ไม่คาดว่าจะเกิด | คอนฟิกที่ไม่ถูกต้องจะทำให้การอัปโหลดล้มเหลวพร้อมผลลัพธ์แบบมีโครงสร้าง |
R2ArchiveConfig::getEndpoint() | ไม่มี | ใช้ปลายทางที่ระบุไว้อย่างชัดเจนหรือสร้างปลายทาง Cloudflare R2 จาก ID บัญชี | string | ไม่คาดว่าจะเกิด | ใช้สำหรับการสร้างคำขอที่ลงนามแล้ว |
new R2ObjectKey(string $key, string $bucket) | คีย์ออบเจ็กต์แบบเต็มและบัคเก็ต | ไม่มีการทำให้เป็นมาตรฐาน | R2ObjectKey | ไม่คาดว่าจะเกิด | โดยปกติ R2ObjectKey::generate() จะสร้างค่านี้ |
R2ObjectKey::generate(string $prefix, string $filename, ?DateTimeInterface $date = null) | คำนำหน้า, ชื่อไฟล์เดิม, วันที่แบบไม่บังคับ | คีย์ออบเจ็กต์ที่แบ่งพาร์ติชันตามวันที่และผ่านการทำความสะอาดแล้ว | R2ObjectKey | ไม่คาดว่าจะเกิด | ฉีดวันที่ในการทดสอบเพื่อให้ได้คีย์ที่กำหนดได้แน่นอน |
R2ObjectKey::fullPath() | ไม่มี | เชื่อมเส้นทางพาร์ติชันและชื่อไฟล์ออบเจ็กต์เข้าด้วยกัน | string | ไม่คาดว่าจะเกิด | จัดเก็บค่านี้เป็นคีย์ออบเจ็กต์ |
new R2UploadResult(bool $success, string $key, string $etag = '', int $size = 0, string $error = '') | แฟล็กความสำเร็จ, คีย์ออบเจ็กต์, entity tag (ETag), ขนาดไบต์, ข้อความแสดงข้อผิดพลาด | ETag ว่างเปล่า, ขนาดเป็นศูนย์, ข้อผิดพลาดว่างเปล่า | R2UploadResult | ไม่คาดว่าจะเกิด | โดยปกติ R2ArchiveManager::upload() จะคืนค่านี้ |
R2UploadResult::isValid() | ไม่มี | ถูกต้องเมื่อการอัปโหลดสำเร็จและมีทั้งคีย์และ ETag อยู่ | bool | ไม่คาดว่าจะเกิด | ตรวจสอบก่อนเปิดเผย URL |
R2UploadResult::publicUrl(string $customDomain = '') | โดเมนสาธารณะแบบกำหนดเองที่ไม่บังคับ | คืนค่าคีย์ออบเจ็กต์เปล่าเมื่อไม่ได้ระบุโดเมนแบบกำหนดเอง | string | ไม่คาดว่าจะเกิด | หลีกเลี่ยงการใช้ URL สาธารณะสำหรับเอกสารที่มีความอ่อนไหว เว้นแต่นโยบายจะอนุญาต |
ตัวช่วยการขนส่ง
หัวข้อที่มีชื่อว่า “ตัวช่วยการขนส่ง”ใช้ตารางนี้สำหรับการเชื่อมต่อระดับล่างเท่านั้น: การปักหมุด Internet Protocol (IP) และ SubjectPublicKeyInfo (SPKI) ในระดับ cURL รวมถึงสัญญาของ local-renderer ที่ใช้เป็นเส้นทางสำรองเมื่อไม่สามารถเข้าถึง Worker ได้
| สัญลักษณ์ | พารามิเตอร์ | พฤติกรรมเริ่มต้น | คืนค่า | ข้อยกเว้นหรือความล้มเหลว | หมายเหตุ |
|---|---|---|---|---|---|
new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30) | factory แบบ PSR-17, IP ที่ปักหมุด, คีย์สาธารณะที่ปักหมุด, การหมดเวลา | ไม่มีการปักหมุดและใช้การหมดเวลา 30 วินาที | PinnedCurlTransport | ไม่คาดว่าจะเกิด | ใช้เฉพาะเมื่อต้องการการปักหมุดในระดับ cURL เท่านั้น |
PinnedCurlTransport::sendRequest(RequestInterface $request) | คำขอแบบ PSR-7 | ส่งผ่าน cURL พร้อมการหมดเวลาและการควบคุมการปักหมุดที่กำหนดค่าไว้ | ResponseInterface | ข้อยกเว้นการขนส่งแบบ PSR-18 | ใช้เฉพาะเมื่อไคลเอ็นต์ HTTP ของเฟรมเวิร์กไม่สามารถบังคับใช้นโยบายการปักหมุดเดียวกันได้ |
PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port) | คำขอ, โฮสต์เป้าหมาย, พอร์ตเป้าหมาย | สร้างอาร์เรย์ตัวเลือก cURL ที่ sendRequest() ใช้ | array | คำขอที่ไม่ถูกต้องหรือข้อผิดพลาดในการกำหนดค่าการปักหมุด | ฮุกการทดสอบและการวินิจฉัยระดับล่าง |
LocalRendererInterface::render(string $html, array $options = []) | HTML และตัวเลือกของตัวเรนเดอร์ | เป็นสัญญาเท่านั้น การนำไปใช้งานจะกำหนดค่าเริ่มต้น | string | ข้อผิดพลาดในการเรนเดอร์เฉพาะของการนำไปใช้งาน | ใช้เป็นการสำรองแบบโลคัลเมื่อการเรนเดอร์ด้วย Worker ไม่พร้อมใช้งาน |
LocalRendererFactoryInterface::create() | ไม่มี | สร้างการนำตัวเรนเดอร์แบบโลคัลไปใช้งาน | LocalRendererInterface | ข้อผิดพลาดด้าน factory หรือการพึ่งพา | แยกการสร้างตัวเรนเดอร์สำรองออกจาก CloudflareHtmlRenderer |
หมายเหตุการพัฒนา
หัวข้อที่มีชื่อว่า “หมายเหตุการพัฒนา”- ถือว่า URL ของ Worker เป็นขอบเขตเครือข่าย ตรวจสอบความถูกต้องของปลายทาง ขนาด และการรับรองความถูกต้องก่อนการเรนเดอร์
- ใช้ผลลัพธ์การป้องกัน API เป็นเอาต์พุตของนโยบาย ไม่ใช่เป็นโฟลว์การควบคุมด้วยข้อยกเว้น
- การอัปโหลด R2 จะคืนค่าผลลัพธ์ความสำเร็จหรือข้อผิดพลาดแบบมีโครงสร้าง ให้จัดการทั้งสองเส้นทาง