Heroku第三方服务接入指南（二）

上文我们讲了第三方服务、Heroku、用户三者的关系，这一篇进入正题，了解第三方厂商（下文简称厂商）怎样为Heroku开发服务。这里仅仅做简介，了解heroku大致是怎么做的。假设你的平台。希望接入第三方服务，你正在犯愁，这个流程要怎么做，那么本文对你将有所启示。假设你希望实操接入heroku，请进一步查阅heroku官方文档。

本文主要概述了接入到heroku前要做的三个事情：创建配置（heroku和服务的协议），实现配置指定的接口，測试。简介了提高接入效率相关的工具。

一、工具

1.kensa。heroku提供了一个命令行的工具，它能够生成接入heroku所需的配置、測试接口。

2.Logplex.日志组件。第三方服务商能够将日志输出到这里，然后heroku用户就能在heroku平台看到日志。

3.foreman.heroku推荐的一个本地web执行容器。让你在本地能够启动并訪问服务。

二、创建接口配置

heroku和第三方厂商是通过一份配置文件来对接的。

heroku拿到这个配置文件后。才干知道服务的地址，资源接口。

这份配置，能够通过kensa来生成。有两个相关的命令，kensa init、kensa create。两者都能生成前文所述的配置文件--addon-manifest.json。不同之处在于，后者还能生成一个空的项目模版。

让我们来看一份addon-manifest.json样例

{
  "id": "errorbucket",
  "api": {
    "config_vars": [
      "ERRORBUCKET_URL"
    ],
    "password": "GqAGAmdrnkDFcvR9",
    "sso_salt": "7CwqmJLEjv8YZTXK",
    "regions": ["us","eu"],
    "requires": ["log_input"],
    "production": {
      "base_url": "https://errorbucket.com/heroku/resources",
      "sso_url": "https://errorbucket.com/sso/login"
    },
    "test": {
      "base_url": "http://localhost:4567/heroku/resources",
      "sso_url": "http://localhost:4567/sso/login"
    }
  }
}

id：服务名。用户能够通过heroku addons:add [id]来加入这个第三方服务

api/config_vars：创建资源时，返回的參数名列表。比如用户希望创建mysql服务，这时要返回參数，參数名是这里定义的config_vars，參数值是相应的资源唯一url

api/password：heroku发送请求给第三方server时，都会带上这个密码。

api/sso_salt：用于支持sso登录

api/regions：服务区域。

仅仅同意这里指定的区域訪问服务。主要考虑到对时延高要求的服务，对地域要求较高。假设没办法给全部地区的用户都提供高质量服务，那就限制一下吧。

api/production/base_url：生产环境的

api/test/：測试环境

三、实现接口

接口的详细实现，heroku是不关注的。主要关注下面约定

1、约定：

1、全部的接口都要使用http basic auth认证

2、假设接口不可用，应当返回422

3、假设status是422或者503。返回中的message（出错信息）可能会直接展示给用户。假设是其它异常状态码。则展示统一的出错信息

4、rest api。

资源的增删改，都相应为同一个url。如https://username:password@api.youraddon.com/heroku/resources。请求类型为Post表示创建，DELETE表示删除（需带上id，如https://username:password@api.youraddon.com/heroku/resources/:id），PUT表示改动（带上id）

5、请求參数名已由heroku定死，比如heroku_id表示用户id等。假设有自己定义字段。组装成一个options对象。

6、请求返回，能够将一些备注信息放到message字段

2、接口实例

添加资源

Request: POST https://username:password@api.youraddon.com/heroku/resources
Request Body: {
  "heroku_id": "app123@heroku.com",
  "plan": "basic",
  "region": "amazon-web-services::us-east-1",
  "callback_url": "https://api.heroku.com/vendor/apps/app123%40heroku.com",
  "log_input_url": "https://token:t.01234567-89ab-cdef-0123-456789abcdef@1.us.logplex.io/logs",
  "options": {}
}
Response Body: {
  "id": "your-internal-unique-id",
  "config": {"MYADDON_URL": "http://myaddon.com/52e82f5d73"},
  "message": "your message here"
}

删除资源

Request: PUT https://username:password@api.youraddon.com/heroku/resources/:id
Request Body: {"heroku_id": "app123@heroku.com", "plan": "premium"}
Response Body: {"config": { ... }, "message": "your message here"}

改动资源

Request: DELETE https://username:password@api.youraddon.com/heroku/resources/:id
Request Body: none
Response Status: 200

四、測试

还是借助于kensa这个工具。它提供了两个层级的測试能力。

1、服务端測试

模拟herokuserver訪问第三方服务接口的过程

kensa test provision。能够測试”test“环境，创建资源接口

 kensa test provision
Testing POST /heroku/resources
  Check response [PASS]
  Check valid JSON [PASS]
  Check authentication [PASS]
Testing response
  Check contains an id [PASS]
Testing config data
  Check is a hash [PASS]
  Check all config keys were previously defined in the manifest [PASS]
  Check all config values are strings [PASS]
done.

測试输出如上，能够看到它依次做了下面測试：验证有结果返回。验证是否做了权限验证（强制要求带权限验证），返回信息校验（包括了指定信息）

还能够通过kensa test deprovision測试”删除资源“，kensa test planchange測试资源信息变更

2、client測试

模拟heroku用户訪问第三方服务接口的过程。

首先你要实现一份代码demo。通过环境变量的方式获取资源url，然后再执行kensa run demo。run的过程，实际包括了下面步骤：调用接口创建资源，将资源url注入到环境变量中，执行你的demo（由于前面已经注入了环境变量，这时候你的demo应当能拿到资源并做操作），最后是调用接口删除资源

五、其它

1、heroku提供了api，第三方服务通过api查询服务的用户信息等。

2、支持SSO登录

3、服务供应商能通过Logplex将日志实时输出到heroku上。