Eingabespezifikationsdatei

Der Initialisierungsbefehl Blockchain App Builder liest die Eingabespezifikationsdatei und generiert das gerüstete Projekt, das Tools zur Unterstützung des Chaincode-Entwicklungsprozesses enthält.

In der Spezifikationsdatei können Sie mehrere Assetdefinitionen und -verhalten, CRUD- und Nicht-CRUD-Methodendeklaration, benutzerdefinierte Methoden, Validierung von Argumenten, Auto-Marshalling/Unmarshalling, transparente Persistenzfunktion und die Möglichkeit angeben, Rich-Data-Abfragen mit SQL SELECT-Anweisungen oder der Abfragesprache CouchDB abzuschließen. Diese Funktionen werden für Sie generiert.

Informationen zum Angeben von Tokenassets finden Sie in den folgenden Themen:
Die Spezifikationsdatei kann im YAML- oder JSON-Format geschrieben werden. Beispielspezifikationsdateien werden in beiden Formaten im Paketdownload von Blockchain App Builder angezeigt:
  • Fabcar-Typescript.yml
  • Marbles-Go.yml

Hinweis:

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

Struktur der Spezifikationsdatei

Normalerweise 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 speziellen Assets sind als type: embedded oder type: token im Abschnitt assets: der Spezifikationsdatei definiert.

Tabelle 3-2: Beschreibungen und Beispiele für Spezifikationsdateiparameter

Eintrag Beschreibung Beispiele
assets:

Diese Eigenschaft übernimmt die Definition und das Verhalten des Assets. Sie können mehrere Anlagen definieren.

  
name:

Der Name der Anlage.

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:

Vermögensgegenstandstypen

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

Wenn Sie keinen Parameter type im Abschnitt assets 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, um im Buch gespeichert zu werden.

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

Eingebettete Assets unterstützen keine Zirkelreferenzen. 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:

Beschreibt alle Eigenschaften eines Assets.

  
name:

Der Name der Eigenschaft.

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

Gibt die ID dieses Assets an. Diese Eigenschaft ist erforderlich.

 
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:

Eigenschaftstypen

Die folgenden grundlegenden Eigenschaftstypen werden unterstützt:
  • number
  • float
  • string
  • boolean
  • date
  • array
Bei Go-Chaincodes wird number int zugeordnet, und float float64. 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 ist. Abhängige Eigenschaften müssen den Datentyp string und kein eingebettetes Asset aufweisen.

Diese Eigenschaft hat zwei obligatorische Parameter:
  • strategy: Nimmt die Werte concat oder hash an.
  • format: nimmt ein Array von Spezifikationszeichenfolgen und -werten an, die von der Strategie verwendet werden sollen.
Beispiel 1:
  • Die Eigenschaft employeeID ist von den Eigenschaften firstName und lastName abhängig.
  • Diese Eigenschaft ist eine Verkettung der Werte, die im Array format aufgeführt sind.
  • IND%1#%2%tIND ist der 0. Index im Array und beschreibt das endgültige Format.
  • %n ist ein Positionsbezeichner, der seine Werte aus den anderen Indizes im Array übernimmt.
  • %t gibt an, dass der Wert der stub.timestamp-Wert aus dem Kanalheader ist.
  • Wenn Sie das Prozentzeichen (%) in der Zeichenfolge format verwenden müssen, muss es mit einem anderen Prozentzeichen (%) 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 ein Positionsbezeichner, der seine Werte aus den anderen Indizes im Array übernimmt.
  • %t gibt an, dass der Wert der stub.timestamp-Wert aus dem Kanalheader ist.
  • Wenn Sie das Prozentzeichen (%) in der Zeichenfolge format verwenden müssen, muss es mit einem anderen Prozentzeichen (%) 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:

Der Standardwert dieser Eigenschaft.

  
validate:

Die angegebene Eigenschaft wird anhand einiger der einsatzbereiten Validierungen validiert, die von Blockchain App Builder bereitgestellt werden. Sie können Validierungen ketten, 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: Nummer
  • positiv()
  • negativ()
  • min()
  • max()

Diese Validierungen können durch Kommas getrennt miteinander 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: String
  • min()
  • max()
  • email()
  • url()
  • /regex/ unterstützt PHP-Regex

Bei Go-Kettencodes müssen reguläre Ausdrücke, die bestimmte reservierte Zeichen oder Leerzeichen enthalten, ordnungsgemäß maskiert 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: boolesch
  • true
  • false

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

name: active
type: boolean
validate:

Typ: Array

Durch den Typ selbst in Form von type: number[] wird vermittelt, dass das Array den Typ number aufweist.

Sie können Limits für das Array im Format number[1:5] eingeben. Das bedeutet, dass die Mindestlänge 1 ist und das Maximum 5 ist. Sie können eine davon auslassen. 

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

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

Verwenden Sie diese Option, um anzugeben, welche der CRUD-Methoden (Erstellen/Lesen/Aktualisieren/Löschen) oder zusätzliche Methoden generiert werden sollen.

Standardmäßig werden alle CRUD- und anderen Methoden generiert.

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

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

Wenn der Parameter crud nicht angegeben ist, werden standardmäßig alle vier Methoden erstellt.

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

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" (Go).

Wenn dieses Array leer bleibt, werden keine anderen Methoden erstellt.

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

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

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

Diese Eigenschaft erstellt aufrufbare benutzerdefinierte Methodenvorlagen in der Hauptcontrollerdatei. Es nimmt die Methodensignatur und erstellt die Funktionsdeklaration in der Controller-Datei.

Hier können Sie sprachspezifische Funktionsdeklarationen angeben.

Eine benutzerdefinierte Methode namens executeQuery wird bereitgestellt. Wenn Sie diese Methode zur Spezifikationsdatei hinzufügen, wird beschrieben, wie Berkeley DB SQL- und CouchDB Rich-Abfragen 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)"