使用Composer查询语言和REST API的查询教程

使用Composer查询语言和REST API的查询教程

在本教程中，我们将在开发者教程的基础上进行扩展，以展示查询。原生查询语言可以使用条件过滤返回的结果，并可以在交易中被调用以执行操作，例如更新或删除结果集上的资产。

查询在查询文件（.qry）中定义，文件位于业务网络定义的父目录中的。查询包含一个WHERE子句，它定义了选择资产或参与者的过滤条件。

本教程使用tutorial-network业务网络，该网络开发者教程中被开发和部署。

先决条件

开始本教程之前：

完成开发环境的安装。
完成开发者教程。

第一步：更新业务网络

开发者教程中创建的业务网络必须更新。更新的业务网络包含两个事件和一个额外的交易。

更新模型文件

模型文件必须更新以包含事件和新交易。

1、打开业务网络tutorial-network的模型（.cto）文件。
2、将以下事件和交易添加到模型中：

   event TradeNotification {
       --> Commodity commodity
   }
   transaction RemoveHighQuantityCommodities {
   }
   event RemoveNotification {
       --> Commodity commodity
   }

3、将更改保存到模型中。

更新交易逻辑以使用查询和事件

现在，域模型已经更新，我们可以编写额外的业务逻辑，在提交交易处理时执行。在本教程中，我们将事件和查询添加到下面的业务逻辑中。

1、打开交易处理器函数文件lib/logic.js。
2、用下面的JavaScript替换交易逻辑：

   /**
    * Track the trade of a commodity from one trader to another
    * @param {org.acme.biznet.Trade} trade - the trade to be processed
    * @transaction
    */
   function tradeCommodity(trade) {

       // set the new owner of the commodity
       trade.commodity.owner = trade.newOwner;
       return getAssetRegistry('org.acme.biznet.Commodity')
           .then(function (assetRegistry) {

               // emit a notification that a trade has occurred
               var tradeNotification = getFactory().newEvent('org.acme.biznet', 'TradeNotification');
               tradeNotification.commodity = trade.commodity;
               emit(tradeNotification);

               // persist the state of the commodity
               return assetRegistry.update(trade.commodity);
           });
   }

   /**
    * Remove all high volume commodities
    * @param {org.acme.biznet.RemoveHighQuantityCommodities} remove - the remove to be processed
    * @transaction
    */
   function removeHighQuantityCommodities(remove) {

       return getAssetRegistry('org.acme.biznet.Commodity')
           .then(function (assetRegistry) {
               return query('selectCommoditiesWithHighQuantity')
                       .then(function (results) {

                           var promises = [];

                           for (var n = 0; n < results.length; n++) {
                               var trade = results[n];

                               // emit a notification that a trade was removed
                               var removeNotification = getFactory().newEvent('org.acme.biznet', 'RemoveNotification');
                               removeNotification.commodity = trade;
                               emit(removeNotification);

                               // remove the commodity
                               promises.push(assetRegistry.remove(trade));
                           }

                           // we have to return all the promises
                           return Promise.all(promises);
                       });
           });
   }

3、保存你的更改到logic.js。

第一个函数tradeCommodity将在收到的Trade交易时更改商品（用一个新的拥有者参与者）的拥有者属性，并发出通知事件。然后，将修改后的商品(Commodity)保存回用于存储商品实例的资产库中。

第二个函数调用一个名为“selectCommoditiesWithHighQuantity”（在queries.qry中定义）的查询，它将返回数量大于60的所有商品资产记录; 发出一个事件; 并从AssetRegistry(资产库)中移除商品。

第二步：创建一个查询定义文件

交易处理器逻辑使用的查询被定义在一个叫做queries.qry的文件中。每个查询条目定义执行查询的资源和条件。

1、在tutorial-network目录中，创建一个名为queries.qry的新文件。
2、将以下代码复制并粘贴到queries.qry：

   /** Sample queries for Commodity Trading business network
   */

   query selectCommodities {
     description: "Select all commodities"
     statement:
         SELECT org.acme.biznet.Commodity
   }

   query selectCommoditiesByExchange {
     description: "Select all commodities based on their main exchange"
     statement:
         SELECT org.acme.biznet.Commodity
             WHERE (mainExchange==_$exchange)
   }

   query selectCommoditiesByOwner {
     description: "Select all commodities based on their owner"
     statement:
         SELECT org.acme.biznet.Commodity
             WHERE (owner == _$owner)
   }

   query selectCommoditiesWithHighQuantity {
     description: "Select commodities based on quantity"
     statement:
         SELECT org.acme.biznet.Commodity
             WHERE (quantity > 60)
   }

3、保存你的更改到queries.qry。

第三步：重新生成你的业务网络档案

在更改业务网络中的文件后，业务网络必须重新打包为业务网络档案（.bna），并重新部署到Hyperledger Fabric实例。

1、使用命令行，导航到tutorial-network目录。
2、运行以下命令：

   composer archive create --sourceType dir --sourceName . -a tutorial-network@0.0.1.bna

第四步：部署更新的业务网络定义

我们需要部署修改后的网络，成为区块链上的最新版本！我们正在使用新创建的业务网络档案文件来更新现有的已部署业务网络; 这是我们在开发者教程中使用的同一个业务网络名称。

1、切换到终端，将目录切换到包含tutorial-network.bna的文件夹。
2、运行以下命令更新业务网络：

   composer network update -a tutorial-network@0.0.1.bna -c admin@tutorial-network

3、运行以下命令测试网络是否已部署：

   composer network ping -c admin@tutorial-network

第五步：为更新后的业务网络重新生成REST API

现在，我们把刚更新的业务网络与添加的查询集成在一起，并为这个业务网络暴露REST API。

1、使用命令行，导航到tutorial-network目录。
2、使用以下命令启动REST服务器：

   composer-rest-server

3、输入admin@tutorial-network作为卡片名称。
4、当询问是否在生成的API中使用名称空间时，请选择不使用名称空间。
5、当询问是否保护生成的API时选择否。
6、当询问是否启用事件发布时，选择是。
7、当询问是否启用TLS安全时，请选择否。

第六步：测试REST API并创建一些数据

打开Web浏览器并导航到http：//localhost:3000/explorer。你应该看到LoopBack API浏览器，允许你查看和测试生成的REST API。

我们应该能够看到被添加了名为“Query”的REST端点，并且在展开时显示了业务网络 tutorial-network中定义的REST查询操作列表

作为REST端点公开的查询

在开始之前，我们需要创建一些数据，以充分展示查询。使用提供的示例JSON数据，使用REST API创建3个交易者（参与者）和更多商品（资产）。

1、首先，在REST Explorer中点击’Trader’，然后点击/Trader上的’POST’方法，然后向下滚动到Parameter部分 - 依次创建下面的Trader实例：

   {
     "$class": "org.acme.biznet.Trader",
     "tradeId": "TRADER1",
     "firstName": "Jenny",
     "lastName": "Jones"
   }

2、点击“Try it out”来创建参与者。“Response Code”（向下滚动）应该是200（成功）
3、通过复制以下JSON创建另一个交易者：

   {
     "$class": "org.acme.biznet.Trader",
     "tradeId": "TRADER2",
     "firstName": "Jack",
     "lastName": "Sock"
   }

4、通过复制以下JSON创建第三个交易者：

   {
     "$class": "org.acme.biznet.Trader",
     "tradeId": "TRADER3",
     "firstName": "Rainer",
     "lastName": "Valens"
   }

5、现在滚动到顶部，并在REST浏览器中点击“Commodity”对象。
6、点击POST操作，并向下滚动到Parameters 部分：以上述相同的方式，为拥有者TRADER1和TRADER2创建两个商品资产记录（见下文）：

{
  "$class": "org.acme.biznet.Commodity",
  "tradingSymbol": "EMA",
  "description": "Corn",
  "mainExchange": "EURONEXT",
  "quantity": 10,
  "owner": "resource:org.acme.biznet.Trader#TRADER1"
}

{
  "$class": "org.acme.biznet.Commodity",
  "tradingSymbol": "CC",
  "description": "Cocoa",
  "mainExchange": "ICE",
  "quantity": 80,
  "owner": "resource:org.acme.biznet.Trader#TRADER2"
}