使用REST-API

您可以通过 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 运行示例程序。

正常结果示例

> mvn spring-boot:run
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v2.0.6.RELEASE)

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)
2020-02-17 18:00:09.059  INFO 79141 --- [           main] com.aliyun.baas.MainApplication          : No active profile set, falling back to default profiles: default
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
2020-02-17 18:00:09.775  INFO 79141 --- [           main] o.s.j.e.a.AnnotationMBeanExporter        : Registering beans for JMX exposure on startup
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)
<200,class InlineResponse2002 {
    success: true
    result: class Block {
        number: 1
        hash: 1c397c4eb3e0e330c01ec430170f844e46159f16930aa347486b8153b6586548
        previousHash: 88ef0ad6ba2df7ba7e53de78575d2d14cee2253fe6897305e50b57ceeecebc78
        createTime: 1579056958
        transactions: []
        data: {data={data=[{payload={data={config={channel_group= ... }}}}]}}
    }
    error: class Error {
        code: 200
        message: Success
        requestId: edf8fe52-7cef-447f-a04a-7b8c1db56487
    }
},{Server=[nginx], Date=[Mon, 17 Feb 2020 10:00:10 GMT], Content-Type=[application/json; charset=UTF-8], Transfer-Encoding=[chunked], Connection=[keep-alive]}>
<200,class InlineResponse200 {
    success: true
    result: class Response {
        id: a5f5503f12b92a4c59e079e1baf49b517785e2d9988f90dfb234f6c3954a2389
        status: 200
        event: null
        data: MTU4MTkzMzYxMDEzNg==
    }
    error: class Error {
        code: 200
        message: Success
        requestId: 71a9f95f-ea5b-4dea-b4a1-a608ae429fb4
    }
},{Server=[nginx], Date=[Mon, 17 Feb 2020 10:00:11 GMT], Content-Type=[application/json; charset=UTF-8], Content-Length=[249], Connection=[keep-alive]}>
<200,class InlineResponse200 {
    success: true
    result: class Response {
        id: ba50180c9fe38c9be115f20775b78e80b7a1205c34ef34b66fab635efedc3b49
        status: 200
        event: null
        data: MTU4MTkzMzYxMDEzNg==
    }
    error: class Error {
        code: 200
        message: Success
        requestId: c703a36b-3589-4a8b-87a0-5e5bf56b2396
    }
},{Server=[nginx], Date=[Mon, 17 Feb 2020 10:00:11 GMT], Content-Type=[application/json; charset=UTF-8], Content-Length=[249], Connection=[keep-alive]}>
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  4.217 s
[INFO] Finished at: 2020-02-17T18:00:11+08:00
[INFO] ------------------------------------------------------------------------
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
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 运行示例程序。

正常结果示例

> go run main.go
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": ...}}}}]}}}
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"}}
Invoke contract response: "MTU4MTkzNDAwOA=="
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"}}
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 运行示例程序。

正常结果示例

> node main.js
{ number: 1,
  hash: '1c397c4eb3e0e330c01ec430170f844e46159f16930aa347486b8153b6586548',
  create_time: 1579056958,
  previous_hash: '88ef0ad6ba2df7ba7e53de78575d2d14cee2253fe6897305e50b57ceeecebc78',
  transactions: [],
  data:
   { data: { data: [Array] },
     header:
      { data_hash: 'HDl8TrPg4zDAHsQwFw+ETkYVnxaTCqNHSGuBU7ZYZUg=',
        number: '1',
        previous_hash: 'iO8K1rot97p+U954V10tFM7iJT/miXMF5QtXzu7OvHg=' },
     metadata: { metadata: [Array] } } }
Data 1581931486180 pushed to blockchain with transaction f19217c0db571dc715af8ad99025422f03e5561910371841fe5e69a356d0cb23
{ id: '8fd06f6087c5128b7dbe309658b170366b37e0733994e5e959d30be201c28827',
  status: '200',
  events: [],
  data: 'MTU4MTkzMTQ4NjE4MA==' }
阿里云首页 区块链服务 BaaS 相关技术圈