Eingabespezifikationsdatei

Der Initialisierungsbefehl Blockchain App Builder liest die Eingabespezifikationsdatei und generiert das gerüstete Projekt mit mehreren Tools, um den Chaincode-Entwicklungsprozess zu unterstützen.

Mit der Spezifikationsdatei können Sie mehrere Assetdefinitionen und -verhalten, CRUD- und Nicht-CRUD-Methodendeklaration, benutzerdefinierte Methoden, Validierung von Argumenten, automatisches Marshalling/Unmarshalling, transparente Persistenzfunktion und das Aufrufen von Rich Data-Abfragen mit SQL SELECTs oder CouchDB Query Language angeben. Diese Funktionen werden für Sie generiert.

Informationen zum Angeben von Tokenassets finden Sie in den folgenden Themen:
Die Spezifikationsdatei kann in yaml oder json geschrieben werden. Beispielspezifikationsdateien in beiden Formaten finden Sie im Download des Blockchain App Builder-Pakets:
  • Fabcar-Typescript.yml
  • Marbles-Go.yml

Hinweis:

Gemäß den Go-Konventionen beginnen exportierte Namen mit einem Großbuchstaben. Daher müssen alle Asset-Eigenschaften und -Methoden Namen aufweisen, die mit Großbuchstaben in der Spezifikationsdatei beginnen.

Struktur der Spezifikationsdatei

In der Regel strukturieren Sie eine Spezifikationsdatei wie folgt:

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

Blockchain App Builder unterstützt zwei spezielle Assettypen, eingebettete Assets und Tokenassets, zusätzlich zu generischen Assets ohne angegebenen Typ. Die Sondervermögensgegenstände werden als type: embedded oder type: token im Abschnitt assets: der Spezifikationsdatei definiert.

Tabelle 7-2: Beschreibung und Beispiele für Parameter der Spezifikationsdatei

Eintrag Beschreibung Beispiele
assets:

Diese Eigenschaft übernimmt die Definition und das Verhalten des Assets. Hier können Sie mehrere Assetdefinitionen angeben.

  
name:

Der Name des Assets.

Die folgenden Namen sind reserviert. Verwenden Sie diese Namen nicht für Assets.
  • account
  • role
  • hold
  • token
  • authorization
  • tokenAdmin
  • Account
  • Role
  • Hold
  • Token
  • Authorization
  • TokenAdmin
 
name: owner # Information about the owner
type:

Assettypen

Die folgenden speziellen Assettypen werden unterstützt:
  • embedded
  • token

Wenn Sie im Abschnitt assets keinen Parameter type angeben, weist das Asset den generischen Typ auf.

 
type:

Typ: eingebettet

Wenn diese Eigenschaft auf embedded gesetzt ist, wird das Asset als eingebettetes Asset definiert. Eingebettete Anlagen haben keine CRUD-Methoden und müssen Teil einer anderen Anlage sein, die im Buch gespeichert werden soll.

Im Beispiel ist die Eigenschaft address eingebettet und in einem anderen Asset definiert.

Eingebettete Assets unterstützen keine Zirkelbezüge. Beispiel: Im vorherigen Beispiel darf das Asset address keine Referenz auf das Asset employee enthalten.

Anlage: 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
Anlage: address
name: address

type: embedded

properties:
   name: street
   type: string

   name: city
   type: string

   name: state
   type: string

   name: country
   type: string
properties:

Beschreiben Sie alle Eigenschaften eines Assets.

  
name:

Der Name der Eigenschaft.

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

Gibt die ID dieses Vermögensgegenstands an. Diese Eigenschaft ist obligatorisch.

 
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:

Eigenschaftentypen

Die folgenden grundlegenden Eigenschaftstypen werden unterstützt:
  • number
  • float
  • string
  • boolean
  • date
  • array
Bei Go-Chaincodes ist number int zugeordnet, und float ist float64 zugeordnet. Andere Typen werden derzeit nicht unterstützt, einschließlich der folgenden Typen:
  • 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:

Diese Eigenschaft gibt an, dass die ID-Eigenschaft von anderen Schlüsseln abgeleitet wird. Abhängige Eigenschaften müssen den Datentyp string und kein eingebettetes Asset aufweisen.

Diese Eigenschaft hat zwei obligatorische Parameter:
  • strategy: Übernimmt Werte von concat oder hash.
  • format: Übernimmt ein Array von Spezifikationszeichenfolgen und -werten, die von der Strategie verwendet werden sollen.
Beispiel 1:
  • Die Eigenschaft employeeID hängt von den Eigenschaften firstName und lastName ab.
  • Diese Eigenschaft ist eine Verkettung der im Array format aufgeführten Werte.
  • IND%1#%2%tIND ist der 0. Index im Array und beschreibt das endgültige Format.
  • %n ist eine Positionsspezifikation, die ihre Werte aus den anderen Indizes im Array übernimmt.
  • %t gibt an, dass der Wert aus dem Kanalheader stub.timestamp lauten muss.
  • Wenn Sie das Zeichen % in der Zeichenfolge format verwenden müssen, muss es mit einer anderen % maskiert werden.
  • Das endgültige Format in diesem Beispiel lautet: INDfirstName#lastName1606885454916IND
Beispiel 2:
  • Wenn Sie hash verwenden, müssen Sie auch den Parameter algorithm verwenden. Der Standardwert ist sha256; md5 wird ebenfalls unterstützt.
  • IND%1#%2%t ist der 0. Index im Array und beschreibt das endgültige Format.
  • %n ist eine Positionsspezifikation, die ihre Werte aus den anderen Indizes im Array übernimmt.
  • %t gibt an, dass der Wert aus dem Kanalheader stub.timestamp lauten muss.
  • Wenn Sie das Zeichen % in der Zeichenfolge format verwenden müssen, muss es mit einer anderen % maskiert werden.
Beispiel 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)
Beispiel 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

Die entsprechende Eigenschaft ist erforderlich und kann beim Erstellen einer Anlage nicht übersprungen werden.

 
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:

Dadurch erhalten Sie den Standardwert dieser Eigenschaft.

  
validate:

Die angegebene Eigenschaft wird anhand einiger Out-of-Box-Validierungen validiert, die von Blockchain App Builder bereitgestellt werden. Sie können Validierungen verketten, wenn Sie sicherstellen, dass die Kette gültig ist.

Wenn die Eigenschaft validate nicht angegeben ist, wird die Validierung nur für die Eigenschaft type ausgeführt.

 
validate:

Typ: Zahl
  • positiv()
  • negativ()
  • Minuten()
  • max()

Diese Validierungen können durch Komma getrennt verkettet werden. 

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

Typ: Zeichenfolge
  • min()
  • max()
  • email()
  • url()
  • /regex/ - unterstützt den regulären PHP-Ausdruck

Bei Go-Kettencodes müssen reguläre Ausdrücke, die bestimmte reservierte Zeichen oder Leerzeichen enthalten, ordnungsgemäß mit Escapezeichen versehen werden.

 
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:

Typ: boolean
  • true
  • false

Im Beispiel erfolgt die Validierung der Eigenschaft active nach dem Typ selbst (boolean). 

name: active
type: boolean
validate:

Typ: Array

Der Typ selbst in Form von type: number[] gibt an, dass das Array vom Typ "Zahl" ist.

Sie können Limits für das Array im Format number[1:5] eingeben. Das bedeutet, dass die Mindestlänge 1, die Höchstlänge 5 beträgt. Wird einer davon vermieden, wird nur min/max berücksichtigt. 

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

Typ: Datum
  • min()
  • max()
Das Datum muss eines der folgenden Formate aufweisen:
  • YYYY-MM-DD
  • YYYY-MM-DDTHH:MM:SSZ, wobei T das Datum von der Uhrzeit trennt und Z UTC angibt. Zeitzonenverschiebungen können Z in -05:00 für die zentrale Sommerzeit ersetzen. 
name: expiryDate
type: date
validate: max('2020-06-26')
name: completionDate
type: date
validate: min('2020-06-26T02:30:55Z')
methods:

Geben Sie hiermit an, welche der CRUD-Methoden (Create/Read/Update/Delete) oder zusätzliche Methoden generiert werden sollen.

Wenn nichts eingegeben wird, werden standardmäßig alle CRUD- und andere Methoden generiert.

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

Wenn dieses Array leer gelassen wird, werden keine CRUD-Methoden erstellt.

Wenn der Parameter crud überhaupt nicht verwendet wird, werden standardmäßig alle vier Methoden erstellt.

Der Parameter crud gilt nicht für token- und embedded-Assets. 

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

getHistoryById gibt die Historie des Assets in einer Liste zurück.

getByRange gibt alle Assets in einem bestimmten Bereich zurück. Weitere Informationen finden Sie unter "getByRange" (TypeScript) und "GetByRange" (Los).

Wenn dieses Array leer gelassen wird, werden keine anderen Methoden erstellt.

Wenn der Parameter others überhaupt nicht verwendet wird, werden standardmäßig beide Methoden erstellt.

Der Parameter others gilt nicht für token- und embedded-Assets. 

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

Diese Eigenschaft erstellt in der Hauptcontrollerdatei unbrauchbare benutzerdefinierte Methodenvorlagen. Er nimmt die Methodensignatur und erstellt die Funktionsdeklaration in der Controllerdatei.

Hier können Sie sprachspezifische Funktionsdeklarationen angeben.

Wir stellen eine benutzerdefinierte Methode mit dem Namen executeQuery bereit. Wenn sie der Spezifikationsdatei hinzugefügt wird, wird beschrieben, wie Berkeley DB SQL- und CouchDB Rich Queries ausgeführt werden können. Diese Methode kann nur aufgerufen werden, wenn Sie mit Oracle Blockchain Platform Cloud oder Enterprise Edition verbunden sind.

TypeScript

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

Los

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