概念:JSON 格式的 API
只有有限的Adaptive Planning REST API 可以使用 JSON 格式提交 Adaptive Planning 和从Adaptive Planning获取数据。在将来的发行版中,更多 API 将使用 JSON 格式。
JSON 请求
每个 JSON 请求都需要:
- HTTP 谓词或方法示例:GET、PUT、或PATCH
- URL 端点。您的授权 URL 和 API 端点可能因Adaptive Planning实例所在的位置而异。有关更多信息,请参见Adaptive Planning身份验证 URL 和 IP 地址。示例:HTTPS://api.adaptiveplanning.com/api/rest/modeling/v1/globosales/sheet/availability
- 授权标头示例:--header 'Authorization: Basic c5RldmVjQLdsb2JvLmNabTpjaGFuZ2VtZQ=='
HTTP 谓词或方法
可用的方法或谓词因服务和资源而异:
方法 | 描述 |
|---|---|
GET | 检索数据集合或单个对象。 |
POST | 使用指定的数据创建单个数据实例。 |
PATCH | 部分更新现有数据。 |
PUT | 更新现有数据,并将现有数据替换为请求正文中的指定数据。 |
DELETE | 删除现有的数据实例。 |
URL 端点
您的授权 URL 和 API 端点可能因Adaptive Planning实例所在的位置而异。有关更多信息,请参见Adaptive Planning身份验证 URL 和 IP 地址。
https://api.adaptiveplanning.com/rest/<service name>/<version>/<tenant>/<resource path>
- service name组件名称,基于以下功能:modeling、或security。
- version服务的版本。所有服务的当前版本:v1。
- tenant此服务的租户,表示Adaptive Planning实例。用途default作为授权中用户的默认实例。
- resource path资源的路径,使用类似名词sheet和availability。该路径还支持查询参数,例如:
- sheetName以指定Adaptive Planning中工作表的名称。
- columnName以指定Adaptive Planning工作表中的列名称。
- limit以指定单个响应中包含的对象数据条目的限制。
- offset以指定要在响应中包括的集合中第一个对象的偏移量。
示例:
https://api.adaptiveplanning.com/api/rest/modeling/v1/globosales/sheet/availability?sheetName=Expense Cube&columnName=Level&columnType=Level
示例:使用 JSON 正文的 POST 请求
curl --location --request POST 'https://api.adaptiveplanning.com/api/rest/modeling/v1/default/sheet/availability?sheetName=Sales Cube&columnName=account&columnType=Account' \ --header 'Authorization: Basic c5RldmVjQLdsb2JvLmNabTpjaGFuZ2VtZQ==' \ --header 'Content-Type: application/json' \ --data-raw '[ { "name": "Discount Percent", "code": "SalesCube.DiscountPercent", "accountGroup": false, "available": true } ]'
收款
资源通常表示业务对象的集合,
Adaptive Planning
以 JSON 集合形式返回。该集合可在开发框架中用于构建业务对象列表。通过标识符访问集合中的特定对象。集合中对象的排序顺序由以下项设置
Adaptive Planning
,并且不可配置。集合的分页由 2 个可选查询参数(limit 和offset)控制。
查询参数 | 描述 |
|---|---|
limit | 单个响应中包含的对象数据条目的限制。默认值为 20,最大值为 100。 |
offset | 要在响应中包括的集合中第一个对象的偏移量。默认值为 0。 |
包含限额和抵销的申请示例
此示例将检索用户实例的集合,
instanceCode
属于GLOBO
。@GET @PATH("/users/instances?instanceCode=GLOBO&limit=20&offset=0") @Produces(MediaType.APPLICATION_JSON) public List<User> getUsers(@PathParam("instanceCode") String instanceCode,@PathParam("limit")int limit,@PathParam("offset")int offset)
包含限额和抵销的回复示例
{ "total": 25, "link": { "next": "https://api.adaptiveplanning.com/api/rest/security/v1/default/users/instances?instanceCode=GLOBO&offset=4&limit=2", "previous": "https://api.adaptiveplanning.com/api/rest/security/v1/default/users/instances?instanceCode=GLOBO&offset=0&limit=2" }, "users": [ { "userId": 14, "userGuid": "474C4F424F000000000000000100000E", "userName": "asiaboss@globo.com", "instances": [ { "code": "GLOBO", "default": true } ] }, { "userId": 21, "userGuid": "474C4F424F0000000000000001000015", "userName": "Bob@globo.com", "instances": [ { "code": "GLOBOSALES" }, { "code": "GLOBOSUB" }, { "code": "GLOBO", "default": true } ] } ] } Note: -Default offset = 0 and limit = 500
凭据类型、身份验证和授权
所有 API 请求都是无状态的单操作请求。必须在每次单独的调用中对用户进行身份验证,以防止入侵者尝试劫持任何现有的 Web 服务会话。
在 API 请求中对用户进行身份验证时,系统不会为此用户创建持续会话。每个单独的 Web 服务调用都必须单独对用户进行身份验证。
该
Adaptive Planning
JSON 格式的 API 支持基本身份验证方法和基于令牌的身份验证方法。Adaptive Planning
支持 JSON 格式的真正 REST API,并在请求标头中指明授权,而不是像 XML API 那样在请求正文中指明。有关 XML API 示例,请参见请求和响应消息格式和使用Workday凭据发出Adaptive Planning API 请求。基本身份验证
基本身份验证在身份验证标头中使用经过 Base64 编码的用户名和密码。
示例:
'Authorization': 'Basic <insert base64 encoded string>'
示例:
xyz@demo.com:password
编码为 eHl6QGRlbW8uY29tOnBhc3N3b3Jk
基于令牌的身份验证 (TBA)
如果您将Workday中的用户同步到Adaptive Planning,则必须使用基于令牌的身份验证方法。要获取令牌,请按照使用Workday凭据发出Adaptive Planning API 请求中的步骤操作。获取令牌后,在标头中传递该令牌。
Sample:'Authorization': 'Bearer <在此处插入令牌>'
示例:'
Authorization: Bearer eyJjdHkiOiJ0ZXh0L3BsYWluIiwiYWxnIjoiSFMyNTYifQ.eyJsb2dpbl9pZCI6InN0ZXZlY0BheWdsb2JvLmNvbSIsIm5iZiI6MTU4NjEzMDA2NywibXVsdGlfdXNlIjoiMCIsImlzX2F1dGgiOiIxIiwiZXhwIjoxODg2MTMwMTg3LCJpYXQiOjE2MDM5NDYwMjEsImp0aSI6IjM0YzFkZDY2LTY2MTMtNDk0Ny05MjFhLTliZDQ2ZDVmZDkwNyJ9.FZnLHGQ3dNfpzvW-A9ILi53z6YLGNNI45Mlc-4NT3As'