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

金数据的应用程序编程接口（API）操作指南
金数据API为具备编程能力的用户提供了极强的扩展功能。

开发者可以通过表单API获取表单定义、通过数据API追加数据或通过数据推送API将新提交的数据推送到自己的平台。

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

API访问规则
●所有的数据格式为JSON
●所有的数据传输编码为UTF-8
●目前，API访问的地址来源为https:///api/v1/
●除了数据推送API外，所有的API都需要恰当的API访问权限。

目前我们仅
支持HTTP Basic验证的方式。

●目前提供的API
数据推送API
开启数据推送API的表单收到新数据时，金数据会将该数据通过HTTP POST推送到指定的URL。

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

填写地址并保存后，金数据会在表单收到新数据后向指定的地址以JSON格式POST该数据。

数据推送示例
例如指定URL为/jinshuju/callback，则金数据以JSON格式POST该数据的Entry信息。

发送的JSON数据以字段的key来展示，字段对照表将列出Key与Label的对应关系。

POST /jinshuju/callback
Content-Type: application/json
X-Requested-By: jinshuju
{
"form": "xJfeTv",
"entry": {
"field1": 123,
"field2": "Hello, World",
"field3": "It's very good."
}
}
注意事项
•对方服务器需在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 https:///api/v1/forms/ex27t2
请注意，以下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 https:///api/v1/forms/1F34Qv
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数据给调用者。