RESTPP请求
用户提交请求的过程从本质上说,是将一个HTTP请求发送给对应的REST++服务器的过程。默认情况下,REST++服务器的监听端口为9000。每一个请求命令都必须包含下面的三个要素:
请求方法(包括GET、POST或DELETE)
端点地址
必须的参数和可选的参数
端点地址以HTTP URL的形式表示。
参数附加在末尾,并使用标准的HTTP请求字符串格式:
在测试环境或开发环境中,提交请求的一方和收到请求的REST++服务器可能位于同一台计算机上。在这种情况下,服务器的IP地址server_ip可以写成localhost。
通常情况下,向REST++服务器提交HTTP请求的最方便方式是使用Linux的curl命令。
例:
假定REST++服务器位于本地计算机上(典型配置),且同时TigerGraph数据库中有一个叫做socialNEet的图。则如果用户试图获得socialNet图上的所有 User 点,则命令将写为:
如果只想获得前三个点,则可以将limit参数设定为3:
HTTP请求中的三个方法关键字————即GET、POST和DELETE三个字段是大小写敏感的。同时,curl命令的选项标记(option flag)也是大小写敏感的。
POST方法的数据输入
在POST请求中,输入的数据必须为JSON格式。输入数据的方法有两种,即命令行嵌入式或文件导入式。
命令行嵌入式
数据必须处理为一条单行字符串,不能有分行符。在curl命令中添加- d参数,然后加上对应的JSON字符串。
下面的例子中,我们使用POST /graph端点,向socialNet图中插入一个id为 “id6” 的点类为User的点。
文件导入式
通常,使用单独的文件导入数据会更加方便,特别是当数据量比较大的时候。
可以在curl命令中添加 --data-binary @path_to_file 参数来引用数据文件,
如果把前面的例子中的源数据改为由文件导入(假设文件名为:my_input.json),则对应的命令行变为:
REST++的输出
在TigerGraph中,所有的REST输出都是JSON格式的。在本指导的“内建端点”部分可以找到所有内建端点的格式详述。默认情况下,输出的结果是机器阅读格式,即不会有多余的空格和回车。输出的JSON对象有三个字段:错误(error)、消息(message)和结果(result)。
本文档中所有的JSON格式均以v2版本的API为基础。对于早期使用v1版本API的TigerGraph来说,其输出的结果可能和v2版本的输出略有差异。在新版的TigerGraph系统中,用户可自行选择v1或v2版本的格式输出。
为了使得输出的结果更加便于阅读,用户可以使用jq command或Python的内建json库来对输出结果调整格式。绝大多数的Linux安装包中都默认安装了这些组件。
例:
在文档GSQL Demo Examples 文档中的Collaborative Filter案例中,包含了如下请求:
如果输出结果没有被处理过,它是这样的:
如果我们对结果进行格式修改:
则输出的内容便更易于阅读了:
REST++的安全验证
TigerGraph管理员可以选择是否在REST++端点上开启用户验证。如果用户验证处于关闭状态,则TigerGraph的REST++端点是公开的,任何可以访问该服务器HTTP端口的用户都能够调用该REST++端点。然而,当用户验证开启后,要调用REST++端点则必须在HTTP头中添加有效的用户身份令牌。请参阅文档用户权限及验证查看开启/关闭用户验证的具体步骤。
TigerGraph的REST++服务使用OAuth 2.0验证规范:每个用户需要创建一条或多条密文(即secret,格式为一个伪随机字符串)。每条密文对应某个特定用户在特定图上的特定权限。任何人只要拥有该密文,即可以在特定的REST端点上生成一个用于验证身份的令牌(即token,同样也是一个伪随机字符串)。令牌用于通过REST端点执行TigerGraph数据库操作。每个令牌都会在一定时间后失效。默认情况下,令牌的有效期为一个月。
通过GET /requesttoken获得一个令牌
用户在获取令牌前必须首先拥有密文。可以在文档用户权限及验证中找到从GSQL中获取密文的方法。端点GET /requesttoken专门用于生成令牌。该端点需要两个输入参数:
secret (必须): 即用户的密文
lifetime (可选): 令牌的有效时间(单位为秒)。默认有效期为一个月,约合2600万秒。
使用令牌
当REST++端点上的用户验证功能打开时,我们必须在每一个HTTP请求的头部都包含有效的令牌。如果我们使用的是curl命令提交REST++请求,则语法格式如下:
例:假设令牌为 “01234567abcdefgh01234567abcdefgh”,则Collaborative Filtering案例中的请求应写成如下样式:
大小限制
一条URL请求的最长长度限制为8K字节(包含查询字符串)。如果字符串中内嵌的数据过长,建议使用文件导入法输入数据。
请求主体(包括内嵌的数据)的最大长度取决于系统参数nginx.client_max_body_size的值。该值默认值为128(单位MB)。下面的命令可以提高该限制值:
该参数的上限为1024MB。提高该参数的值会降低内存的可用空间,这可能会影响其他组件的运行。所以,在改动该参数时请务必谨慎。
Last updated