RESTPP请求

用户提交请求的过程从本质上说,是将一个HTTP请求发送给对应的REST++服务器的过程。默认情况下,REST++服务器的监听端口为9000。每一个请求命令都必须包含下面的三个要素:

  1. 请求方法(包括GET、POST或DELETE)

  2. 端点地址

  3. 必须的参数和可选的参数

端点地址以HTTP URL的形式表示。

参数附加在末尾,并使用标准的HTTP请求字符串格式:

通常情况下,向REST++服务器提交HTTP请求的最方便方式是使用Linux的curl命令。

例:

假定REST++服务器位于本地计算机上(典型配置),且同时TigerGraph数据库中有一个叫做socialNEet的图。则如果用户试图获得socialNet图上的所有 User 点,则命令将写为:

如果只想获得前三个点,则可以将limit参数设定为3:

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)。

例:

在文档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。提高该参数的值会降低内存的可用空间,这可能会影响其他组件的运行。所以,在改动该参数时请务必谨慎。