การสร้าง Persisted Query

Persisted Query คือการผสมผสานระหว่าง GraphQL และ REST API โดยเป็น GraphQL query ปกติที่เผยแพร่บนไซต์และเข้าถึงได้ผ่าน URL ของตัวเอง คล้ายกับ REST endpoint

ตัวอย่างเช่น เราสามารถเปิดเผยข้อมูลสำหรับเว็บไซต์ผ่าน persisted queries ดังต่อไปนี้:

/graphql-query/homepage-posts
/graphql-query/user-widget
/graphql-query/post-content และรันโดยส่ง ID ของโพสต์: ?post=1
/graphql-query/post-content/es เพื่อแปลเนื้อหาของโพสต์เป็นภาษาสเปน
และอื่นๆ

ตัวแก้ไข Persisted Query

การรัน Persisted Query

เมื่อเผยแพร่ persisted query แล้ว เราสามารถรันมันผ่าน permalink ของมันได้

Persisted query สามารถรันได้โดยตรงในเบราว์เซอร์ เนื่องจากเข้าถึงผ่าน GET และเราจะได้รับข้อมูลที่ร้องขอในรูปแบบ JSON:

การรัน Persisted Query ในเบราว์เซอร์

การรัน Persisted Query ในแอปพลิเคชัน

โปรดทำตามคำแนะนำในคู่มือ การเชื่อมต่อกับ GraphQL server จาก client

การเข้าถึง Persisted Queries ทั้งหมด

การคลิก "Persisted Queries" ในเมนูของปลั๊กอิน จะแสดงรายการ persisted queries ทั้งหมดที่สร้างไว้:

การสร้าง Persisted Query ใหม่

คลิกปุ่ม "Add New GraphQL persisted query" เพื่อเปิดตัวแก้ไข WordPress:

การสร้าง Persisted Query

ตั้งชื่อและตรวจสอบให้แน่ใจว่า permalink ถูกต้องตามที่คาดหวัง ป้อน GraphQL query เลือกการตั้งค่า schema และปรับตัวเลือกต่างๆ เมื่อพร้อมแล้ว คลิกปุ่ม Publish จากนั้น permalink จะกลายเป็น endpoint ของ persisted query

ลิงก์ไปยัง endpoint (และไปยัง source) จะแสดงอยู่ในแผงด้านข้าง "Persisted Query Endpoint Overview":

Persisted Query Endpoint Overview

โดยค่าเริ่มต้น endpoint ของ persisted query มีเส้นทาง /graphql-query/ และค่านี้สามารถปรับแต่งได้ผ่านการตั้งค่า:

ตัวแก้ไข Query

GraphiQL client ในตัวแก้ไขคือที่ที่ใช้ป้อน GraphQL persisted query:

GraphiQL client ของ Persisted Query

ตัวแก้ไขมาพร้อมกับส่วนเสริม Explorer ที่ช่วยให้คุณสามารถสร้าง query ได้โดยการคลิกที่ฟิลด์บนแผงด้านซ้าย การคลิกปุ่ม "Run" จะรัน query เพื่อดูตัวอย่างการตอบสนอง:

การสร้าง Persisted Query ด้วย Explorer

การตั้งค่า Schema

การกำหนดว่าใครสามารถเข้าถึงฟิลด์ที่ร้องขอใน persisted query นั้นถูกกำหนดไว้ใน schema configuration

ดังนั้นเราต้องสร้าง schema configuration แล้วเลือกจาก dropdown (หรือใช้ none หรือค่าเริ่มต้น):

การเลือก Schema Configuration

Persisted Queries แบบส่วนตัว

การตั้งสถานะของ Persisted Query เป็น private จะทำให้ endpoint เข้าถึงได้เฉพาะผู้ดูแลระบบเท่านั้น ซึ่งป้องกันไม่ให้ข้อมูลของเราถูกแชร์โดยไม่ตั้งใจกับผู้ใช้ที่ไม่ควรมีสิทธิ์เข้าถึง

ตัวอย่างเช่น เราสามารถสร้าง Private Persisted Queries ที่ช่วยในการจัดการแอปพลิเคชัน เช่น การดึงข้อมูลเพื่อสร้างรายงานจากเมตริกของเรา

Private Persisted Query

Persisted Queries ที่ป้องกันด้วยรหัสผ่าน

หากเราสร้าง Persisted Query สำหรับ client เฉพาะราย เราสามารถกำหนดรหัสผ่านให้กับมันได้ เพื่อเพิ่มระดับความปลอดภัยที่ทำให้เฉพาะ client รายนั้นเท่านั้นที่สามารถเข้าถึง endpoint ได้

Persisted Query ที่ป้องกันด้วยรหัสผ่าน

เมื่อเข้าถึง persisted query ที่ป้องกันด้วยรหัสผ่านเป็นครั้งแรก เราจะพบหน้าจอที่ขอรหัสผ่าน:

Persisted Query ที่ป้องกันด้วยรหัสผ่าน: การเข้าถึงครั้งแรก

เมื่อกรอกและยืนยันรหัสผ่านแล้ว ผู้ใช้จึงจะสามารถเข้าถึง endpoint ที่ต้องการได้

การทำให้ Persisted Query เป็นแบบ Dynamic ผ่านพารามิเตอร์ URL

ค่าของแต่ละตัวแปรสามารถกำหนดได้ผ่านพารามิเตอร์ URL (โดยใช้ชื่อตัวแปร) เมื่อรัน persisted query หากเปิดใช้งานตัวเลือก "Do URL params override variables?" พารามิเตอร์ URL จะมีความสำคัญก่อน มิฉะนั้น ค่าที่กำหนดไว้ใน variables dictionary จะมีความสำคัญก่อน (ถ้ามี)

ตัวอย่างเช่น ใน query นี้ จำนวนผลลัพธ์ถูกควบคุมผ่านตัวแปร $limit โดยมีค่าเริ่มต้นเป็น 3:

การใช้ตัวแปรใน Persisted Query

เมื่อรัน persisted query นี้ โดยส่ง ?limit=5 จะรัน query และคืนค่า 5 ผลลัพธ์แทน:

การแทนที่ค่าตัวแปรใน Persisted Query

การสร้างลำดับชั้น Persisted Query

โปรดอ่านคำแนะนำใน การสร้างลำดับชั้น API

การปิดใช้งาน Persisted Query

ในตัวเลือก ตั้งค่า "Enabled" เป็น false เพื่อปิดใช้งาน persisted query

ฟีเจอร์นี้มีประโยชน์เมื่อต้องการให้ persisted query เป็นส่วนหนึ่งของลำดับชั้น API เพื่อให้พฤติกรรมร่วมกับ persisted queries ลูก แต่โดยตัวมันเองไม่จำเป็นต้องถูกรัน

การเพิ่มคำอธิบายให้ Persisted Query

ใช้ฟิลด์ "Excerpt" จากแผง Document settings เพื่อเพิ่มคำอธิบายให้กับ persisted query

ดูข้อมูลเพิ่มเติมได้ในคู่มือ การเพิ่มคำอธิบายให้กับ API

การทดสอบ Persisted Query ก่อนเผยแพร่ออนไลน์

Persisted query ที่มีสถานะ draft หรือ pending จะใช้งานได้เฉพาะผู้ใช้ schema editor เท่านั้น

จากนั้น เราสามารถสร้าง persisted query กำหนด Schema Configuration เผยแพร่เป็น draft หรือ pending และทดสอบมัน (เช่น: ตรวจสอบว่ากฎ Access Control เหมาะสม)

เมื่อได้รับการอนุมัติแล้ว จึงค่อยตั้งสถานะเป็น publish เพื่อให้ persisted query พร้อมใช้งานสำหรับทุกคน

การดู Source

การเพิ่ม ?view=source ต่อท้าย endpoint จะแสดงการตั้งค่าของ persisted query (ตราบใดที่ผู้ใช้เข้าสู่ระบบแล้วและ user role มีสิทธิ์เข้าถึง):

Source ของ Persisted Query

การตั้งค่าในตัวแก้ไข WordPress

นี่คือ input ในส่วนเนื้อหาของตัวแก้ไข:

Input	คำอธิบาย
Title	ชื่อของ persisted query
GraphiQL client	ตัวแก้ไขสำหรับเขียนและรัน GraphQL query: เขียน query ใน textarea ประกาศตัวแปรภายใน query และประกาศค่าของมันใน variables input ที่ด้านล่าง คลิกปุ่ม "Run" เพื่อรัน query ดูผลลัพธ์ใน input ทางด้านขวา คลิก "Docs" เพื่อตรวจสอบข้อมูล schema Explorer (แสดงเฉพาะเมื่อเปิดใช้งานโมดูล `GraphiQL Explorer`) ช่วยให้คุณคลิกที่ฟิลด์และจะถูกเพิ่มลงใน query โดยอัตโนมัติ
Schema configuration	จาก dropdown เลือก schema configuration ที่ใช้กับ persisted query หรือหนึ่งในตัวเลือกเหล่านี้: `"Default"`: ใช้ schema configuration ที่เลือกไว้ในการตั้งค่าของปลั๊กอิน `"None"`: persisted query จะไม่มีข้อจำกัด `"Inherit from parent"`: ใช้ schema configuration เดียวกับ persisted query หลัก ตัวเลือกนี้ใช้งานได้เมื่อเปิดใช้งานโมดูล `API Hierarchy` และ persisted query มี parent query (เลือกในการตั้งค่า Document)
Options	ปรับแต่งพฤติกรรมของ persisted query: Enabled?: ว่า persisted query เปิดใช้งานอยู่หรือไม่ มีประโยชน์ในการปิดใช้งาน persisted query ที่เป็น parent query ใน API hierarchy Do URL params override variables?: อนุญาตให้พารามิเตอร์ URL แทนที่ค่าของตัวแปรที่กำหนดไว้ใน GraphiQL client Inherit query from ancestor(s)?: ใช้ query เดียวกับ persisted query หลัก ตัวเลือกนี้ใช้งานได้เมื่อเปิดใช้งานโมดูล `API Hierarchy` และ persisted query มี parent query (เลือกในการตั้งค่า Document)

นี่คือ input ในการตั้งค่า Document:

Input	คำอธิบาย
Permalink	endpoint ที่ persisted query จะพร้อมใช้งาน
Categories	สามารถจัดหมวดหมู่ persisted query ได้ เช่น: `mobile`, `app` เป็นต้น
Excerpt	ใส่คำอธิบายสำหรับ persisted query Input นี้ใช้งานได้เมื่อเปิดใช้งานโมดูล `Excerpt as Description`
Page attributes	เลือก persisted query หลัก Input นี้ใช้งานได้เมื่อเปิดใช้งานโมดูล `API Hierarchy`