Baidu轻应用AppBuilder平台模板开发者技术参考.docx

轻应用App Builder平台模板开发者技术参考1.概述App Builder是通过百度云能力优化各行业之间的资源配置并助力落地商户快速创建轻应用的服务平台。开发者可以利用App Builder方便地将自己拥有的资源以WebApp的形式发布为轻应用，并以百度轻应用渠道接入与推广出去。一方面，App Builder实现了对数据的加工、存储，以及对优质数据搜索引擎对接；另一方面，App Builder通过提供组件化的输出支持，及最领先的云能力支持，为用户提供与native app相同的使用体验。1.1模板App Builder以模板概念对开发者进行技术支持，联接技术型开发者与应用创建者。模板是运行在BAE上的一套代码，提供包括应用数据的后台管理与前台展示的功能。一方面，技术型开发者可以开发出自己的模板并提交到App Builder平台中，另一方面，应用创建者可以将手中的资源接入到模板中，生成轻应用。一个模板可以根据需求定制生成出多个轻应用。模板提供的功能有：l 应用创建与初始化模板帮助应用创建者完成创建与初始化轻应用，如选择应用基本样式、填充默认数据，并将应用发布到轻应用接入系统中l 应用内容管理应用发布后，模板提供管理与维护应用的功能，包括更新应用内容、修改应用配置等l 应用访问界面当应用上线后并被搜索及访问时，模板提供应用的展示与交互界面更多关于模板的详细技术细节请参考第二章节内容。1.2API 与 SDKApp Builder对应用数据的组织形式有着了规范化要求，以便于搜索接入及组件化输出。应用数据在App Builder中以key-value形式存在，App Builder提供了完整的API供模板控制应用数据，包括：l 数据访问包括应用数据的存取与遍历、查找等。通过对应用数据结构的设计，模板可以利用key-value形式存储任意数据，并利用API的不同数据访问接口实现整个应用的数据逻辑l 写入检索信息在应用数据更新成功后，模板通过调用对应API即可将检索信息同步到搜索引擎中。API为不同的应用类型提供了丰富的搜索引擎个性化展示方案，供模板开发者选择l 控制应用状态为了便于模板开发者维持线上数据的稳定性，App Builder提供了数据预览机制，将数据区分为线下与线上环境。模板可以为应用创建者提供交互功能，使用户可以在数据维护完成后，通过调用API提供的发布接口主动将线下环境的预览数据同步到线上，同时同步检索信息到搜索引擎中l 后端推送数据如果模板面向的应用创建者是拥有后端开发能力的开发者，模板可以为开发者提供后端调用接口，API将为模板后端接口提供接入支持。开发者创建应用后，可以根据当前应用信息以Oauth2.0授权方式调用API，API将请求转发给模板，实现后端数据更新等机制。为了便于模板开发者使用API，我们提供了常用编程语言的SDK封装，包括php、js等。模板开发者只需下载或引用SDK代码后，即可使用SDK提供的编程接口方便地访问API。关于API与SDK的详细信息请参考第三章节内容。2.模板接入App Builder提供了一种基于token的请求鉴权机制，以实现应用数据的隔离及请求的有效性检查。当应用创建者创建或管理应用时，App Builder将向用户展示模板的创建或管理页面，并在页面地址中附加token参数。页面后端代码可以利用该参数构造请求访问API，得到应用数据（SDK已实现了访问API时token参数的传递功能）。当用户浏览到已上线的应用时，手机浏览器的请求将由App Builder转发给模板，并附加上token参数。token是一个特殊加密的字符串，包含应用信息、请求信息等。应用创建者通过App Builder平台查看自己的应用的创建或管理页面时，App Builder将生成有效期为1000天的admin token，模板可以利用该token读写线下预览数据，并控制应用数据的发布；用户浏览应用时，App Builder后端将生成有效期为120秒的guest token，模板可以利用该token读写线上数据。2.1模板的开发与调试模板可以用任意BAE支持的语言进行开发（目前BAE支持php、java、python、nodejs等语言）。为了方便模板开发者的编程与调试，App Builder的数据API支持调试模式，开发者可以在本地开发模板代码，并以test token 利用假的appid生成的admin token，可以用来测试除应用状态控制外的任意功能 (点此获取)进行测试，利用test token生成的应用数据存储在用户的个人云存储(PCS)中，数据key以appid为命名空间。开发者登录并获取test token后，在调试本地代码时需要将token参数写在url中。例如：token为ZeZPX4vVAS40bK79TV25rOhfb4G6KV1DolsSek0rO-JriTfv，页面地址为：http:/localhost:8080/index.php，则完整的调试地址为：http:/localhost:8080/index.php?token=ZeZPX4vVAS40bK79TV25rOhfb4G6KV1DolsSek0rO-JriTfv。模板开发完毕后，需要部署到BAE上方可提交。如果开发者没有执行环境，也可以利用BAE作为开发测试环境。token可以和其它页面参数写在一起使用，如:http:/localhost/test? page=0& token=*注意！为了便于应用创建者预览应用效果，App Builder平台端只支持Chrome、Safari及百度浏览器、搜狗浏览器等其它包含webkit内核的浏览器。所以模板开发者务必保证模板的平台端页面能够兼容上述浏览器。2.2模板的提交模板开发者如果是在本地进行的的开发，在完成模板的开发与测试后，需要将模板部署到BAE中，才能提交到App Builder平台。模板提交时需要填写以下基本信息：l 模板名称与简介模板展示在模板列表中的名称与简介l 模板分类模板面向的应用类型，如注重时效性的新闻类、面向商业的营销类等。模板分类关系到生成的应用的搜索引擎接入l 模板部署信息模板所在的BAE部署l 其它信息如模板的移动端效果缩略图、面向的创建者类型等模板提交成功后，需要通过修改配置文件完善模板的高级信息。模板配置文件是key=value形式的纯文本文件，除了上一步填写的基本信息外，还包含以下配置信息：l default_name: 轻应用默认名称应用创建者使用该模板创建轻应用时的默认应用名称l default_desc: 轻应用默认简介应用创建者使用该模板创建轻应用时的默认应用简介l default_data: 默认应用数据轻应用创建成功时自动灌入的应用数据，格式为json形式，数据类型为json对象，包含两个键：public和private，分别是应用创建时灌入的默认public数据和private数据（有关public与private数据请参考第三章），public与private键对应的数据为json对象，其中的key-value对将被写入到应用数据中。l create_steps: 创建步骤引导创建应用页面看到的创建步骤信息的引导文案，以竖线隔开。最多支持2个步骤，每个步骤最多支持4个汉字l create_url: 创建页面路径应用创建成功后进入的创建页面对应的模板路径，如: /create.php。开发者可以为路径填写包括：以/开头的路径信息，query参数、hash信息（形如:/create.php?foo=bar#nav）。模板调用API的publish接口以完成应用创建l manage_url: 管理页面路径轻应用发布后通过应用列表页进入的应用管理页面的路径，如：/manage.phpl index_url: 访问页面路径轻应用上线后被访问时请求被转发到的页面路径，如：/l worker_interval: 后台任务触发间隔App Builder支持后台任务，以方便模板实现数据更新等定时任务。轻应用创建完成后，App Builder后台会定时地构造一个guest token请求worker_url指定的路径。worker_interval的单位为分钟，最小触发间隔为5分钟。如果设置为0，则不使用后台触发。l worker_url: 后台任务触发路径后台任务触发时的访问路径完成模板信息完善后，开发者可以预览模板效果或提交审核；审核通过后，应用创建者即可用此模板创建轻应用。如果开发者需要对模板进行更新，或改动模板配置，均需再次提交审核并通过后才能更新到线上。3.API使用App Builder后台以http形式为模板提供通用的数据接口API。API的接入域名为：，支持浏览器访问与后端服务器访问两种形式。API以token机制来校验请求来源、类型等信息，以控制访问权限，并决定使用的数据环境（预览or线上数据）及存储空间（用户、appid等），这新信息对模板都是透明的。当模板在浏览器端通过js访问API时，API可以通过http头中的Referer解析出页面地址，并匹配出token信息；当模板通过后端服务发起API请求时，必须在请求地址中附加token参数（如：/api?token=*）。3.1token验证APIApp Builder提供了API以验证token信息。模板可以根据token获取当前请求的部分信息。当模板操作涉及敏感步骤时，可以对当前的token进行验证，以确定请求合法性。 API名称: token API功能：验证token信息 API参数：n token: 公共参数n tplid: 正整数，模板的id 用户访问应用的管理页面或者移动页面时，App Builder会在请求参数中附加模板的id（与token一起），模板可以利用该id获取token信息，或者生成分享链接等 API类型: GET API路径: /api/token API示例: GET /api/token?tplid=2 响应示例:n 成功: status:0,data:appid:123,isadmin:truen 失败: status:1,msg:Bad tplid3.2jsonrpc API绝大多数API为jsonrpc形式，以方便对API进行封装，建立统一的参数传递机制。jsonrpc形式的请求方式为POST，路径为/api，请求内容为json对象，包含method和params两个键。其中method为接口名称，格式为字符串；params为接口参数列表，格式为数组。对于包含默认参数的API，params中可以忽略。如：利用get接口获取key为hello的数据的请求的http头及内容如下:POST /api?token=* HTTP/1.1Host: Content-Type: application/jsonContent-Length: 35method:get,params:hello请求成功时，API响应形如：status:0,data:#，其中data为响应数据（如果API没有返回值，则不包含data字段）；请求失败时（如：token错误，接口不存在，参数类型错误等），响应形如：status:1,msg:xxxxx，其中msg为参考错误信息。绝大多数jsonrpc API均有一个公共参数isPrivate，类型为boolean，默认值为false，表示此次API请求是否为访问private数据。为了保证存储在App Builder的敏感数据不泄露，App Builder后端提供了private数据机制。private数据与非private数据并不存放在一起，二者可以使用相同的key存放不同的数据。使用token既可以访问private数据也可以访问非private数据，除此之外存放在非private空间内的数据，移动端可以通过appid直接读取、遍历。3.2.1query接口query提供了基础的数据查找、遍历功能。其原型为：object query(mixed keyRule,boolean parse_json = false,int start = 0,int limit = 100,boolean isPrivate = false)其中keyRule为查询规则。API支持复杂的key查询，以满足不同需求。keyRule定义为：keyRule := null | string | string | mapl 如果keyRule = null，返回全部数据l 如果keyRule为字符串，返回该字符串为key对应的数据l 如果keyRule为数组，返回数组中全部字符串为key对应的数据l 如果keyRule为对象，返回满足对象中全部key-value构成的规则的数据。keyRule规则支持以下规则： = 、= : 2013-12-01,= : 2013-12-31,!= : 2013-12-25,= : 2013-11-11query接口的第二个参数parse_json表示是否以json格式解码数据内容。App Builder后台以字符串形式存储数据，如果写入数据的时候写入的是其它形式，将以json形式对其进行编码。第三个和第四个参数是分页开始与分页大小。注意start必须是limit的整数倍。query接口返回的数据为所有匹配keyRule的key与value的字典。如果指定了parse_json为true，value为以json格式解码后的数据 API名称：query API功能：查询、遍历数据 API参数：n keyRule: 数据的key规则n parse_json: 是否以json格式解码数据，默认为false，返回字符串n start: 匹配记录的起始条数，默认为0n limit: 匹配记录的返回总条数，默认为100n isPrivate: 是否访问private数据，默认为false API类型：jsonrpc API示例：POST /apimethod:query,params:like:foo%,false,0,100,false 响应示例：status:0,data:foo:bar3.2.2get接口get接口与query接口类似，不过对查询参数进行了简化。get接口的原型为:mixed get(string path, boolean isPrivate = false)object get(string paths, boolean isPrivate = false)path为以.联结的key与数据子键。get接口总是对数据进行json解码，如果path中包含.，get接口对path进行切割，以第一个子串为key，以后续的子串为子key进行数据获取。如：设key=foo的数据，value=abc:def，则以path=foo.abc进行查找，得到结果为def。如果第一个参数类型为字符串，则返回该字符串为path的数据；如果第一个参数类型为数组，则返回其中每个字符串为path得到的结果的字典。 API名称：get API功能：获取数据 API参数：n path | paths: 数据key与子key构成的路径n isPrivate: 是否访问private数据，默认为false API类型：jsonrpc API示例：POST /apimethod:get,params:foo.abc 响应示例：status:0,data:def API示例：POST /apimethod:get,params:foo.abc 响应示例：status:0,data:foo.abc:def3.2.3set接口set接口与get接口相对，用来写入数据。原型为：void set(string path, mixed data, boolean isPrivate = false)如果path包含.，set接口将首先尝试根据key获取原始的数据，利用子key覆盖数据后写回。如果key不存在，将插入新的记录。 API名称：set API功能：写入数据 API参数：n path: 数据key与子key构成的路径n data: 路径对应的数据n isPrivate: 是否访问private数据，默认为false API类型：jsonrpc API示例：POST /apimethod:set,params:foo.abc,def 响应示例：status:03.2.4setString接口setString接口是set接口的底层实现，不支持子key与json编码。API原型为：void setString(string key, string value, boolean isPrivate = false) API名称：setString API功能：写入数据 API参数：n key: 数据keyn value:数据值n isPrivate: 是否访问private数据，默认为false API类型：jsonrpc API示例：POST /apimethod:setString,params:foo,bar 响应示例：status:03.2.5insert接口insert接口接受的参数与set接口相同，不过在存储时会首先尝试插入，如果插入失败（key已存在）再进行更新。在某些场景下，使用insert接口比使用set接口更高效（如：key是动态生成的，重复几率较低）。3.2.6insertString接口与insert接口类似，是setString接口的另一个形式。3.2.7remove接口remove接口用来删除key对应的数据。对应两种形式：void remove(string key, boolean isPrivate = false)void remove(string keys, boolean isPrivate = false)第二个接口形式是批量删除形式。3.2.8keys接口keys接口用来遍历满足条件的数据的key，与query接口相比，它不返回数据的值。keys接口有以下三种形式：string keys(string pattern, boolean isPrivate = false)string keys(string range, boolean isPrivate = false)string keys(mixed keyRule, boolean isPrivate = false)与query接口相比，keys接口对第一个参数的处理稍有不同：首先，如果第一个参数是字符串，keys接口将其当做mysql匹配串的形式（%为通配符）查找匹配该模式的所有key；其次，如果第一个参数是一个长度为2的数组，keys接口将其当做一个key的范围（两边均包含）。 API名称：keys API功能：获取满足条件的数据的key列表 API参数：n pattern | range | keyRule: 匹配规则n isPrivate: 是否访问private数据，默认为false API类型：jsonrpc API示例：POST /apimethod:keys,params:2013-12-01,2013-12-31 响应示例：status:0,data:2013-12-03,2013-12-24,2013-12-273.2.9clear接口clear接口用来清除应用所有数据（private和非private），可以用来在测试阶段重置应用状态。clear接口没有参数，且只接受admin token（test token也是admin token）。clear接口的原型为：void clear()3.2.10sync接口sync接口用来将应用数据从线下预览环境同步到线上环境。当应用发布后，通过应用管理页面维护修改应用信息后，需调用sync接口将数据同步到线上环境。sync接口的原型为：void sync(string keys, string privateKeys = null)其中keys为要同步的非private数据的key列表，privateKeys为要同步的private数据的key列表。需要注意的是，sync接口不涉及应用设置信息、审核数据、检索数据类型的更新。如果与上一次应用发布相比，增加了新的类型的检索数据，必须重新进行发布，重新审核后新的检索数据类型才能生效。sync接口也只接受admin token。3.2.11publish接口publish接口将应用所有预览环境数据同步到线上环境，并更新检索数据类型、根据应用图标和二维码配色重新生成二维码图片，并将应用状态更改为已发布。publish接口没有任何参数，且只接受admin token。应用完成创建流程后，模板需调用publish接口完成创建流程，此后从App Builder平台将不再进入创建页面。如果只是少量数据需要同步到线上环境，可以通过sync接口实现。3.2.12addSitemap接口addSitemap接口提供了对检索信息的维护的封装。模板在应用数据更新成功后，可以通过addSitemap接口更新检索数据。addSitemap接口的原型为：void addSitemap(string type, string url, object data)其中type为检索数据类型（目前只支持generic），url为页面路径，data为检索数据。url参数接受一个包含路径、query参数、hash的字符串，表示要展示的页面在应用内的相对地址。用户通过搜索引擎搜索到该页面时，得到的地址将自动加上host和appid参数。data包含卡片所需的全部检索信息。addSitemap接口将会根据卡片类型，调用不同的json schema对data格式进行验证。如果验证失败，将返回验证信息。addSitemap接口将数据写入到当前上下文所在的存储引擎中。如果模板在worker_url触发页面中调用addSitemap，数据将立即写入线上环境，并将在检索数据下一次更新时被获取到。如果模板在平台的管理页面调用addSitemap，数据将被写入到线下预览环境，模板可以通过publish接口将数据同步到线上。generic类型卡片的验证规则如下：字段名称字段说明类型必需备注name页面名称string是页面标题等provider作者信息string是公司名称、站点名称等description页面简介string是页面摘要articleBody页面正文string是全文检索正文keywords关键词string是页面关键词，多个关键词以$分割breadcrumb导航面包屑stringimage图片url页面相关图片video视频url页面相关视频relatedLink相关链接url页面相关链接地址datePublished发布日期integer是发布日期时间戳，单位为秒copyrightHolder版权信息object版权信息结构体，类型为对象，包含一个字段：section,数据类型为数组，数组元素类型为对象，包含两个字段：siteName和siteUrl，类型分别为string和urlcopyrightYear版权年份integer版权年份时间戳，单位为秒category分类string是如：新闻等 API名称：addSitemap API功能：写入检索信息 API参数：n type: 检索结果类型n url: 页面相对路径n data: 检索数据 API类型：jsonrpc API示例：POST /apimethod:addSitemap,params:generic,/foo/bar?abc=def#hash, name:百度一下,url:/,provider:百度,description:百度一下，你就知道,articleBody:Lorem ipsum dolor sit amet,keywords:百度$搜索,datePublished:1234567890,category:新闻,image:/test.gif,copyrightHolder:section:siteName:baidu,siteUrl:/?aa=bb&cc=dd 响应示例：n 成功：status:0n 失败：status:1,msg: is required3.2.13removeSitemap接口当页面被删除后，模板需要通过removeSitemap接口将对应的检索信息清除。removeSitemap接口原型为：void removeSitemap(string type, string url)其中的参数与数据更新逻辑请参考addSitemap。3.3File APIApp Builder为模板准备了文件上传功能，用户通过File API上传的文件存放在用户自己的个人云存储中。File API以RESTFul形式提供，以便于不同平台编程调用，接口地址规则为：/api/file/path，其中path为文件的存储路径。3.3.1上传文件文件上传请求采用PUT方法，请求内容为文件内容，响应内容文件存放的相对路径。如果文件已存在，API会根据请求参数中是否包含overwrite=true决定覆盖文件或者在文件名后面附加时间戳。如果模板在应用中创建了public目录（通过上传文件或创建目录的方式），则移动端用户可以使用appid通过js编程上传文件到public目录中。 API名称：upload API功能：上传文件 API参数：n overwrite: 如果文件路径重复，是否覆盖文件，默认为falsen dir: 创建目录而不是上传文件，默认为false API类型：PUT API路径：/api/file/path API示例：PUT /api/file/hello.txt?overwrite=trueHost: Content-Type: text/plainContent-Length: 11Hello world 响应示例：status:0,data:/hello.txt3.3.2下载文件File API以GET形式提供文件下载接口以方便编程实现。如果文件不存在，客户端将得到404响应。通过在请求头中指定Range参数，客户端还可以实现分段下载/续传。为了简化模板开发流程中文件的使用，File API支持浏览器直接根据路径下载文件，以实现图片、视频上传功能。例如：模板将图片上传至云存储的/public/upload.png路径，用户浏览到应用后，模板在html中写入：即可展示该图片。图片请求有App Builder后端直接处理并返回。在模板测试阶段，或者在平台端的管理页面进行预览时，该请求会被发送给模板所在的后端，后端需要对该请求进行处理。最简单的处理方式是发送重定向，例如后端使用nginx作为HTTP服务软件，只需在规则中加入如下内容：server listen 80;server_name localhost;.location /api/file/ rewrite /(.*) /$1 permanent;.如果使用BAE进行测试，可以在app.conf的handlers中加入如下内容：-url: /(api/file/.*) status: 302 Location: /$1此外，App Builder后端对来自浏览用户的文件下载请求有一定限制：只允许下载/public/或/public-r/目录下的文件，所以模板在上传图片到File API时如果需要浏览端访问，可以上传到/public-r/目录下。 API名称：download API功能：下载文件 API参数： API类型：GET API路径：/api/file/path API示例：GET /api/file/hello.txt Host: 响应示例：hello world4.使用SDK通过使用SDK可以简化模板开发中API的使用。目前提供php与js两种SDK，供前端与后端使用。4.1php SDK下载php SDK（点此下载）后，将其解压至模板开发目录中，在需要时引入并初始化即可使用。php SDK将jsonrpc API封装为动态调用，如调用get接口，获取key=hello的数据： get(hello);?文件上传接口为：$sdk-file-upload($path, $file