GraphQL接口

功能简介

GraphQL接口可以帮助客户查看并获取指定数据源中的数据, 无需登录神箭手后台.

接口说明

GraphQL接口通过发送HTTP请求给神箭手实现:

HTTP请求方式: GET

HTTP请求url: https://graphql.shenjian.io/?user_key=用户key&timestamp=秒级时间戳&sign=签名&source_id=数据源ID&query=查询请求

请求参数说明

参数 是否必填 说明
user_key 用户key(您可以在神箭手用户中心查看您的user_key)
timestamp 当前时间戳(1970年01月01日起至现在的总秒数, 精确到秒)
sign 签名(用户key, 秒级时间戳, 用户密钥三个值顺序连接后用MD5加密得到的32位字符串, 大小写均可)
source_id 数据源ID(可在每个数据源的”数据”页查看)
query 查询请求(下面会介绍query语法)

query语法说明

query参数是一个字符串, 需要utf8 Urlencode.

query语法参考示例:

  • 示例1

查询某数据源的所有数据, 点此查看请求频次说明.

source{}

source{data{}}
  • 示例2

查询某数据源的10条数据.

source(limit:10){}

source(limit:10){data{}}
  • 示例3

查询某数据源name值为”sjs”的10条数据.

source(limit:10,name:{eq:"sjs"}){}

source(limit:10,name:{eq:"sjs"}){data{}}
  • 示例4

查询某数据源name值为”sjs”, 且__id值小于等于100的10条数据.

source(limit:10,name:{eq:"sjs"},__id:{lte:100}){}

source(limit:10,name:{eq:"sjs"},__id:{lte:100}){data{}}
  • 示例5

__id正序查询某数据源name值为”sjs”, 且__id值小于等于100的10条数据.

source(limit:10,name:{eq:"sjs"},__id:{lte:100},sort:"asc"){}

source(limit:10,name:{eq:"sjs"},__id:{lte:100},sort:"asc"){data{}}
  • 示例6

__id正序查询某数据源name值为”sjs”, 且__id值小于等于100的10条数据, 返回字段包括__idname.

source(limit:10,name:{eq:"sjs"},__id:{lte:100},sort:"asc"){
data{
__id,
name
}
}

query语法说明:

参数 是否必需 说明
source 查询请求的必备参数
字段名 可以给字段设置筛选条件, 包括”gt”, “lt”, “eq”, “in”等,
多个筛选条件要用逗号分隔,
如果数据源是爬虫的爬取结果, 则必然包含__id, __time__url三个字段; 其他数据源则不包含
gt 字段筛选条件,
查询大于指定字段值的数据, 数据类型与字段值保持一致,
例如: 查询__id大于10的数据, __id:{gt:10}
lt 字段筛选条件,
查询小于指定字段值的数据, 数据类型与字段值保持一致,
例如: 查询__id小于100的数据, __id:{lt:100}
eq 字段筛选条件,
查询等于指定值的数据, 数据类型与字段值保持一致,
例如: 查询name等于”sjs”的数据, name:{eq:"sjs"}
gte 字段筛选条件,
查询大于等于指定字段值的数据, 数据类型与字段值保持一致,
例如: 查询__id大于等于10的数据, __id:{gte:10}
lte 字段筛选条件,
查询小于等于指定字段值的数据, 数据类型与字段值保持一致,
例如: 查询__id小于等于100的数据, __id:{lte:100}
ne 字段筛选条件,
查询不等于指定值的数据, 数据类型与字段值保持一致,
例如: 查询name不等于”sjs”的数据, name:{ne:"sjs"}
in 字段筛选条件,
查询等于指定数组元素值的数据, 数组类型,
数组元素的数据类型与字段值保持一致,
例如: 查询__id为20和25的数据, __id:{in:[20,25]}
limit 单次请求查询的最大条数, 整型, 默认值20,
不同神箭手套餐, 可查询的最大条数不同,
例如: 设置单次最多请求50条数据, limit:50
sort __id顺序查询数据, String类型, 值为”desc”或”asc”,
默认值是”desc”, 表示按__id倒序查询数据,
如果数据源没有__id字段, 则不会对查询数据进行排序,
例如: 按__id正序查询数据, sort:"asc"
data 可自定义查询指定数据源所包含的字段
count 查询数据源的总数据条数,
由于该操作非常耗时, 如无必要建议不要查询
page_info 查询has_next_pageend_cursor的必备参数
has_next_page 查询是否包含下一页数据
end_cursor 查询本次请求返回最后一条数据的__id

注意: __id__time的字段值都是整型, 其余字段的值都是String类型.

返回参数说明

参数 说明
code 返回码
result 返回内容(请求成功时会出现)
error_info 错误信息(请求失败时会出现)

返回码对照表

返回码 详情
0 成功
101 无效的user_key
102 无效的sign
103 数据源不存在
104 请求频率超过限制
106 请求已过期(timestamp落后服务器时间超过5分钟)
500 (具体错误原因请在返回的”error_info”字段中查看)

请求频次说明

套餐等级 单次请求最大查询条数 每次请求间隔时间
个人免费版 20条 5s
个人专业版 50条 1s
个人旗舰版 200条 0.5s
企业标准版 2000条 0.1s
企业高级版 5000条 0.05s
企业定制版 不限条数 0.01s

接口调用成功示例

{
"code": 0,
"result": {
"count": 2523,
"data": [
{"__id":105,"__time":1493003149,"name":"脚钛"},
{"__id":106,"__time":1493003149,"name":"腕表"},
{"__id":107,"__time":1493003148,"name":"春鞋"}
],
"page_info": {
"has_next_page": true,
"end_cursor": 107
}
}
}

接口调用失败示例

注意: 接口调用失败后, 会返回详细的错误信息

{
"error_info": {
"message": "Cannot query field \"age\" on type \"data\".",
"locations": [{"line":1,"column":63}]
},
"code": 500
}

PHP调用GraphQL的例子

<?php

// 可在神箭手"用户中心"查看
$user_key = '用户Key';
// 可在神箭手"用户中心"查看
$user_secret = '用户密钥';
// 可在每个数据源的"数据"页查看
$source_id = <数据源ID>;
$timestamp = time();
$sign = md5($user_key . $timestamp . $user_secret);
$gt = 0;
// 该"query"语句会返回数据的所有字段,
// 如果需要返回部分字段请参看上文中的"query语法说明"
$query = "source(__id: {gt: {$gt}}, limit: 5, sort: \"asc\")".
"{data{}, page_info{has_next_page, end_cursor}}";

$url = "https://graphql.shenjian.io/?".
"user_key={$user_key}&timestamp={$timestamp}&sign={$sign}".
"&source_id={$source_id}&query=" . urlencode($query);

$content = file_get_contents($url);
$result = json_decode($content, true);
if($result['code'] == 0) {// 正确返回
$data = $result['result']['data'];
foreach($data as $item) {
echo "item id: " . $item['__id'] . "\n";
}
} else {
echo "error code: " . $result['code'] . "\n";
echo "error reason: " . $result['error_info'] . "\n";
}