輸入規格檔案

Blockchain App Builder 初始化命令會讀取輸入規格檔案並產生鷹架式專案，其中包含可協助鏈碼開發流程的工具。

在規格檔案中，您可以指定多個資產定義和行為、CRUD 和非 CRUD 方法宣告、自訂方法、引數驗證、自動封送處理 (Marshall) / 取消封送處理 (unmarshalling)、通透保存功能，以及使用 SQL SELECT 敘述句或 CouchDB 查詢語言完成豐富資料查詢的功能。這些功能會為您產生。

如需有關指定權杖資產的資訊，請參閱下列主題：
規格檔案可以 YAML 或 JSON 格式寫入。您可以在 Blockchain App Builder 套件下載中看到兩種格式的範例規格檔案：
  • Fabcar-Typescript.yml
  • Marbles-Go.yml

附註：

根據 Go 慣例，匯出的名稱以大寫字母開頭。因此，規格檔案中的所有資產特性和方法名稱都必須以大寫字母為開頭。

規格檔案的結構

一般而言，您會以下列方式建構規格檔案：

assets: 
    name:
    type:
    properties:
        name:
        type:
        id:
        derived:
           strategy:
           algorithm:
           format:
        mandatory:
        default:
        validate:
    methods:
        crud:
        others:
customMethods:

除了沒有指定類型的一般資產之外，Blockchain App Builder 還支援兩種特殊資產類型：內嵌資產和權杖資產。特殊資產定義為規格檔案之 assets: 區段下的 type: embedded 或 type: token。

表格 3-2 規格檔案參數描述與範例

進入 描述 範例
assets:

此特性接受資產的定義和行為。您可以定義多個資產。

  
name:

資產的名稱。

下列為保留名稱。請勿將這些名稱用於資產。
  • account
  • role
  • hold
  • token
  • authorization
  • tokenAdmin
  • Account
  • Role
  • Hold
  • Token
  • Authorization
  • TokenAdmin
 
name: owner # Information about the owner
type:

資產型態

支援下列特殊資產類型：
  • embedded
  • token

如果您未在 assets 區段中指定 type 參數，則資產為一般類型。

 
type:

類型：內嵌

如果此特性設為 embedded，則會將資產定義為內嵌資產。內嵌資產沒有 CRUD 方法，而且必須是要儲存在分類帳中另一個資產的一部分。

在範例中，特性 address 是內嵌的，定義在另一個資產中。

內嵌資產不支援循環參考。例如，在上一個範例中，address 資產不能包含 employee 資產的參照。

資產：employee
name: employee
  properties:
     name: employeeId
     type: string
     mandatory: true
     id: true

     name: firstName
     type: string
     validate: max(30)
     mandatory: true

     name: lastName
     type: string
     validate: max(30)
     mandatory: true

     name: age
     type: number
     validate: positive(),min(18)

     name: address
     type: address
資產：address
name: address

type: embedded

properties:
   name: street
   type: string

   name: city
   type: string

   name: state
   type: string

   name: country
   type: string
properties:

描述資產的所有物業。

  
name:

特性的名稱。

 
name: ownerId # Unique ID for each owner
id:
  • true

這會指定此資產的 ID。此為必要屬性。

 
name: owner            # Information about the owner
properties:
     name: ownerId    # Unique ID for each owner
     type: string
     mandatory: true
     id: true
     name: name        # Name of the owner
     type: string
     mandatory: true
type:

財產類型

支援下列基本特性類型：
  • number
  • float
  • string
  • boolean
  • date
  • array
對於 Go 鏈碼，number 會對應至 int，float 會對應至 float64。目前不支援其他類型，包括下列類型：
  • complex
  • unsigned/signed int
  • 8/16/32/64 bits
 
name: year        # Model year
                    type: number
                    mandatory: true
                    validate: min(1910),max(2020)
                    name: color       # Color - no validation as color names are innumerable
                    type: string
                    mandatory: true
derived:

此特性指定 ID 特性衍生自其他索引鍵。相依特性必須是 string 資料類型，而不是內嵌資產。

此特性有兩個必要參數：
  • strategy：接受 concat 或 hash 的值。
  • format：接受要由策略使用的規格字串和值陣列。
範例 1：
  • 特性 employeeID 與 firstName 和 lastName 特性相依。
  • 此特性是 format 陣列中所列值的串連。
  • IND%1#%2%tIND 是陣列中的第 0 個索引，並描述最終格式。
  • %n 是一個位置指定元，可從陣列中的其他索引取得其值。
  • %t 表示此值為來自通道標頭的 stub.timestamp 值。
  • 如果您需要使用 format 字串中的百分比符號 (%)，則必須使用其他百分比符號 (%) 來遁離。
  • 此範例中的最終格式為：INDfirstName#lastName1606885454916IND
範例 2：
  • 使用 hash 時，您也必須使用 algorithm 參數。預設值為 sha256；也支援 md5。
  • IND%1#%2%t 是陣列中的第 0 個索引，並描述最終格式。
  • %n 是一個位置指定元，可從陣列中的其他索引取得其值。
  • %t 表示此值為來自通道標頭的 stub.timestamp 值。
  • 如果您需要使用 format 字串中的百分比符號 (%)，則必須使用其他百分比符號 (%) 來遁離。
範例 1
name: employee
  properties:
     name: employeeId
     type: string
     mandatory: true
     id: true
     derived:
         strategy: concat
         format: ["IND%1#%2%tIND","firstName","lastName"]

     name: firstName
     type: string
     validate: max(30)
     mandatory: true

     name: lastName
     type: string
     validate: max(30)
     mandatory: true

     name: age
     type: number
     validate: positive(),min(18)
範例 2
name: account
  properties:
     name: accountId
     type: string
     mandatory: true
     id: true
     derived:
         strategy: hash
         algorithm: 'sha256'
         format: ["IND%1#%2%t","bankName","ifsccode"]

     name: bankName
     type: string
     validate: max(30)
     mandatory: true

     name: ifsccode
     type: string
     mandatory: true
mandatory:
  • true
  • false

對應的特性為必要項目，無法在建立資產時略過。

 
name: phone       # Phone number - validate as (ddd)-ddd-dddd where dashes could also be periods or spaces
type: string
mandatory: true
validate: /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/
name: cars        # The list of car VINs owned by this owner
type: string[]
mandatory: false
default:

此屬性的預設值。

  
validate:

指定的特性會根據區塊鏈 App 產生器提供的部分立即可用驗證進行驗證。如果確定鏈結有效，您可以鏈結驗證。

如果未提供 validate 特性，則只會針對特性 type 進行驗證。

 
validate:

類型：數字
  • 正 ()
  • 負 ()
  • min()
  • max()

這些驗證可以鏈結在一起，並以逗號分隔。 

name: offerApplied
type: number
validate: negative(),min(-4)
name: year  # Model year
type: number
mandatory: true
validate: min(1910),max(2020)
validate:

類型：字串
  • min()
  • max()
  • email()
  • url()
  • /regex/ 支援 PHP 正規表示式

對於 Go 鏈碼，必須正確遁離包含特定保留字元或空格字元的正規表示式。

 
name: website 
type: string
mandatory: false
validate: url()
name: phone  # Phone number - validate as (ddd)-ddd-dddd where dashes could also be periods or spaces
type: string
mandatory: true
validate: /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/
name: Color #Color can be red, blue, or green
type: string
mandatory: true
validate: /^\\s*(red|blue|green)\\s*$/
validate:

類型：布林值
  • true
  • false

在範例中，特性 active 的驗證是依據類型本身 (boolean) 

name: active
type: boolean
validate:

類型：陣列

依類型本身，格式為 type: number[]，表示陣列的類型為 number。

您可以使用 number[1:5] 格式來輸入陣列的限制，這表示長度下限為 1，上限為 5。您可以省略其中一項。 

name: items
type: number[:5]
validate:

類型：日期
  • min()
  • max()
日期必須為下列其中一種格式：
  • YYYY-MM-DD
  • YYYY-MM-DDTHH:MM:SSZ，其中 T 會將日期與時間分隔，而 Z 則表示 UTC。時區偏移量可以取代 Z，如 -05:00 中央日光節約時間。 
name: expiryDate
type: date
validate: max('2020-06-26')
name: completionDate
type: date
validate: min('2020-06-26T02:30:55Z')
methods:

使用此功能來說明要產生的 CRUD (建立 / 讀取 / 更新 / 刪除) 或其他方法。

預設會產生所有 CRUD 和其他方法。

 
methods:
    crud: [create, getById, update, delete]
    others: [getHistoryById, getByRange]
crud:
  • create
  • getByID (讀取)
  • update
  • delete

如果此陣列保留空白，將不會建立 CRUD 方法。

如果未指定 crud 參數，預設會建立四個方法。

crud 參數不適用於 token 和 embedded 資產。 

methods:
    crud: [create, getById, delete]
    others: [] # no other methods will be created
others:
  • getHistoryById
  • getByRange

getHistoryById 會傳回清單中資產的歷史記錄。

getByRange 會傳回指定範圍內的所有資產。如需詳細資訊，請參閱 "getByRange" (TypeScript) 和 "GetByRange" (執行)。

如果這個陣列保留空白，則不會建立其他方法。

如果完全未使用 others 參數，則預設會建立這兩個方法。

others 參數不適用於 token 和 embedded 資產。 

methods:
    crud: [create, delete]
    others: [] # no other methods will be created
      methods:
        crud: [create, getById, update, delete]
        others: [getHistoryById, getByRange]
customMethods:

此特性會在主控制器檔案中建立不可呼叫的自訂方法樣板。它會採用方法簽章，並在控制器檔案中建立函數宣告。

您可以在這裡提供語言特有的函數宣告。

系統會提供名為 executeQuery 的自訂方法。如果將此方法新增至規格檔案，它會詳細說明如何執行 Berkeley DB SQL 和 CouchDB RTF 查詢。只有當您連線至 Oracle Blockchain Platform Cloud 或 Enterprise Edition 時，才能呼叫此方法。

TypeScript

customMethods:
    - executeQuery
    - "buyCar(vin: string, buyerId: string, sellerId: string, price: number, date: Date)"
    - "addCar(vin: string, dealerId: string, price: number, date: Date)"

移至

customMethods:
    - executeQuery
    - "BuyCar(vin string, buyerId string, sellerId string, price int)"
    - "AddCar(vin string, dealerId string, price int)"