全部产品
Search
文档中心

使用REST-API

更新时间: 2020-04-03

您可以通过 REST API 调用智能合约,写入或查询链上信息,也可以查询区块及交易信息,并监听区块链事件。区块链 REST-API 使用 Bearer Token 的认证方式,在调用API时,您需要额外指定 HTTP 头 “Authorization: Bearer <Your Access Token>” 来提供您的 Access Token。

注意:您需要通过工单联系阿里云支持团队开通此功能。

生成 Access Token

您可以按照以下步骤生成 Access Token 与 Refresh Token,用来访问 REST-API 以及更新 Access Token。

  1. 进入组织的 REST-API 展示页面,如果您未安装云服务集成功能,需要按照引导完成安装,更多请参考安装云服务集成用户入口

  2. 点击页面右上角的“生成Token”,会弹出如下对话框。根据使用场景,选择合适的 Access Token 与 Refresh Token 的有效期,并勾选 Token 具有的权限。生成Token

  3. 点击侧边栏的“生成Token”,会在下方展示生成的 Token 信息。

使用 Swagger UI,测试 REST-API

使用 REST-API 展示页面中的 Swagger UI 之前,您需要先生成Access Token, 才能打开 Swagger UI 控制台测试 REST-API。

配置Access Token

如果您生成的 Access Token 已经过期,或者希望测试应用APP使用的特定 Access Token,您可以按照以下步骤修改 Swagger UI 控制台使用的 Access Token。

  1. 点击页面中的“Authorize”按钮,弹出认证信息输入对话框。认证按钮

  2. 如果已经配置了 Access Token,先点击“Logout”删除旧的认证信息。退出认证

  3. 在 “Value” 中输入我们已经生成好的 Access Token,并点击“Authorize”。输入Token

  4. 点击“Close”关闭对话框,我们可以看到 API 右侧的小锁已经是锁定状态,表示我们已经成功输入了认证信息认证完成

发起请求

  1. 选择您想要调试的 REST API(这里以 invoke 为例),点击API标题,展开详细描述。API描述
  2. 点击描述右侧的“Try it out”,按照调试需求,调整API的参数。API参数

  3. 点击“Execute”发起请求,请求返回后,您可以在下方看到返回结果。API返回结果

注:接口 /networks/{network}/events/subscribe 不能通过 Swagger UI 调试,测试方法请参考文档订阅事件

刷新 Access Token

Access Token 有效期较短,在 Token 即将过期时需要使用 Refresh Token 来获取新的 Access Token。REST-API 提供了符合 OAuth 2.0 标准的刷新接口 “/api/v1/token”,我们建议您使用标准 OAuth SDK 来自动刷新Token并访问 REST-API。您可以在 OAuth 库实现 中找到各个语言的 OAuth Client 实现,也可以在这里直接访问我们提供的几种常用语言的 Client SDK 使用示例:

SDK的调用参数默认基于示例链码,您可以在文档智能合约示例中获取示例链码 notary 。

Java SDK 示例

  1. 获取 Java SDK 示例,需要 java 版本 >= 1.8。

  2. 根据您组织实例的 REST-API 地址、生成的 Token 信息、业务通道和链码信息,修改文件 java-oauth-client/src/main/resources/application.properties

  3. 进入目录 java-oauth-client 执行 mvn spring-boot:run 运行示例程序。

正常结果示例

  1. > mvn spring-boot:run
  2. . ____ _ __ _ _
  3. /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
  4. ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
  5. \\/ ___)| |_)| | | | | || (_| | ) ) ) )
  6. ' |____| .__|_| |_|_| |_\__, | / / / /
  7. =========|_|==============|___/=/_/_/_/
  8. :: Spring Boot :: (v2.0.6.RELEASE)
  9. 2020-02-17 18:00:09.056 INFO 79141 --- [ main] com.aliyun.baas.MainApplication : Starting MainApplication on Bright.local with PID 79141 (java-oauth-client/target/classes started by bright in java-oauth-client)
  10. 2020-02-17 18:00:09.059 INFO 79141 --- [ main] com.aliyun.baas.MainApplication : No active profile set, falling back to default profiles: default
  11. 2020-02-17 18:00:09.092 INFO 79141 --- [ main] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@5bf85360: startup date [Mon Feb 17 18:00:09 CST 2020]; root of context hierarchy
  12. 2020-02-17 18:00:09.775 INFO 79141 --- [ main] o.s.j.e.a.AnnotationMBeanExporter : Registering beans for JMX exposure on startup
  13. 2020-02-17 18:00:09.792 INFO 79141 --- [ main] com.aliyun.baas.MainApplication : Started MainApplication in 0.958 seconds (JVM running for 3.321)
  14. <200,class InlineResponse2002 {
  15. success: true
  16. result: class Block {
  17. number: 1
  18. hash: 1c397c4eb3e0e330c01ec430170f844e46159f16930aa347486b8153b6586548
  19. previousHash: 88ef0ad6ba2df7ba7e53de78575d2d14cee2253fe6897305e50b57ceeecebc78
  20. createTime: 1579056958
  21. transactions: []
  22. data: {data={data=[{payload={data={config={channel_group= ... }}}}]}}
  23. }
  24. error: class Error {
  25. code: 200
  26. message: Success
  27. requestId: edf8fe52-7cef-447f-a04a-7b8c1db56487
  28. }
  29. },{Server=[nginx], Date=[Mon, 17 Feb 2020 10:00:10 GMT], Content-Type=[application/json; charset=UTF-8], Transfer-Encoding=[chunked], Connection=[keep-alive]}>
  30. <200,class InlineResponse200 {
  31. success: true
  32. result: class Response {
  33. id: a5f5503f12b92a4c59e079e1baf49b517785e2d9988f90dfb234f6c3954a2389
  34. status: 200
  35. event: null
  36. data: MTU4MTkzMzYxMDEzNg==
  37. }
  38. error: class Error {
  39. code: 200
  40. message: Success
  41. requestId: 71a9f95f-ea5b-4dea-b4a1-a608ae429fb4
  42. }
  43. },{Server=[nginx], Date=[Mon, 17 Feb 2020 10:00:11 GMT], Content-Type=[application/json; charset=UTF-8], Content-Length=[249], Connection=[keep-alive]}>
  44. <200,class InlineResponse200 {
  45. success: true
  46. result: class Response {
  47. id: ba50180c9fe38c9be115f20775b78e80b7a1205c34ef34b66fab635efedc3b49
  48. status: 200
  49. event: null
  50. data: MTU4MTkzMzYxMDEzNg==
  51. }
  52. error: class Error {
  53. code: 200
  54. message: Success
  55. requestId: c703a36b-3589-4a8b-87a0-5e5bf56b2396
  56. }
  57. },{Server=[nginx], Date=[Mon, 17 Feb 2020 10:00:11 GMT], Content-Type=[application/json; charset=UTF-8], Content-Length=[249], Connection=[keep-alive]}>
  58. [INFO] ------------------------------------------------------------------------
  59. [INFO] BUILD SUCCESS
  60. [INFO] ------------------------------------------------------------------------
  61. [INFO] Total time: 4.217 s
  62. [INFO] Finished at: 2020-02-17T18:00:11+08:00
  63. [INFO] ------------------------------------------------------------------------
  64. 2020-02-17 18:00:11.573 INFO 79141 --- [ Thread-3] s.c.a.AnnotationConfigApplicationContext : Closing org.springframework.context.annotation.AnnotationConfigApplicationContext@5bf85360: startup date [Mon Feb 17 18:00:09 CST 2020]; root of context hierarchy
  65. 2020-02-17 18:00:11.574 INFO 79141 --- [ Thread-3] o.s.j.e.a.AnnotationMBeanExporter : Unregistering JMX-exposed beans on shutdown

Go SDK 示例

  1. 获取 Go SDK 示例, 需要 go 版本为 1.13.x。

  2. 根据您组织实例的 REST-API 地址、生成的 Token 信息、业务通道和链码信息,修改文件 go-oauth-client/src/go-oauth-client/main.go 中的参数。

  3. 进入目录 go-oauth-client/src/go-oauth-client 执行 go run main.go 运行示例程序。

正常结果示例

  1. > go run main.go
  2. Block response body: {"Success":true,"Result":{"number":1,"hash":"1c397c4eb3e0e330c01ec430170f844e46159f16930aa347486b8153b6586548","create_time":1579056958,"previous_hash":"88ef0ad6ba2df7ba7e53de78575d2d14cee2253fe6897305e50b57ceeecebc78","transactions":[],"data":{"data":{"data":[{"payload":{"data":{"config":{"channel_group": ...}}}}]}}}
  3. Invoke response body: {"Success":true,"Result":{"id":"e0a11c3b953fa1759ef715214bb8bd24c0a7e762b739eb5f645ead921314fef4","status":"200","events":[],"data":"MTU4MTkzNDAwOA=="},"Error":{"code":200,"message":"Success","request_id":"c3c92ad0-a0ef-4a82-b596-4ac50a893ef6"}}
  4. Invoke contract response: "MTU4MTkzNDAwOA=="
  5. Query response body: {"Success":true,"Result":{"id":"c3d4c2928dfa7129641863b18dfeee4b18c7227929c841ff7d8bd25148f6c5f6","status":"200","events":[],"data":"MTU4MTkzNDAwOA=="},"Error":{"code":200,"message":"Success","request_id":"f1bf52b2-8c60-491e-9a40-8fecb96667ea"}}
  6. Query contract response: "MTU4MTkzNDAwOA=="

Node SDK 示例

  1. 获取 Node SDK 示例, 需要 nodev8 版本 >= 8.17。

  2. 根据您组织实例的 REST-API 地址、生成的 Token 信息、业务通道和链码信息,修改文件 node-oauth-client/main.js 中的参数。

  3. 进入目录 node-oauth-client 执行 npm install 安装依赖包,再执行 node main.js 运行示例程序。

正常结果示例

  1. > node main.js
  2. { number: 1,
  3. hash: '1c397c4eb3e0e330c01ec430170f844e46159f16930aa347486b8153b6586548',
  4. create_time: 1579056958,
  5. previous_hash: '88ef0ad6ba2df7ba7e53de78575d2d14cee2253fe6897305e50b57ceeecebc78',
  6. transactions: [],
  7. data:
  8. { data: { data: [Array] },
  9. header:
  10. { data_hash: 'HDl8TrPg4zDAHsQwFw+ETkYVnxaTCqNHSGuBU7ZYZUg=',
  11. number: '1',
  12. previous_hash: 'iO8K1rot97p+U954V10tFM7iJT/miXMF5QtXzu7OvHg=' },
  13. metadata: { metadata: [Array] } } }
  14. Data 1581931486180 pushed to blockchain with transaction f19217c0db571dc715af8ad99025422f03e5561910371841fe5e69a356d0cb23
  15. { id: '8fd06f6087c5128b7dbe309658b170366b37e0733994e5e959d30be201c28827',
  16. status: '200',
  17. events: [],
  18. data: 'MTU4MTkzMTQ4NjE4MA==' }