walder
v4.1.3
Walderは、分散型の知識グラフの上にWebサイトまたはWeb APIをセットアップする簡単な方法を提供します。ナレッジグラフは、そのデータの意味と一緒にデータを組み込みます。これにより、異なる独立した当事者がそれらを維持またはホストする場合でも、複数の知識グラフからのデータを組み合わせることができます。知識グラフは、固体ポッド、SPARQLエンドポイント、トリプルパターンフラグメントインターフェイス、RDFファイルなどを介してホストできます。コンテンツネゴシエーションを使用して、Walderは、これらの知識グラフのデータを、HTML、RDF、およびJSON-LDを介してクライアントが利用できるようにします。ユーザーは、Walderが使用するデータとこのデータの処理方法を構成ファイルで定義します。ここでウォルダーで構築されているAPIを調べてください。
目次
yarn global add walderを介して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 serverOpenAPI 3.0仕様に続いて、YAMLで構成ファイルを書き込みます。構成ファイルには、次の構造が必要です。
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キーには、Walderが使用するディレクトリへのパスが含まれています。このキーとその値はオプションです。ユーザーがパスを指定しない場合、Walderは構成ファイルのディレクトリに比べて次のデフォルト値を使用します。
root : .
views : views
pipe-modules : pipe-modules
public : public
layouts : layouts Walderが間違ったファイルを公開しないようにするために、ユーザーがpublicフィールドへのパスを提供しない場合、Walderは現在の作業ディレクトリにこのディレクトリを見つけられず、それを使用している場合、新しいディレクトリ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でサーバーが開始されます。
上記のパスエントリでは、ユーザーは、Walderがそのパスのすべてのクエリに対して使用するグローバル（オプション）識別子として定義されたoptionsを定義しました。選択できる2つのオプションがあります： 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は、GraphQL-LD-Comunicaを使用してGraphQLクエリと @comunica/Query-SPARQLを実行してSPARQLクエリを実行します。 GraphQL-LDクエリの結果はJSONデータです。ウォルダーは最初にそれをJSON-LDに変換します。これにより、コンテンツネゴシエーション中に他のRDF形式への変換が可能になります。 SPARQLクエリの結果は、一連のクワッドです。 JSON-LDフレームが指定されている場合、クワッドはJSON-LDに変換されます。コンテンツの交渉の重要性により、コンストラクトクエリのみがサポートされています。
Walderは統合を使用して、特定のテンプレートに対して対応するエンジンを自動的に取得します。これは、サポートされているテンプレートエンジンが統合に依存していることを意味します。
さまざまなルートに異なるテンプレートエンジンを使用できます。たとえば、PUGは1つのルートのHTMLをレンダリングし、ハンドルバーは別のルートのHTMLをレンダリングします。 Walderは、指定されたテンプレートのファイル拡張子を調べることでこれをすべて行います。
テンプレートは、ビューとレイアウトで使用できます。そのため、区別するためにテンプレートとレイアウトテンプレートを表示します。
ルートの構成ファイルで指定されたクエリの結果は、データとしてビューテンプレートでレンダリングするために利用できます。
dataという名前のオブジェクトが含まれています。 GraphQL-LDクエリの場合、クエリが特異化されていない限り、各オブジェクトは配列になります。 songs.handlebarsは、この構成ファイルのルート/music/{musician}の単一クエリの結果の結果の消費の例です。 songs_movies.handlebarsは、この構成ファイルのルート/artist/{artist}の2つのクエリの結果の結果の消費の例です。
SPARQLクエリの場合、JSON-LDフレームが指定されていない場合、各オブジェクトはクワッドの配列です。そうでなければ、JSON-LDオブジェクトになります。
レイアウトを使用することは、ルート固有のビューテンプレートの繰り返しを避けるための優れた方法です。複数のルートに表示されることを目的としたヘッダー、フッター、ナビゲーションバー、その他のコンテンツなどの再利用可能なHTML構造は、レイアウトファイルで指定されます。
フロントマッタースメタデータフィールドlayoutを使用して、レイアウトテンプレートファイルをビューテンプレートファイルで指定できます。構成ファイルで定義されているlayouts場所で利用可能なファイル名を含める必要があります。ファイル名の前に相対パスが含まれる場合があります。
例レイアウトを指定するテンプレートファイルを表示：
---
layout: my-layout.pug
---
// view template continues here
Walderは、ビューテンプレートファイルから生成された内部HTMLコンテンツを、レイアウトテンプレートファイルにcontentという名前のオブジェクトとして転送されたデータに配置します。
レイアウトテンプレートファイルは、さらに別のテンプレートです。通常、これらの内側のHTML内容を選択した位置に拡張します。
単純なパグの例（Mind the !{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
対応するレイアウトテンプレート（レイアウトfm.pug）そのフィールドを読み取ります（ #{a2}に心を込めて）：
doctype html
html(lang="en")
head
if a2
title #{a2}
body !{content}
構成ファイルを解析している間、Walderは入力の正確性と完全性も検証します。 Walderが構成ファイル全体を解析し、エラーを見つけたとき、Walderはすべてのエラーと出口を返します。
現時点では、ウォルダーは以下を検証しています。
200~x-walder-input-text/htmlエントリの既存のファイルのみに言及しています。 Walderは、エラーページを特定のHTTPステータスコードにバインドします。デフォルトのエラーページを定義できますが、対応するパスエントリのresponsesキーにそれらを追加することにより、パス固有のエラーページも定義できます。
404 ：ページが見つかりません500 ：内部サーバーエラー500 ：指定されたパイプモジュールを適用できませんでした404 ：予想される変数は与えられませんでした500 ：指定されたクエリを実行できませんでした次のコマンドを使用してウォルダーを実行したとき：
$ walder -c example/config-errors.yaml
次のパスはエラーにつながります。
404 （グローバル：ページは見つかりません）500 （パイプモジュール：指定されたパイプモジュールを適用できませんでした）500 （graphql-ld：指定されたクエリを実行できませんでした）次の構成ファイルの抜粋は、PATH固有のmoviesServerError.handlebarsを使用します。ハンドルバールは、 /moviesにナビゲートするときにステータスコード500につながるエラーでテンプレートを表示します。
必要なクエリパラメーターactor渡されない場合、ウォルダーはステータスコード404返します。 configファイルには、対応するステータスのパス固有のHTMLビューテンプレートがないため、Walderはデフォルトのerror404.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 Webサイトを開発している間、 config.yamlに変更を加えながらWebサイトにリロードしたいと思うでしょう。 NPMウォッチを使用してこれを簡単に実行できます。開始方法については、以下のpackage.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がすべてのconfig.yaml変更をリロードします！
| 図書館 | ライセンス |
|---|---|
| @comunica | mit |
| 受け入れます | mit |
| axios | mit |
| チャイ | mit |
| 司令官 | mit |
| 統合します | mit |
| デバッグ | mit |
| 急行 | mit |
| 前面 | mit |
| fs-extra | mit |
| graphql-ld | mit |
| graphql-ld-comunica | mit |
| ハンドルバー | mit |
| IS-HTML | mit |
| jade-to handlebars | mit |
| json-refs | mit |
| jsonld | BSD-3節 |
| jsonpath | mit |
| Markdown-It | mit |
| モカ | mit |
| モーガン | mit |
| N3 | mit |
| オブジェクトパス | mit |
| パグ | mit |
| スーパーテスト | mit |
| TMP | mit |
| ウィンストン | mit |
| Yaml | ISC |
ウォルダーを構築し、リストに追加したいですか？プルリクエストを作成してください！
このコードは、Ghent Universityによって著作権で保護されています©2019–2020 - IMECとMITライセンスの下でリリースされました。
