Tạo một persisted query

Một persisted query là sự kết hợp giữa GraphQL và REST API: đó là một queries GraphQL thông thường, được xuất bản trên trang web và truy cập qua URL riêng của nó, tương tự như một REST endpoint.

Ví dụ, chúng ta có thể hiển thị dữ liệu cho một trang web thông qua các persisted queries sau:

• /graphql-query/homepage-posts
• /graphql-query/user-widget
• /graphql-query/post-content và thực thi nó bằng cách truyền ID của bài viết: ?post=1
• /graphql-query/post-content/es để dịch nội dung bài viết sang tiếng Tây Ban Nha
• Và các queries khác

​

Thực thi persisted query

Sau khi persisted query được xuất bản, chúng ta có thể thực thi nó qua permalink của nó.

Persisted query có thể được thực thi trực tiếp trong trình duyệt vì nó được truy cập qua GET, và chúng ta sẽ nhận được dữ liệu yêu cầu ở định dạng JSON:

​

Thực thi persisted query trong một ứng dụng

Vui lòng làm theo hướng dẫn trong guide Kết nối với máy chủ GraphQL từ một client.

​

Truy cập tất cả các persisted queries

Nhấp vào "Persisted Queries" trong menu của plugin sẽ hiển thị danh sách tất cả các persisted queries đã tạo:

​

Tạo một persisted query mới

Nhấp vào nút "Add New GraphQL persisted query" để mở trình soạn thảo WordPress:

Đặt tiêu đề và đảm bảo permalink là đúng như mong muốn, nhập queries GraphQL, chọn cấu hình schema và điều chỉnh các tùy chọn. Khi sẵn sàng, nhấp vào nút Publish, và permalink sẽ trở thành endpoint của persisted query.

Liên kết đến endpoint (và đến nguồn) được hiển thị trong bảng điều khiển bên "Persisted Query Endpoint Overview":

Theo mặc định, endpoint của persisted query có đường dẫn /graphql-query/, và giá trị này có thể cấu hình thông qua Cài đặt:

​

Trình soạn thảo queries

Client GraphiQL trong trình soạn thảo là nơi để nhập persisted queries GraphQL:

Trình soạn thảo đi kèm với tiện ích bổ sung Explorer, cho phép soạn queries bằng cách nhấp vào các trường ở bảng điều khiển bên trái. Nhấp vào nút "Run" để thực thi queries, xem trước kết quả phản hồi:

​

Cấu hình schema

Việc xác định ai có thể truy cập các trường được yêu cầu trong persisted query được định nghĩa trong cấu hình schema.

Vì vậy chúng ta phải tạo một cấu hình schema, sau đó chọn nó từ danh sách thả xuống (hoặc không chọn gì, hoặc chọn cái mặc định):

​

Persisted queries riêng tư

Bằng cách đặt trạng thái của Persisted Query là private, endpoint chỉ có thể được truy cập bởi người dùng quản trị. Điều này ngăn dữ liệu của chúng ta bị chia sẻ vô tình với những người dùng không nên có quyền truy cập.

Ví dụ, chúng ta có thể tạo các Persisted Queries riêng tư để hỗ trợ quản lý ứng dụng, chẳng hạn như lấy dữ liệu để tạo báo cáo với các số liệu của mình.

​

Persisted queries được bảo vệ bằng mật khẩu

Nếu chúng ta tạo một Persisted Query cho một khách hàng cụ thể, chúng ta có thể gán mật khẩu cho nó, nhằm cung cấp thêm một lớp bảo mật để chỉ khách hàng đó mới có thể truy cập endpoint.

Khi truy cập lần đầu vào một persisted query được bảo vệ bằng mật khẩu, chúng ta sẽ gặp màn hình yêu cầu nhập mật khẩu:

Sau khi mật khẩu được cung cấp và xác thực, người dùng mới có thể truy cập endpoint mong muốn.

​

Làm cho persisted query trở nên động thông qua tham số URL

Giá trị của mỗi biến có thể được đặt qua một tham số URL (với tên biến) khi thực thi persisted query. Nếu tùy chọn "Do URL params override variables?" được bật, thì tham số URL sẽ được ưu tiên. Ngược lại, giá trị được định nghĩa trong từ điển biến sẽ được ưu tiên (nếu có).

Ví dụ, trong queries này, số lượng kết quả được kiểm soát qua biến $limit, với giá trị mặc định là 3:

Khi thực thi persisted query này, truyền ?limit=5 sẽ thực thi queries trả về 5 kết quả thay thế:

​

Tạo một phân cấp persisted query

Vui lòng đọc hướng dẫn về tạo một phân cấp API.

​

Vô hiệu hóa persisted query

Trong các tùy chọn, đặt "Enabled" thành false để vô hiệu hóa persisted query.

Tính năng này có thể hữu ích khi persisted query là một phần của phân cấp API, nhằm cung cấp hành vi chung cho các persisted queries con của nó, nhưng không cần bản thân nó được thực thi.

​

Mô tả persisted query

Sử dụng trường "Excerpt" trong bảng cài đặt Tài liệu để đặt mô tả cho persisted query.

Tìm thêm thông tin trong guide Thêm mô tả vào API.

​

Kiểm tra persisted query trước khi xuất bản trực tuyến

Một persisted query có trạng thái draft hoặc pending chỉ khả dụng cho người dùng biên tập schema.

Sau đó, chúng ta có thể tạo một persisted query, gán Cấu hình Schema, xuất bản nó ở trạng thái draft hoặc pending, và kiểm tra nó (ví dụ: xác minh rằng các quy tắc Kiểm soát Truy cập của nó là phù hợp).

Sau khi được phê duyệt, chúng ta mới đặt trạng thái của nó là publish, làm cho persisted query khả dụng với tất cả mọi người.

​

Xem nguồn

Thêm ?view=source vào endpoint, nó sẽ hiển thị cấu hình của persisted query (miễn là người dùng đã đăng nhập và vai trò của người dùng có quyền truy cập):

​

Cấu hình trong trình soạn thảo WordPress

Đây là các trường trong phần thân của trình soạn thảo:

Đây là các trường trong cài đặt Tài liệu: