Persisted Queries
ใช้ GraphQL queries เพื่อสร้าง endpoint ที่กำหนดไว้ล่วงหน้าแบบ REST และรับประโยชน์จากทั้งสอง API
คำอธิบาย
ด้วย REST คุณสามารถสร้าง endpoint หลายตัว โดยแต่ละตัวจะคืนค่าชุดข้อมูลที่กำหนดไว้ล่วงหน้า
| ข้อดี | ข้อเสีย |
|---|---|
| ✅ ใช้งานง่าย | ❌ การสร้าง endpoint ทั้งหมดเป็นเรื่องที่น่าเบื่อ |
✅ เข้าถึงได้ผ่าน GET หรือ POST | ❌ โปรเจกต์อาจเกิดปัญหาคอขวดในการรอ endpoint ให้พร้อมใช้งาน |
| ✅ สามารถ cache ได้บนเซิร์ฟเวอร์หรือ CDN | ❌ การสร้างเอกสารประกอบเป็นสิ่งจำเป็น |
| ✅ ปลอดภัย: เปิดเผยเฉพาะข้อมูลที่ตั้งใจไว้ | ❌ อาจช้า (โดยเฉพาะสำหรับแอปมือถือ) เนื่องจากแอปพลิเคชันอาจต้องส่งคำขอหลายครั้งเพื่อดึงข้อมูลทั้งหมด |
ด้วย GraphQL คุณสามารถส่ง query ใดก็ได้ไปยัง endpoint เดียว ซึ่งจะคืนค่าข้อมูลที่ร้องขอมาเท่านั้น
| ข้อดี | ข้อเสีย |
|---|---|
| ✅ ไม่มีการดึงข้อมูลมากหรือน้อยเกินไป | ❌ เข้าถึงได้เฉพาะผ่าน POST เท่านั้น |
| ✅ สามารถรวดเร็วได้ เนื่องจากดึงข้อมูลทั้งหมดในคำขอเดียว | ❌ ไม่สามารถ cache บนเซิร์ฟเวอร์หรือ CDN ได้ ทำให้ช้าและมีค่าใช้จ่ายสูงกว่าที่ควรจะเป็น |
| ✅ ช่วยให้ทำซ้ำโปรเจกต์ได้อย่างรวดเร็ว | ❌ อาจต้องประดิษฐ์สิ่งที่มีอยู่แล้วใหม่ เช่น การอัปโหลดไฟล์หรือการ cache |
| ✅ สามารถสร้างเอกสารประกอบตัวเองได้ | ❌ ต้องจัดการกับความซับซ้อนเพิ่มเติม เช่น ปัญหา N+1 |
| ✅ มีตัวแก้ไข query (GraphiQL) ที่ช่วยลดความยุ่งยาก |
Persisted queries รวมสองแนวทางนี้เข้าด้วยกัน:
- ใช้ GraphQL เพื่อสร้างและประมวลผล queries
- แต่แทนที่จะเปิดเผย endpoint เดียว มันจะเปิดเผย query ที่กำหนดไว้ล่วงหน้าแต่ละตัวภายใต้ endpoint ของตัวเอง
ดังนั้น เราจะได้ endpoint หลายตัวที่มีข้อมูลที่กำหนดไว้ล่วงหน้าแบบ REST แต่สร้างขึ้นด้วย GraphQL ซึ่งได้รับข้อดีจากแต่ละแนวทางและหลีกเลี่ยงข้อเสีย:
| ข้อดี | ข้อเสีย |
|---|---|
✅ เข้าถึงได้ผ่าน GET หรือ POST | |
| ✅ สามารถ cache ได้บนเซิร์ฟเวอร์หรือ CDN | |
| ✅ ปลอดภัย: เปิดเผยเฉพาะข้อมูลที่ตั้งใจไว้ | |
| ✅ ไม่มีการดึงข้อมูลมากหรือน้อยเกินไป | |
| ✅ สามารถรวดเร็วได้ เนื่องจากดึงข้อมูลทั้งหมดในคำขอเดียว | POST เท่านั้น |
| ✅ ช่วยให้ทำซ้ำโปรเจกต์ได้อย่างรวดเร็ว | |
| ✅ สามารถสร้างเอกสารประกอบตัวเองได้ | |
| ✅ มีตัวแก้ไข query (GraphiQL) ที่ช่วยลดความยุ่งยาก |
การรัน Persisted Query
เมื่อ persisted query ได้รับการเผยแพร่แล้ว เราสามารถรันได้ผ่าน permalink ของมัน
persisted query สามารถรันได้โดยตรงในเบราว์เซอร์ เนื่องจากเข้าถึงได้ผ่าน GET และเราจะได้รับข้อมูลที่ร้องขอในรูปแบบ JSON:
การสร้าง Persisted Query
เมื่อคลิกที่ลิงก์ Persisted Queries ในเมนู จะแสดงรายการ persisted queries ทั้งหมดที่สร้างไว้:
persisted query คือ custom post type (CPT) หากต้องการสร้าง persisted query ใหม่ ให้คลิกที่ปุ่ม "Add New GraphQL persisted query" ซึ่งจะเปิด WordPress editor ขึ้นมา:
อินพุตหลักคือ GraphiQL client ซึ่งมาพร้อม Explorer ตามค่าเริ่มต้น การคลิกที่ฟิลด์บนแผงด้านซ้ายจะเพิ่มฟิลด์นั้นลงใน query และการคลิกปุ่ม "Run" จะรัน query:
เมื่อ query พร้อมแล้ว ให้เผยแพร่ และ permalink ของมันจะกลายเป็น endpoint ลิงก์ไปยัง endpoint (และ source) จะแสดงบนแผงด้านข้าง "Persisted Query Endpoint Overview":
การเพิ่ม ?view=source ต่อท้าย permalink จะแสดง persisted query และการตั้งค่าของมัน (ตราบเท่าที่ผู้ใช้ล็อกอินอยู่และ user role มีสิทธิ์เข้าถึง):
ตามค่าเริ่มต้น path ของ endpoint สำหรับ persisted query คือ /graphql-query/ และค่านี้สามารถกำหนดค่าได้ผ่าน Settings:
การตั้งค่า Schema
การกำหนดว่า schema ประกอบด้วยองค์ประกอบใดบ้าง และผู้ใช้จะมีสิทธิ์เข้าถึงอย่างไร นั้นถูกกำหนดไว้ใน schema configuration
ดังนั้น เราต้องสร้าง schema configuration และเลือกจาก dropdown:
การจัด Persisted Queries ตามหมวดหมู่
บนแผงด้านข้าง "Endpoint categories" เราสามารถเพิ่มหมวดหมู่เพื่อช่วยจัดการ Persisted Query:
ตัวอย่างเช่น เราสามารถสร้างหมวดหมู่เพื่อจัดการ endpoint ตาม client, แอปพลิเคชัน หรือข้อมูลที่จำเป็นอื่นๆ:
ในรายการ Persisted Queries เราสามารถดูหมวดหมู่ของแต่ละรายการได้ และการคลิกที่ลิงก์หมวดหมู่ หรือการใช้ตัวกรองด้านบน จะแสดงเฉพาะรายการในหมวดหมู่นั้น:
Persisted queries แบบส่วนตัว
การตั้งค่าสถานะของ Persisted Query เป็น private จะทำให้ endpoint เข้าถึงได้เฉพาะผู้ใช้ที่เป็น admin เท่านั้น ซึ่งป้องกันไม่ให้ข้อมูลของเราถูกแบ่งปันโดยไม่ตั้งใจกับผู้ใช้ที่ไม่ควรมีสิทธิ์เข้าถึง
ตัวอย่างเช่น เราสามารถสร้าง Persisted Queries แบบส่วนตัวที่ช่วยจัดการแอปพลิเคชัน เช่น การดึงข้อมูลเพื่อสร้างรายงานด้วย metrics ของเรา
Persisted queries ที่ป้องกันด้วยรหัสผ่าน
หากเราสร้าง Persisted Query สำหรับ client เฉพาะรายหนึ่ง เราสามารถกำหนดรหัสผ่านเพื่อให้ระดับความปลอดภัยเพิ่มเติม ทำให้มีเฉพาะ client นั้นเท่านั้นที่สามารถเข้าถึง endpoint ได้
เมื่อเข้าถึง persisted query ที่ป้องกันด้วยรหัสผ่านเป็นครั้งแรก เราจะพบหน้าจอที่ขอรหัสผ่าน:
เมื่อป้อนและตรวจสอบรหัสผ่านแล้วเท่านั้น ผู้ใช้จึงจะสามารถเข้าถึง endpoint ที่ต้องการได้
การทำให้ persisted query ไดนามิกผ่านพารามิเตอร์ URL
ค่าสำหรับแต่ละตัวแปรสามารถตั้งค่าได้ผ่านพารามิเตอร์ URL (โดยใช้ชื่อตัวแปร) เมื่อรัน persisted query หากเปิดใช้งานตัวเลือก "Do URL params override variables?" พารามิเตอร์ URL จะมีความสำคัญสูงกว่า หากไม่เปิดใช้งาน ค่าที่กำหนดไว้ใน variables dictionary จะมีความสำคัญสูงกว่า (ถ้ามี)
ตัวอย่างเช่น ใน query นี้ จำนวนผลลัพธ์ถูกควบคุมผ่านตัวแปร $limit โดยมีค่าเริ่มต้นเป็น 3:
เมื่อรัน persisted query นี้ โดยส่ง ?limit=5 จะรัน query ที่คืนค่า 5 ผลลัพธ์แทน:
