>[danger]### 在官方不久前宣布提供统一API接口服务之后,`SDK`接口现在也已经正式发布了`1.0`版本。 ## `ThinkAPI`服务介绍 开发者经常为了各种功能而四处寻找是否有相应的API接口,即便找到了可能还要忍受第三方各种奇葩的SDK调用,或者不支持`composer`安装。 >[danger]### `ThinkAPI`统一`API`接口服务是由官方联合合作伙伴封装的一套接口调用服务及`SDK`,旨在帮助`ThinkPHP`开发者更方便的调用官方及第三方的提供的各类`API`接口及服务,从而更好的构建开发者生态。 ### 一站式接口服务 `ThinkAPI`提供了一站式的接口服务,从接口购买、调用到SDK封装都只需要一个官方账号即可完成,无需注册各种接口服务账号,除了涵盖常用`API`服务之外,还设计了可转换接口服务更好的保障接口的稳定性,让你省心省力。 ### 提供统一的`SDK` 官方提供了一套统一的`SDK for PHP`调用服务,通过`composer`安装一个轻量级的依赖包即可调用,采用简洁和现代化的调用方式,并且对IDE友好,可以简化你的`API`调用开发工作。 ### 官方服务市场保障 `ThinkAPI`所有支持的接口都纳入[官方服务市场](https://www.thinkphp.cn/partner/78),包括免费接口和付费接口,市场服务有保障,并且有购买记录以及统计数据。 对于一些付费的接口,官方的[服务市场](https://www.thinkphp.cn/partner/78)提供了更优惠的价格。 ## `ThinkAPI`调用流程 请务必按照如下流程进行`ThinkAPI`接口服务调用: * 第一步:注册[服务市场账号](https://market.topthink.com/auth/login)获取个人`AppCode`; * 第二步:购买[接口服务(次数)](https://market.topthink.com/partner/78),免费接口则跳过; * 第三步:通过接口地址(及参数)或者`SDK`调用接口服务返回数据; ## 身份认证(AppCode) 无论是免费还是付费接口,都需要通过`AppCode`授权后才能进行接口请求。`AppCode`的值可以在官方服务市场`->`个人中心`->`[API管理](https://market.topthink.com/setting/api)的上方查询到,每个用户账号拥有一个唯一的`AppCode`值(请不要随意泄露)。 ![](https://img.kancloud.cn/c4/84/c484de0d4130341987d4a90779b207bc_1250x604.png) 可以使用两种方法进行身份认证: ### 第一种:`Header`信息认证(推荐) 在请求`Header`中添加的`Authorization`字段,配置值为“AppCode + 半角空格 +AppCode值”。 格式如下: ~~~ Authorization:AppCode AppCode值 ~~~ ### 第二种:请求参数认证 请求Query中添加的`appCode`参数,参数的值为用户`AppCode`的值。 ~~~ https://API接口地址?appCode=AppCode值 ~~~ ## 原生`API`调用 `ThinkAPI`所有支持的接口服务都有一个唯一的接口调用地址,这个接口地址统一使用`https://api.topthink.com` 作为接口网址,例如身份证查询接口的请求地址是: ``` https://api.topthink.com/idcard/index ``` 你可以通过下面的请求来调用接口 ``` https://api.topthink.com/idcard/index?appCode=AppCode值&cardno=要查询的身份证号码 ``` 你可以在注册市场账号后测试下这个免费接口,查看具体的返回数据。 >[danger]注意:部分接口可能采用不同的请求类型,不一定是`GET`请求,具体的接口参数请参考具体的API文档,会有详细的说明。 ### 返回数据格式 所有的`api`接口返回数据规范如下: | 名称 | 类型 | 说明 | | --- | --- | --- | | code | int | 返回码,0 表示成功 其它表示失败 | | message | string | 返回提示信息 | | data | object | 返回数据 | >[danger] 当`code`为0的时候计费,其中`data`包含的数据和具体的接口有关。 ## 使用`SDK`调用 除了使用原生的方式调用接口外,`ThinkAPI`还提供了一套通用的`SDK`接口规范,让你用更简洁和现代化的方式调用接口服务。使用方法如下: 首先需要在你的项目里面安装`think-api`库 ~~~ composer require topthink/think-api ~~~ > 建议设置使用[阿里云 Composer 全量镜像](https://developer.aliyun.com/composer) 然后就可以调用你需要的接口进行查询和返回数据,还是以上面的查询身份证所属地区接口为例说明: ~~~ use think\api\Client; // API调用之前必须设置`AppCode`值,用于接口调用的身份认证 $client = new Client("YourAppCode"); // 调用某个接口方法和传入参数 $result = $client->idcardIndex() ->withCardno('身份证号码') ->request(); var_dump($result); ~~~ 所有的接口服务和方法都支持IDE自动提示和完成(请务必注意方法大小写必须保持一致 确保参数名的正确性),基本上不需要文档即可完成接口开发工作。 上面是免费接口的SDK调用示例,付费接口的调用方式是完全一样的,区别在于付费接口你必须要先在市场购买接口次数才能正常调用(`ThinkAPI`服务的接口必须在[官方市场](https://market.topthink.com/partner/78)购买才有效,第三方购买的接口是不支持调用的),而免费接口则有每天不超过100次请求的限制。 下面是身份证实名认证的付费接口调用示例: ``` $client = new Client("YourAppCode"); $result = $client->idcardQuery() ->withIdcard('身份证号码') ->withRealname('姓名') ->request(); var_dump($result); ``` > 注意,该SDK服务仅支持官方已经接入的API接口,目前接口数量正在扩充中,你可以联系我们反馈你需要的API接口,我们来统一进行接入。 ## 成为`API`供应商 面向服务开发将是将来的一大开发趋势,如果你计划在100万+的ThinkPHP开发者中推广你们的服务,欢迎联系!诚邀合作伙伴(包括但不限于API服务商或对外提供开放API的产品服务商)加入官方统一API接口服务计划。 ## 联系我们 成为API供应商或者反馈你需要的API接口请联系微信`topthink`(注明来意)。