RESTPP请求

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

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

  2. 端点地址

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

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

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

在测试环境或开发环境中,提交请求的一方和收到请求的REST++服务器可能位于同一台计算机上。在这种情况下,服务器的IP地址server_ip可以写成localhost

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

REST请求格式
curl -X method "http://server_ip:9000/path_to_endpoint?request_parameters"

例:

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

例: 获得所有用户点
curl -X GET "http://localhost:9000/graph/socialNet/vertices/User"

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

例: 获得三个用户点
curl -X GET "http://localhost:9000/graph/socialNet/vertices/User?limit=3"

HTTP请求中的三个方法关键字————即GET、POST和DELETE三个字段是大小写敏感的。同时,curl命令的选项标记(option flag)也是大小写敏感的。

POST方法的数据输入

在POST请求中,输入的数据必须为JSON格式。输入数据的方法有两种,即命令行嵌入式或文件导入式。

命令行嵌入式

数据必须处理为一条单行字符串,不能有分行符。在curl命令中添加- d参数,然后加上对应的JSON字符串。

POST请求中嵌入源数据的语法格式
curl -X POST -d 'json_string' "http://server_ip:9000/path_to_endpoint?request_parameters"

下面的例子中,我们使用POST /graph端点,向socialNet图中插入一个id为 “id6” 的点类为User的点。

例:使用嵌入式方法输入数据
curl -X POST -d '{"vertices":{"User":{"id6":{"id":{"value":"id6"}}}}}' "http://localhost:9000/graph/socialNet"

文件导入式

通常,使用单独的文件导入数据会更加方便,特别是当数据量比较大的时候。

可以在curl命令中添加 --data-binary @path_to_file 参数来引用数据文件,

例:POST请求中通过文件导入数据的语法
curl -X POST --data-binary @json_file "http://server_ip:9000/path_to_endpoint?request_parameters"

如果把前面的例子中的源数据改为由文件导入(假设文件名为:my_input.json),则对应的命令行变为:

例:使用文件导入数据
curl -X POST --data-binary @my_input.json "http://localhost:9000/graph/socialNet"

REST++的输出

在TigerGraph中,所有的REST输出都是JSON格式的。在本指导的“内建端点”部分可以找到所有内建端点的格式详述。默认情况下,输出的结果是机器阅读格式,即不会有多余的空格和回车。输出的JSON对象有三个字段:错误(error)、消息(message)和结果(result)。

本文档中所有的JSON格式均以v2版本的API为基础。对于早期使用v1版本API的TigerGraph来说,其输出的结果可能和v2版本的输出略有差异。在新版的TigerGraph系统中,用户可自行选择v1或v2版本的格式输出。

为了使得输出的结果更加便于阅读,用户可以使用jq command或Python的内建json库来对输出结果调整格式。绝大多数的Linux安装包中都默认安装了这些组件。

curl -X method "http://server_ip:9000/path_to_endpoint?request_parameters" | jq .
curl -X method "http://server_ip:9000/path_to_endpoint?request_parameters" | python -m json.tool

例:

在文档GSQL Demo Examples 文档中的Collaborative Filter案例中,包含了如下请求:

curl -X GET "http://localhost:9000/graph/socialNet/vertices/User?limit=3"

如果输出结果没有被处理过,它是这样的:

{"version":{"api":"v2","schema":0},"error":false,"message":"","results":[{"v_id":"id2","v_type":"User","attributes":{}},{"v_id":"id5","v_type":"User","attributes":{}},{"v_id":"id3","v_type":"User","attributes":{}}]}

如果我们对结果进行格式修改:

curl -X GET http://localhost:9000/graph/socialNet/vertices/User?limit=3 | jq .

则输出的内容便更易于阅读了:

{
  "version": {
    "api": "v2",
    "schema": 0
  },
  "error": false,
  "message": "",
  "results": [
    {
      "v_id": "id2",
      "v_type": "User",
      "attributes": {}
    },
    {
      "v_id": "id5",
      "v_type": "User",
      "attributes": {}
    },
    {
      "v_id": "id3",
      "v_type": "User",
      "attributes": {}
    }
  ]
}

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++请求获得令牌"
curl -X GET 'localhost:9000/requesttoken?secret=jiokmfqqfu2f95qs6ug85o89rpkneib3&lifetime=1000000'

使用令牌

当REST++端点上的用户验证功能打开时,我们必须在每一个HTTP请求的头部都包含有效的令牌。如果我们使用的是curl命令提交REST++请求,则语法格式如下:

通过curl提交包含用户验证信息的请求
curl -X GET -H "Authorization: Bearer <token>" '<request_URL>'

例:假设令牌为 “01234567abcdefgh01234567abcdefgh”,则Collaborative Filtering案例中的请求应写成如下样式:

curl -X GET -H "Authorization: Bearer 01234567abcdefgh01234567abcdefgh" "http://localhost:9000/graph/socialNet/vertices/User?limit=3"

大小限制

一条URL请求的最长长度限制为8K字节(包含查询字符串)。如果字符串中内嵌的数据过长,建议使用文件导入法输入数据。

请求主体(包括内嵌的数据)的最大长度取决于系统参数nginx.client_max_body_size的值。该值默认值为128(单位MB)。下面的命令可以提高该限制值:

gadmin --set nginx.client_max_body_size xxx -f

该参数的上限为1024MB。提高该参数的值会降低内存的可用空间,这可能会影响其他组件的运行。所以,在改动该参数时请务必谨慎。

Last updated