中文描述:GRLC,the GIT repository linked data API constructor
grlc的Python项目详细描述
grlc,gitrepositorylInked Data APIconstructor使用存储在Git存储库中的SPARQL查询自动构建Web API。http://grlc.io/
撰稿人:albert mero,rinke hoekstra,carlos martinez
版权所有:阿姆斯特丹大学阿尔伯特·梅罗尼奥
许可证:麻省理工学院许可证(请参见license.txt)
什么是GRLC?
grlc是一个轻量级服务器,它接受在github存储库中管理的sparql查询,并将它们转换为链接的数据web api。这允许对链接数据进行通用访问。用户不需要知道SPARQL来查询数据,而是可以访问Web API。
快速教程
有关快速使用教程,请查看我们的wiki演练此处
功能
- 请求参数映射到sparql:grlc符合关于如何将get/post请求参数映射到sparql的basil惯例
- 通过sparql三模式查询,在swagger ui的下拉菜单中自动、用户可自定义地填充参数值
- 现在也可以在查询修饰符中指定作为枚举的参数值(即将填充ui下拉列表的封闭值列表),以保存端点请求(请参见本例中的)
- 参数默认值现在也可以通过decorators来表示(请参见本例)
- 基于URL的内容协商:可以通过将特定内容类型附加到操作请求URL来请求,例如http://localhost:8088/cedar project/querys/residestatus_all.csv" rel="nofollow">http://localhost:8088/cedar project/querys/residestatus_all.csvl以csv格式请求结果
- API结果分页,按照
分页
decorator和Github的API分页遍历 - Docker Hub中的Docker映像便于部署
- 与链接数据片段的兼容性服务器、rdf转储和html+rdfa文件
- [新]GRLC I现在集成sparqltransfer,允许在json中使用查询(请参见本例中的sparqltransfer)。
- 在回购历史记录(通过git2prov和grlc的活动添加)和grlc的活动添加中,在prov中生成出处。
- 基于提交的api版本控制与带有git散列的repo版本控制一致
- sparql端点地址可以在查询级别、存储库级别设置,现在也可以作为查询参数设置。这使您的api端点不可知,并支持通用和可转置查询!
- 构造查询现在自动映射为获取请求、接受where子句中的参数并返回
中的内容。text/turtle
或application/ld+json
- 插入数据查询现在自动映射到post请求。支持仅限于不带where子句的查询,参数通常是
g
(插入数据的命名图)和data
(插入三元组,格式为ntriples
)的值。insert查询模式到目前为止是静态的,如static.py中所定义。仅限技术人员测试。
安装并运行
通过docker运行是部署grlc的最简单和首选形式。您需要一个正在工作的docker和docker compose的安装程序。要部署GRLC,只需从Docker Hub中提取最新的映像,并使用适合您需要的aDocker compose.yml
运行Docker compose(根目录中提供了a示例):
git clone https://github.com/CLARIAH/grlc cd grlc docker pull clariah/grlc docker-compose -f docker-compose.default.yml up
要直接从Docker Hub运行,只需执行以下操作即可:
docker run --rm -p 8088:80 -e GRLC_SERVER_NAME=grlc.io -e GRLC_GITHUB_ACCESS_TOKEN=xxx -e GRLC_SPARQL_ENDPOINT=http://dbpedia.org/sparql -e DEBUG=true clariah/grlc
(如果只复制文件系统中的某个文件,则可以省略前两个命令)
如果您使用提供的docker compose.default.yml
您的GRLC实例将在http://localhost:8001
如果希望GRLC实例将查询转发到不同于grlc.io
的服务,请编辑docker compose.yml
或docker compose.default.yml
文件中的grlc\u服务器名
变量。
为了让grlc与github通信,您需要告诉grlc您的访问令牌是什么:
- 获取github个人访问令牌。在GitHub的配置文件页面中,转到设置,然后转到开发人员设置,个人访问令牌,并生成新令牌
- 您将获得一个访问令牌字符串,复制它并将其保存在安全的地方(github不会让您再次看到它!)
- 编辑
docker compose.yml
或docker compose.default.yml
文件,并将此标记粘贴为环境变量grlc_github_access_标记的值
如果您想在系统引导时作为服务运行grlc,可以在upstart/
替代安装方法
通过这些你会错过一些很酷的Docker捆绑功能(比如基于nginx的缓存)。我们提供这些替代方案只是为了测试、开发场景或Docker兼容性的原因。
先决条件
- 蟒蛇3
- 开发文件:
sudo apt-get install libevent-dev python-all-dev
PIP
如果要将grlc用作库,可以通过pip
安装grlc>
pip install grlc grlc-server
有关更多详细信息,请访问grlc的pypi页面(感谢c-martinez!)
烧瓶应用
您可以按如下方式本机运行grlc:
gunicorn -c gunicorn_config.py src.server:app
注意:由于gunicorn
在Windows下不起作用,您可以使用服务生来代替:
waitress-serve --port=8088 src.server:app
您也可以在这里找到一个示例
用法
grlc假设有一个github存储库(对通用git repos的支持正在进行中),您可以在其中将sparql查询存储为.rq文件(例如在本例中)。grlc将为这样一个sparql查询/.rq文件创建一个api操作。
如果您看到了这一点,那么您的grlc实例已经启动并运行,可以构建api了。假设您在http://localhost:8088/" rel="nofollow">http://localhost:8088/运行它,并且您的查询位于https://github.com/cedar-project/queries" rel="nofollow">https://github.com/cedar project/queries,只需将浏览器指向以下位置:
- 要请求api的夸张规范,请使用http://localhost:8088/api/username/repo/spec" rel="nofollow">http://localhost:8088/api/username/repo/spec,例如http://localhost:8088/api/cedar project/querys/spec" rel="nofollow">http://localhost:8088/api/cedar project/querys/spec或http://localhost:8088/api/clariah/wp4 querys/spec
- 要请求api swagger ui风格的api文档,请访问http://localhost:8088/api/username/repo/api docs" rel="nofollow">http://localhost:8088/api/username/repo/api docs,例如http://localhost:8088/api/cedar project/querys/api docs" rel="nofollow">http://localhost:8088/api/cedar project/querys/api docs或http://localhost:8088/api/clariah/wp4 querys/api docs
默认情况下,grlc会将查询定向到dbpedia sparql端点。要更改此设置:
- 向请求中添加一个
端点
参数:'http://grlc.io/user/repo/query?endpoint=http://sparql endpoint/'。如果不想在api的swagger ui中看到
中添加一个endpoint
参数,可以在url:falseendpoint\u装饰符。
- 在查询文本的第一个注释块中添加一个
+endpoint:
decorator(首选,请参见下文) - 在包含查询的github存储库中的
endpoint.txt
文件中的一行上添加端点的url。 - 或者您可以直接修改grlc源代码(但如果查询是自包含的,就更好了)
就这样!
示例API
看看这些:
- http://grlc.io/api/clariah/wp4查询hisco/
- http://grlc.io/api/albertmeronyo/lodapi/
- http://grlc.io/api/albertmeronyo/lsq-api
您可以在github
装饰符语法
有两个sparql注释嵌入的装饰器可以使您的招摇过市的ui看起来更好(请注意,所有注释都以\++
开头,并且限制了':'
的使用d列出表示,不能在摘要文本中使用:
- 要指定特定于查询的终结点,
+终结点:http://example.com/sparql
- 要指示http请求方法,
+method:get
- 要对结果进行分页,例如一组100个,
+分页:100
- 要创建查询/操作摘要,
+摘要:这是我的查询/操作摘要
- 要为查询/操作分配标记,
#+ tags: #+ - firstTag #+ - secondTag
- 要指示查询/操作的哪些参数应使用sparql端点的值获取枚举(并在swagger ui中获取下拉菜单),
#+ enumerate: #+ - var1 #+ - var2
- 这些参数也可以硬编码到查询装饰器中,以保存端点请求并加快api的生成:
#+ enumerate: #+ - var1: #+ - value1 #+ - value2
注意,这些应该是没有sparql/basil约定的纯变量名(所以应该用var1而不是code>?_变量IRI)
有关示例,请参见https://github.com/albertmeronyo/lodapi" rel="nofollow">https://github.com/albertmeronyo/lodapi
使用此GitHub搜索以查看来自GRLC其他用户的示例。
贡献!
grlc需要您继续将语义web内容带给开发人员、应用程序和用户。无论您是一个好奇的用户、开发人员还是研究人员,您都可以通过多种方式做出贡献:
- 错误报告中的文件
- 请求新功能
- 设置自己的环境并开始黑客攻击
查看我们的贡献指南,了解更多信息,立即加入我们!
如果你不能编码,那没问题!您仍然可以贡献很多:
- 在twitter中分享使用grlc的经验(提到处理程序@grlcldapi)
- 如果您擅长HTML/CSS,请通知我们
相关工具
- sparql2git是一个用于编辑sparql查询并将其保存在github中作为grlc api的Web界面。
- grlcr是r的一个包,通过grlc将链接的数据轻松地带入r环境。
- hay的工具将grlc列为与wikimedia相关的工具:-)
这就是GRLC用户所说的
- 用GRLC给链接的数据调味,作者:Carlos Martinez
- Egon Willighagen的博客
学术出版物
- 阿尔伯特·梅罗涅·佩涅拉,林克·霍克斯特拉。"grlc使github尝起来像链接数据api"。语义网-ESWC 2016卫星事件,Heraklion,克里特岛,希腊,2016年5月29日至6月2日,修订了部分论文。LNCS 9989,第342-353页(2016年)。(pdf)
- 阿尔伯特·梅罗涅·佩涅拉,林克·霍克斯特拉。"sparql2git:透明sparql和通过git的链接数据api管理"。在:第14届扩展语义网络会议(ESWC 2017)会议记录,海报和演示曲目。斯洛文尼亚,波托罗兹,2017年5月28日至6月1日(2017年)。(pdf)
- 阿尔伯特·梅罗涅·佩涅拉,林克·霍克斯特拉。"用于对链接数据进行例行访问的以查询为中心的自动API"。在:语义网–ISWC 2017,第16届国际语义网络会议。《计算机科学讲义》,第10587卷,第334-339页(2017年)。(pdf)