金数据的应用程序编程接口(API)操作指南.docx

金数据的应用程序编程接口（API）操作指南
金数据API为具备编程能力的用户提供了极强的扩展功能。
开发者可以通过表单API获取表单定义、通过数据API追加数据或通过数据推送API将新提交的数据推送到自己的平台。

您可以在 个人中心 —— API 来开启您的API支持及获取API Key/Secret。

API访问规则

l 所有的数据格式为JSON
l 所有的数据传输编码为UTF-8
l 目前，API访问的地址来源为
l 除了数据推送API外，所有的API都需要恰当的API访问权限。目前我们仅支持HTTP Basic验证的方式。
l 目前提供的API

数据推送API
开启数据推送API的表单收到新数据时，金数据会将该数据通过HTTP POST推送到指定的URL。
数据推送API详解：
开启数据推送
如果您想将某个表单新提交的数据推送到指定URL，您可以在表单的 设置 —— 数据提交 页面的底部找到将 数据以JSON格式发送给第三方，勾选开启后您将看到当前表单的字段对照表。

填写地址并保存后，金数据会在表单收到新数据后向指定的地址以JSON格式POST该数据。
数据推送示例
例如指定URL为
发送的JSON数据以字段的key来展示，字段对照表将列出Key与Label的对应关系。
POST
Content-Type: application/json
X-Requested-By: jinshuju
{
"form": "xJfeTv",
"entry": {
"field1": 123,
"field2": "Hello, World",
"field3": "It's very good."
}
}
字段的对应格式
金数据字段
JSON
样例
单行文字，多行文字，邮箱，电话
string
"你好，世界"
数字
number
123.4
单选，下拉框，图片单选
string
"男"
多选，图片多选
Array
["篮球","足球"]
地址
Object
{"province":"陕西", "city":"西安", "address":"锦业一路软件园"}
日期
string
"2012-04-16"
评分
integer
14

注意事项
• 对方服务器需在2秒内返回200作为应答，2秒后金数据将中断连接。
• 如果出错，金数据会最多重试三次。
如果连续出错超过10次，该表单的数据推送过程将停止，表单创建者将获得邮件通知。开发者需要在数据推送设置中手工启动，只有成功，数据推送才会继续。

表单API
您可以通过该API获取表单定义，然后你可以在任意你熟知的平台上重绘这个表单。通过结合数据API，您可以脱离金数据界面绘制和添加数据。

表单API用于获取表单定义，目前支持的字段有：
• 单选框 single_choice
• 复选框 multiple_choice
• 下拉框 drop_down
• 日期 date
• Email email
• 数字 number
• 电话 phone
• 多行文本 paragraph_text
• 单行文本 single_line_text
上传文件、商品字段等暂时未支持。
使用方法
首先确保您有访问API的能力。获得API Key&Secret后，即可获取表单的JSON定义。
例如，通过curl来访问：
curl -u api_key:api_secret
请注意，以下JSON内容中，选项类的部分在数据库中以name和value两部分组成。
您获得的JSON表单定义类似如下：
{
"name": "意见反馈",
"description": "<p>当您希望从顾客那里获得反馈时，可以使用该表单收集</p>",
"fields": [
{
"field_9": {
"label": "您对我们的服务满意么？",
"type": "single_choice",
"notes": "",
"private": false,
"validation": {},
"choices": [
{
"name": "非常满意",
"value": "zyRl"
},
{
"name": "满意",
"value": "8Q6B"
},
{
"name": "一般",
"value": "hPWR"
},
{
"name": "不满意",
"value": "s8PE"
},
{
"name": "非常不满意",
"value": "fLdR"
}
],
"allow_other": false
}
},
{
"field_10": {
"label": "您最喜欢的部分是",
"type": "multiple_choice",
"notes": "",
"private": false,
"validation": {},
"choices": [
{
"name": "服务1",
"value": "CIoI"
},
{
"name": "服务2",
"value": "A8li"
},
{
"name": "服务3",
"value": "MIWn"
}
],
"allow_other": false
}
},
{
"field_11": {
"label": "您希望给我们提出的建议是？",
"type": "paragraph_text",
"notes": "",
"private": false,
"validation": {}
}
},
{
"field_8": {
"label": "希望获得联系",
"type": "single_line_text",
"notes": "如果您希望我们联系您，可以留下您的微博、邮箱或者QQ号",
"private": false,
"validation": {}
}
}
]
}

数据API
您可以通过这个API添加数据。您能够将所有的数据通过JSON格式以HTTP POST的方式发送到对应的表单。

数据API用于对表单数据进行维护。
目前，数据API仅支持增加数据，不支持修改、删除以及获取数据。想要获取数据，可以使用数据推送API。
注意：目前每个API Key只允许100次/每小时的请求频率。如果希望提升这个请求频率，请与我们联系： marketing@
使用方法
首先确保您有访问API的能力。获得API Key&Secret后，即可通过API提交数据。
POST
Accept: application/json
Content-Type: application/json
数据提交请求应该是一个满足表单定义的JSON格式。
需要注意的是，从2015年3月25日起，金数据的单、多选，图片单、多选，下拉框，两级下拉框以及矩阵单选，其选项有name与value两个部分组成，我们建议您在构建JSON数据时，以value提交，一个例子如下：
{
"field_9": "hPWR",
"field_10": "CIoI"
}
如果不满足校验条件（必填/重复等），金数据会返回400，并给出提示如下：
{
"error": "bad_request",
"error_description": "{\"field_9\":[\"您对我们的服务满意么？ 必须填\"],\"field_10\":[\"您最喜欢的部分是 必须填\"]}"
}
如果信息正确，系统会返回201作为响应，并返回整个创建成功的JSON数据给调用者。