概念:JSON 格式的 API
只有有限的 Adaptive Planning REST API 可以使用 JSON 格式提交 Adaptive Planning 数据以及从中获取数据。在将来的发行版中,更多 API 将使用 JSON 格式。
JSON Requests
每个 JSON 请求都需要:
- HTTP 谓词或方法示例:GET、PUT、或PATCH
- URL 端点。如果您的实例使用的不是基于美国的区域身份验证,则您的授权 URL 和 API 端点会因您所在的区域而异。请参见 参考信息:区域身份验证 URL。示例:HTTPS://api.adaptiveplanning.com/api/rest/modeling/v1/globosales/sheet/availability
- 授权标头示例:--header 'Authorization: Basic c5RldmVjQLdsb2JvLmNabTpjaGFuZ2VtZQ=='
HTTP 谓词或方法
可用的方法或谓词因服务和资源而异:
方法 | 描述 |
|---|---|
GET | 检索数据集合或单个对象。 |
POST | 使用指定的数据创建单个数据实例。 |
PATCH | 部分更新现有数据。 |
PUT | 更新现有数据,并将现有数据替换为请求主体中的指定数据。 |
DELETE | 删除现有数据实例。 |
URL 端点
如果您的实例使用的不是基于美国的区域身份验证,则您的授权 URL 和 API 端点会因您所在的区域而异。请参见 参考信息:区域身份验证 URL。
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'