walder
v4.1.3
Walder นำเสนอวิธีง่ายๆในการตั้งค่าเว็บไซต์หรือเว็บ API บนกราฟความรู้แบบกระจายอำนาจ กราฟความรู้รวมข้อมูลร่วมกับความหมายของข้อมูลนั้น สิ่งนี้ทำให้สามารถรวมข้อมูลจากกราฟความรู้หลายอย่างแม้ว่าบุคคลที่แตกต่างกัน แต่บุคคลที่เป็นอิสระจะรักษาหรือโฮสต์ไว้ กราฟความรู้สามารถโฮสต์ผ่านพ็อดที่เป็นของแข็งจุดสิ้นสุดของ Sparql, อินเทอร์เมนต์ชิ้นส่วนรูปแบบสามรูปแบบ, ไฟล์ RDF และอื่น ๆ การใช้การเจรจาต่อรองเนื้อหา Walder ทำให้ข้อมูลในกราฟความรู้เหล่านี้พร้อมใช้งานกับลูกค้าผ่าน HTML, RDF และ JSON-LD ผู้ใช้กำหนดในไฟล์กำหนดค่าที่ข้อมูล Walder ใช้และวิธีการประมวลผลข้อมูลนี้ ค้นหาว่า API ใดที่สร้างขึ้นด้วย Walder ที่นี่
สารบัญ
ติดตั้ง Walder ทั่วโลกผ่าน yarn global add walder
เพื่อการพัฒนาทำตามขั้นตอนเหล่านี้:
yarn install$ yarn global add file:$(pwd) Walder มีให้บริการเป็นไลบรารี CLI และ JavaScript
Usage: walder [options]
Options:
-v, --version output the version number
-c, --config < configFile > YAML configuration file input
-p, --port [portNumber] server port number (default: 3000)
-l, --log [level] enable logging and set logging level (one of [error, warn, info, verbose, debug]) (default: " info " )
--no-cache disable Comunica default caching
--lenient turn Comunica errors on invalid data into warnings
-h, --help output usage information // From the root directory
const Walder = require ( '.' ) ;
const configFilePath = 'path/to/configfile' ;
const port = 9000 ; // Defaults to 3000
const logging = 'info' ; // Defaults to 'info'
const cache = false ; // Defaults to true
const lenient = true ; // Defaults to false
const walder = new Walder ( configFilePath , { port , logging , cache , lenient , cwd } ) ;
walder . activate ( ) ; // Starts the server
walder . deactivate ( ) ; // Stops the serverคุณเขียนไฟล์กำหนดค่าใน YAML ตามข้อกำหนดของ OpenAPI 3.0 ไฟล์กำหนดค่าต้องมีโครงสร้างต่อไปนี้:
openapi : 3.0.2
info : # OpenAPI metadata
title : ' Example site '
version : 0.1.0
x-walder-resources : # Directories used by Walder - OPTIONAL
root : # Path to the root folder of the directories used by Walder (absolute or relative to the directory containing the config file) - OPTIONAL (default: .)
views : # Path to directory containing view template files (absolute or relative to the root folder) - OPTIONAL (default: views)
pipe-modules : # Path to directory containing local pipe modules (absolute or relative to the root folder) - OPTIONAL (default: pipe-modules)
public : # Path to directory containing all files that should be available statically (e.g. stylesheets) (absolute or relative to the root folder) - OPTIONAL (default: public)
layouts : # Path to directory containing all layout template files that can be used by view template files (absolute or relative to the root folder) - OPTIONAL (default: layouts)
x-walder-datasources : # Default list of data sources
- ... # E.g. link to SPARQL endpoint or a GraphQL-LD query
paths : # List of path entries
path-entry-1 :
...
path-entry-2 :
...
x-walder-errors : # Default error page views - status codes with files containing the HTML view template (absolute path or relative to the views directory)
404 : ...
500 : ...
... คีย์ x-walder-resources ของไฟล์ config มีพา ธ ไปยังไดเรกทอรีที่ใช้โดย Walder คีย์นี้และค่านี้เป็นทางเลือก หากผู้ใช้ไม่ให้เส้นทาง Walder ใช้ค่าเริ่มต้นต่อไปนี้เทียบกับไดเรกทอรีของไฟล์กำหนดค่า
root : .
views : views
pipe-modules : pipe-modules
public : public
layouts : layouts เพื่อป้องกันไม่ให้วอลเดอร์เผยแพร่ไฟล์ที่ไม่ถูกต้องต่อสาธารณะเมื่อผู้ใช้ไม่ได้ให้เส้นทางไปยังสาขา public วอลเดอร์สร้างไดเรกทอรีใหม่ public หากไม่พบไดเรกทอรีนี้ในไดเรกทอรีการทำงานปัจจุบันและใช้อันนั้น
รายการเส้นทางกำหนดเส้นทางและมีโครงสร้างต่อไปนี้:
path : # The path linked to this query
request : # The HTTP request type (GET, POST, etc.)
summary : ... # Short description
parameters : # Path variables/Query parameters
- in : ... # 'path' or 'query'
name : ... # Name of the parameter
schema :
type : ... # Type of the parameter
description : ... # Description of the parameter
x-walder-query :
graphql-query : ... # One or more GraphQL queries
json-ld-context : ... # The JSON-LD corresponding to the GraphQL query
sparql-query : ... # One or more SPARQL queries
json-ld-frame : ... # A JSON-LD frame that should be applied to the result of a SPARQL query
options : # Global options that will be applied to all the graphql-queries of this path (OPTIONAL)
datasources : # Query specific datasources (OPTIONAL)
additional : ... # Boolean stating that the following datasources are meant to be used on top of the default ones
sources : # List of query specific datasources
- ... # E.g. link to SPARQL endpoint
x-walder-postprocessing : # The (list of) pipe modules used for postprocessing
module-id : # Identifier of the pipe module
source : ... # Path leading to source code of the pipe module (absolute path or relative to the pipe-modules directory)
parameters : # the parameters for the pipe module (OPTIONAL)
- _data # (DEFAULT) this gives all the data, but all paths in the data object are supported (e.g. _data.0.employee)
- ... # Additional parameters if your function supports those (OPTIONAL)
responses : # Status codes with files containing the HTML view template (absolute path or relative to the views directory)
200 : ... # (REQUIRED)
500 : ... # (OPTIONAL)คำสั่งต่อไปนี้เริ่มต้นเซิร์ฟเวอร์บนพอร์ต 3000 (เริ่มต้น) โดยใช้ไฟล์กำหนดค่าตัวอย่าง
$ walder -c example/config.yaml
สิ่งนี้จะเริ่มต้นเซิร์ฟเวอร์บน localhost:3000 ด้วยเส้นทางต่อไปนี้:
ในรายการ PATH ด้านบน options ที่ผู้ใช้กำหนดเป็นตัวระบุทั่วโลก (ไม่บังคับ) ที่ Walder ใช้สำหรับการสืบค้นทุกเส้นทางของเส้นทางนั้น เรามีสองตัวเลือกที่เราสามารถเลือกได้: sort และ remove-duplicates ด้วยไวยากรณ์ที่กำหนด:
options :
sort : # Enable sorting on the data (OPTIONAL)
object : # JSONPath to the object you want to sort for
selectors : # The values inside the object over which you want to sort
- ... # The default option when you want ascending order, just give the value (JSONPath notation supported for further nesting)
- value : ... # When you want descending order, specify the value/order (JSONPath notation supported for further nesting)
order : desc
remove-duplicates : # Enable the removal of duplicates of the data (OPTIONAL)
object : ... # The JSONPath tot the object that you want to compare
value : ... # The value that has to be compared to determine whether it's duplicate (JSONPath notation is also supported for further nesting) หากคุณไม่ต้องการให้ options เป็นสากลสำหรับเส้นทางทั้งหมดคุณสามารถกำหนด options ต่อการสืบค้น
path : # The path linked to this query
request : # The HTTP request type (GET, POST, etc.)
summary : ... # Short description
parameters : # Path variables/Query parameters
- in : ... # 'path' or 'query'
name : ... # Name of the parameter
schema :
type : ... # Type of the parameter
description : ... # Description of the parameter
x-walder-query :
graphql-query : ... # One or more GraphQL queries
name :
query : ... # The GraphQL query
options : # options that will be applied only to this specific graphql-query (OPTIONAL)
...คำสั่งต่อไปนี้เริ่มต้นเซิร์ฟเวอร์โดยใช้ไฟล์กำหนดค่านี้
$ walder -c example/config-sorting-duplicates.yaml
สิ่งนี้จะเริ่มต้นเซิร์ฟเวอร์บน localhost:3000 ด้วยเส้นทางต่อไปนี้:
คุณสามารถแยกไฟล์กำหนดค่าในหลายไฟล์โดยใช้คำหลัก $ref เราทำตามข้อมูลจำเพาะ OpenAPI 3.0 ที่อธิบายวิธีการใช้การอ้างอิง
เมื่ออ้างอิงครั้งแรกคุณต้องใช้เส้นทางที่เริ่มต้นจากไดเรกทอรีของไฟล์กำหนดค่า แต่ถ้าไฟล์อ้างอิงมีการอ้างอิงเองมันสามารถใช้เส้นทางที่สัมพันธ์กับตำแหน่งของตัวเองดังที่แสดงด้านล่าง
ไฟล์กำหนดค่าจริงที่อ้างอิงเส้นทางของมัน
openapi : 3.0.2
info :
title : ' Example site '
version : 0.1.0
x-walder-resources :
path : ./
views : views
pipe-modules : pipeModules
public : public
x-walder-datasources :
- http://fragments.dbpedia.org/2016-04/en
paths :
/music/{musician} :
$ref : ' ./paths/music_musician.yaml '
/movies/{actor} :
$ref : ' ./paths/movies_actor.yaml '
x-walder-errors :
404 :
description : page not found error
x-walder-input-text/html : error404.html
500 :
description : internal server error
x-walder-input-text/html : error500.html ด้านล่างคุณเห็น ./example/paths/movies_actor.yaml พร้อมการอ้างอิงกับเส้นทางที่สัมพันธ์กับตำแหน่งของตัวเอง
get :
summary : Returns a list of the all movies the given actor stars in
parameters :
- in : path
name : actor
required : true
schema :
type : string
description : The target actor
x-walder-query :
$ref : ' ../walderQueryInfo/movies_actor_info.yaml '
responses :
200 :
description : list of movies
x-walder-input-text/html : movies.pug
ใช้การเจรจาต่อรองเนื้อหา Walder ทำให้รูปแบบผลลัพธ์ต่อไปนี้พร้อมใช้งาน:
Walder ใช้ graphql-ld-comunica เพื่อดำเนินการค้นหา graphql และ @comunica/query-sparql เพื่อดำเนินการสืบค้น SPARQL ผลลัพธ์ของการสืบค้น GraphQL-LD คือข้อมูล JSON Walder แปลงเป็น JSON-LD เป็นครั้งแรก สิ่งนี้ช่วยให้สามารถแปลงเป็นรูปแบบ RDF อื่น ๆ ในระหว่างการเจรจาต่อรองเนื้อหา ผลลัพธ์ของการสืบค้น SPARQL คืออาร์เรย์ของสี่เหลี่ยมจัตุรัส หากมีการระบุเฟรม JSON-LD จะมีการแปลงเป็น quads เป็น JSON-LD เนื่องจากความสำคัญของการเจรจาต่อรองเนื้อหาสนับสนุนการสร้างแบบสอบถามเท่านั้น
Walder ใช้การรวมเพื่อดึงเอ็นจิ้นที่เกี่ยวข้องโดยอัตโนมัติสำหรับเทมเพลตที่กำหนด ซึ่งหมายความว่าเครื่องยนต์เทมเพลตที่รองรับนั้นขึ้นอยู่กับการรวม
คุณสามารถใช้เอ็นจิ้นเทมเพลตที่แตกต่างกันสำหรับเส้นทางที่แตกต่างกันเช่น PUG ทำให้ HTML ของเส้นทางหนึ่งเส้นทางในขณะที่แฮนด์บาร์ทำให้ HTML ของเส้นทางอื่น Walder ทำสิ่งนี้ทั้งหมดโดยดูที่ส่วนขยายไฟล์ของเทมเพลตที่กำหนด
เทมเพลตสามารถใช้ในมุมมองเช่นเดียวกับในเลย์เอาต์ ดังนั้นเราจะตั้งชื่อพวกเขา ดูเทมเพลต และ เทมเพลตเลย์เอาต์ เพื่อแยกแยะ
ผลลัพธ์ของการสืบค้นที่ระบุไว้ในไฟล์การกำหนดค่าสำหรับเส้นทางมีให้สำหรับการแสดงผลในเทมเพลตมุมมองเป็นข้อมูล
data ในกรณีของการสืบค้น GraphQL-LD แต่ละวัตถุจะเป็นอาร์เรย์เว้นแต่ว่าแบบสอบถามจะถูกทำให้เป็นเอกเทศ songs.handlebars เป็นตัวอย่างของการบริโภคผลลัพธ์ของการสืบค้นเดียวในเส้นทาง /music/{musician} ในไฟล์กำหนดค่านี้ songes_movies.handlebars เป็นตัวอย่างของการบริโภคผลลัพธ์ของการสืบค้นทั้งสองในเส้นทาง /artist/{artist} ในไฟล์การกำหนดค่านี้
ในกรณีของการสืบค้น SPARQL แต่ละวัตถุเป็นอาร์เรย์ของ Quads หากไม่มีการระบุเฟรม JSON-LD มิฉะนั้นมันจะเป็นวัตถุ JSON-LD
การใช้เลย์เอาต์เป็นวิธีที่ยอดเยี่ยมในการหลีกเลี่ยงการทำซ้ำในเทมเพลตมุมมองเฉพาะเส้นทาง โครงสร้าง HTML ที่นำกลับมาใช้ใหม่ได้เช่นส่วนหัวส่วนท้าย, แถบการนำทางและเนื้อหาอื่น ๆ ซึ่งหมายถึงการปรากฏในหลายเส้นทางตามที่ระบุไว้ใน ไฟล์เลย์เอาต์
ไฟล์เทมเพลตเลย์เอาต์สามารถระบุได้ในไฟล์เทมเพลตมุมมองโดยใช้ layout ฟิลด์เมตาดาต้าด้านหน้า ควรมีชื่อไฟล์ที่มีอยู่ที่ตำแหน่ง layouts ที่กำหนดไว้ในไฟล์กำหนดค่า มันอาจมีเส้นทางสัมพัทธ์ด้านหน้าของชื่อไฟล์
ตัวอย่างมุมมองไฟล์เทมเพลตที่ระบุเค้าโครง:
---
layout: my-layout.pug
---
// view template continues here
Walder วางเนื้อหา HTML ภายในที่สร้างขึ้นจากไฟล์เทมเพลตมุมมองลงในข้อมูลที่ส่งต่อไปยังไฟล์เทมเพลตเลย์เอาต์เป็นวัตถุที่ชื่อ content
ไฟล์เทมเพลตเลย์เอาต์เป็นเทมเพลตอื่น มันมักจะขยายเนื้อหา HTML ภายในเหล่านี้ที่ตำแหน่งที่เลือก
ตัวอย่าง ปั๊ก ง่าย ๆ (คิดว่า !{content} ):
doctype html
html(lang="en")
head
title I'm based on a layout
body !{content}
นอกเหนือจากผลลัพธ์การสืบค้นแล้ว Walder ยังเพิ่มข้อมูลเมตาด้านหน้าที่ระบุไว้ในเทมเพลตมุมมองซึ่งเป็นคุณลักษณะเพิ่มเติมของข้อมูล
ชื่อของแอตทริบิวต์เพิ่มเติมแต่ละชื่อเท่ากับชื่อฟิลด์ข้อมูลเมตา ฟิลด์ข้อมูลเมตาต่อไปนี้สงวนไว้: layout content data และชื่อที่กำหนดให้กับการสืบค้นในเส้นทางที่มีแบบสอบถามหลายรายการ (ดูด้านบน)
แอตทริบิวต์เหล่านี้พร้อมใช้งานสำหรับเทมเพลตมุมมองและเทมเพลตเลย์เอาต์ที่อ้างถึงถ้ามี
ตัวอย่างมุมมองไฟล์เทมเพลตระบุฟิลด์ข้อมูลเมตาด้านหน้าและอ่านฟิลด์นั้น (โปรดทราบ #{a1} )::
--
a1: Value for FrontMatter attribute a1!
---
doctype html
html(lang="en")
body
main a1: #{a1}
ตัวอย่างไฟล์ดูเทมเพลตระบุเทมเพลตเค้าโครงและฟิลด์ข้อมูลเมตาดาต้าด้านหน้าอื่น ๆ :
---
layout: layout-fm.pug
a2: Value for FrontMatter attribute a2!
---
main Lorem ipsum
ตัวอย่างเทมเพลตเค้าโครงที่สอดคล้องกัน (layout-fm.pug) อ่านฟิลด์นั้น (คิด #{a2} ):
doctype html
html(lang="en")
head
if a2
title #{a2}
body !{content}
ในขณะที่แยกวิเคราะห์ไฟล์กำหนดค่า Walder ยังตรวจสอบความถูกต้องและความสมบูรณ์ของอินพุต เมื่อวอลเดอร์ได้แยกวิเคราะห์ไฟล์กำหนดค่าทั้งหมดและพบข้อผิดพลาด Walder จะส่งคืนข้อผิดพลาดและออกทั้งหมด
ในขณะนี้วอลเดอร์ตรวจสอบสิ่งต่อไปนี้:
200~x-walder-input-text/html วอลเดอร์ผูกหน้าข้อผิดพลาดกับรหัสสถานะ HTTP ที่แน่นอน คุณสามารถกำหนดหน้าข้อผิดพลาดเริ่มต้น แต่ยังรวมถึงหน้าข้อผิดพลาดเฉพาะของเส้นทางโดยเพิ่มลงในคีย์ responses ในรายการพา ธ ที่สอดคล้องกัน
404 : ไม่พบหน้าเว็บ500 : ข้อผิดพลาดของเซิร์ฟเวอร์ภายใน 500 : ไม่สามารถใช้โมดูลท่อที่กำหนดได้ 404 : ไม่ได้รับตัวแปรที่คาดหวัง500 : ไม่สามารถเรียกใช้แบบสอบถามที่กำหนดได้เมื่อคุณเรียกใช้ Walder โดยใช้คำสั่งต่อไปนี้:
$ walder -c example/config-errors.yaml
เส้นทางต่อไปนี้นำไปสู่ข้อผิดพลาด:
404 (ไม่พบหน้า: หน้า)500 (โมดูลท่อ: ไม่สามารถใช้โมดูลท่อที่กำหนด)500 (graphql-ld: ไม่สามารถดำเนินการค้นหาที่กำหนด) ข้อความที่ตัดตอนมาจากไฟล์กำหนดค่าต่อไปนี้จะใช้เทมเพลตดู moviesServerError.handlebars เฉพาะพา ธ บนข้อผิดพลาดที่นำไปสู่รหัสสถานะ 500 เมื่อนำทางไปยัง /movies
เมื่อไม่ผ่าน actor พารามิเตอร์การสืบค้น Walder จะส่งคืนรหัสสถานะ 404 Walder จะใช้ไฟล์ error404.html เริ่มต้นเนื่องจากไฟล์ config ไม่มีเทมเพลตมุมมอง HTML เฉพาะพา ธ สำหรับสถานะที่เกี่ยวข้อง
...
paths :
/movies :
get :
summary : Returns a list of the all movies the given actor stars in
parameters :
- in : query
name : actor
schema :
type : string
minimum : 0
description : The actor from whom the movies are requested
required : true
x-walder-query :
graphql-query : >
{
id @single
... on Film {
starring(label: $actor) @single
}
}
json-ld-context : >
{
"@context": {
"Film": "http://dbpedia.org/ontology/Film",
"label": { "@id": "http://www.w3.org/2000/01/rdf-schema#label", "@language": "en" },
"starring": "http://dbpedia.org/ontology/starring"
}
}
responses :
200 :
description : list of movies
x-walder-input-text/html : movies.pug
500 :
description : internal movie server error
x-walder-input-text/html : moviesServerError.handlebars
x-walder-errors :
404 :
description : page not found error
x-walder-input-text/html : error404.html
500 :
description : internal server error
x-walder-input-text/html : error500.html ในขณะที่พัฒนาเว็บไซต์ของคุณคุณอาจต้องการให้เว็บไซต์ของคุณโหลดซ้ำในขณะที่ทำการเปลี่ยนแปลงใน config.yaml คุณสามารถทำได้อย่างง่ายดายโดยใช้ NPM-Watch ดู package.json ตัวอย่าง Json ด้านล่างเกี่ยวกับวิธีการเริ่มต้น
{
"watch" : {
"run" : " config.yaml "
},
"scripts" : {
"run" : " walder -c config.yaml --no-cache " ,
"watch" : " npm-watch "
},
"dependencies" : {
"walder" : " ^2.0.1 "
},
"devDependencies" : {
"npm-watch" : " ^0.7.0 "
}
} เรียกใช้ npm run watch และ Walder Reloads ทุก config.yaml เปลี่ยน!
| ห้องสมุด | ใบอนุญาต |
|---|---|
| @comunica | มิกซ์ |
| ยอมรับ | มิกซ์ |
| ซอกซอก | มิกซ์ |
| ไค | มิกซ์ |
| ผู้บังคับบัญชา | มิกซ์ |
| รวม | มิกซ์ |
| การดีบัก | มิกซ์ |
| ด่วน | มิกซ์ |
| คนหน้า | มิกซ์ |
| FS-Extra | มิกซ์ |
| graphql-ld | มิกซ์ |
| graphql-ld-comunica | มิกซ์ |
| มือจับ | มิกซ์ |
| is-html | มิกซ์ |
| หยกไปกับมือ | มิกซ์ |
| json-refs | มิกซ์ |
| jsonld | BSD-3-clause |
| jsonpath | มิกซ์ |
| Markdown-it | มิกซ์ |
| มอคค่า | มิกซ์ |
| มอร์แกน | มิกซ์ |
| N3 | มิกซ์ |
| เส้นทางวัตถุ | มิกซ์ |
| ตัก | มิกซ์ |
| สุดยอด | มิกซ์ |
| TMP | มิกซ์ |
| วินสตัน | มิกซ์ |
| ยม | ISC |
คุณสร้างบางสิ่งบางอย่าง Walder และต้องการเพิ่มลงในรายการหรือไม่? โปรดสร้างคำขอดึง!
รหัสนี้มีลิขสิทธิ์© 2019–2020 โดย Ghent University - IMEC และเปิดตัวภายใต้ใบอนุญาต MIT
