phalapi-pro/public/wiki/2x-how-to-use-api.md

如何调用接口

以下将通过简明的方式，介绍客户端如何调用接口。

API入口

假设您的域名是：http://open.phalapi.net，则：

• App开放接口API入口：http://open.phalapi.net/api/app.php
• Platform开放平台接口API入口：http://open.phalapi.net/api/app.php
• Admin管理后台接口API入口：http://open.phalapi.net/api/admin.php
• Task计划任务接口API入口：http://open.phalapi.net/api/admin.php

首先，不同系列的接口，必须要找到对应的API入口。因为不同的入口处理的方式、权限判断和场景都不相同，并且方便分别进行个性化控制而不相互影响。

请求方式

通过HTTP/HTTPS协议，便可以请求接口。

例如对于默认的接口服务：http://open.phalapi.net/api/app.php?s=App.HelloWorld.Say，直接用浏览器打开访问，可以得到结果：

{
  "ret": 200,
  "data": {
    "content": "Hello PhalApi Pro!"
  },
  "msg": ""
}

如果通过CURL方式请求，则结果为：

$ curl http://open.phalapi.net/api/app.php\?s\=App.HelloWorld.Say
{"ret":200,"data":{"content":"Hello PhalApi Pro!"},"msg":""}

通常情况下，可以使用GET或POST方式请求接口，但推荐使用POST方式请求接口。原因有几点：

• 1、GET方式容易存在编码问题导致参数解析失败，但POST方式不会；
• 2、GET参数有最大长度限制，当GET参数过长过大时会提示错误，但POST方式不会；
• 3、GET方式容易被抓包或在服务器存在日志，容易导致密码等敏感信息泄露，POST方式相对安全。

指定接口

和PhalApi开源版一样，通过s参数（完整参数名是service，两者等效），可以指定调用哪一个接口服务。

关于全部的接口，可以通过在线接口文档查看。当未指定接口时，默认接口服务是App.Site.Index。

例如：

# 请求默认接口
http://open.phalapi.net/api/app.php

# 请求会员注册接口
http://open.phalapi.net/api/app.php?s=App.User.Register

# 请求获取文件列表接口（需要切换到后台API入口）
http://open.phalapi.net/api/admin.php?s=Admin.File.GetList

需要注意的是，不同接口的访问入口不同，需要注意区分。

请求参数

如你所见，s或service参数用于指定接口服务。除此之外，公共的接口参数目前有：

• access_token：token令牌，用于接口验证，后面会继续讲解。

每个接口的参数，可以通过接口文档查看，例如：

如无特殊说明，接口参数均可使用GET或POST。

返回结构

如前文所述，以及遵循PhalApi开源版的格式，接口返回的是JSON格式。例如：

{"ret":200,"data":{"title":"Hello PhalApi Pro","version":"1.0","time":1577697960},"msg":""}

格式后是：

{
    "ret": 200,
    "data": {
        "title": "Hello PhalApi Pro",
        "version": "1.0",
        "time": 1577697960
    },
    "msg": ""
}

全部接口，返回的接口结果结构分为三部分：

• ret：状态码，整型，200表示成功，4xx表示客户端非法请求，5xx表示服务器错误
• data：成功时返回的业务数据，通常为对象类型，具体由接口服务而定
• msg：失败时的错误提示信息，字符类型

具体每个接口返回的结果，可以访问接口文档，查看指定接口服务文档的返回结果说明。例如：

也可以查看接口返回示例：

验证方式

PhalApi专业版使用的是access_token令牌验证的方式，在开始使用接口时，需要先申请令牌。申请令牌有两种方式：

• 方式一：通过应用来申请令牌：根据开发者应用的app_key和app_secret申请access_token令牌
• 方式二：通过会员来申请令牌：结合已获得的应用access_token令牌，根据会员账号和密码进行登录并获取新的access_token令牌

获取令牌

方式一：通过应用来申请令牌

这种方式，要求：

• 应用存在：首先需要创建应用，并且审核通过
• 密钥正确：应用app_key和app_secret正确
• 正常状态：应用处于正常状态（若为禁用则不可用）
• 接口权限：应用在调用指定接口时需要拥有相应接口的权限

需要使用的接口是：App.Auth.ApplyToken。

方式二：通过会员登录来申请令牌

方式二，要求：

• 注册账号：已经有注册的会员账号
• 密码正确：会员账号和密码正确
• 正常状态：会员处于正常状态（若为禁用则不可登录）
• 指定应用：通过方式一获得有有效令牌

需要使用的接口是：App.User.UserLogin。

通过access_token参数传递成功申请到的令牌，若令牌过期或无效，接口将会返回ret=406，例如：

{
    "ret": 406,
    "data": {},
    "msg": "非法请求：access_token校验不通过"
}

若令牌有效，则可以正常请求接口。

刷新令牌

令牌过期时间默认为30天，可以通过./config/app.php配置文件的jwt里的exp来自行修改，如设置为7天：

/**
 * JWT令牌
 */
'jwt' => array(
        'key' => '1j7zo53mnsLK', // 用于加密的key（安装时自动生成，不能修改！）
        'exp' => 7 * 86400, // 令牌生成后多少秒内有效，可自行修改
),

在令牌过期前，可以通过App.Auth.RefreshAccessToken接口刷新令牌，从而延长有效期。刷新后有效期会重新延长到jwt里面exp指定的时间。

开放平台与管理后台的身份校验

对于内部，可以通过登录开发者账号，或者通过登录管理员账号来获得令牌。此时使用的接口是Platform.User.UserLogin。