Postman-Sammlung mit der CLI generieren

Mit dem Befehl generate können Sie eine Postman-Collection erstellen, die Beispiel-Payloads für alle Chaincode-Controller-APIs enthält.

Postman ist ein Tool, mit dem Sie REST-APIs verwenden und testen können. Der Generierungsbefehl erstellt eine Postman-Collection, die auf dem Chaincode basiert, der automatisch aus einer deklarativen Spezifikationsdatei generiert wurde. Die Postman-Collection enthält die Payloads für alle Methoden, die in der Chaincode-Controllerdatei angegeben sind. Sie können die Variablenwerte in der Postman-Collection-Datei ändern, um REST-API-Aufrufe vorzunehmen.

Die generierte Postman-Collection enthält Standardwerte für alle APIs im Controller. Weitere Informationen zu Postman finden Sie unter https://www.postman.com/. Nachdem Sie eine Postman-Collection generiert haben, können Sie sie direkt importieren und verwenden, indem Sie die Standardwerte in der Payload und den Variablen ändern.

Die Oracle Blockchain Platform Digital Assets Edition umfasst Unterstützung für Bestätigungsparameter in generierten Postman-Sammlungen. Weitere Informationen finden Sie unter Verbesserungen an Postman Collections.

Verwendung:

generate [options]
ochain generate -h 
Usage: generate [options]

Generates the postman collection for the chaincode. 

Options :
    -h, --help              output command usage information
    -D, --debug             enable debug logging
    -c, --collection        This option is mandatory to generate a Postman collection.
    -p, --project <path>    Path to the chaincode project to generate the Postman collection from. If not specified, it defaults to current directory.
    -o, --out <path>        Path to the generated Postman collection JSON file. If not specified, it defaults to current directory.

Um eine Postman-Sammlung zu generieren, navigieren Sie in das Verzeichnis, das das Projekt enthält, und geben Sie den folgenden Befehl ein. Sie müssen den Befehl generate aus dem Chaincode-Verzeichnis ausführen, da sonst ein Fehler auftritt. Wenn die angegebene Postman-Sammlung bereits vorhanden ist, werden Sie aufgefordert, sie zu überschreiben. 

ochain generate --collection --project path_to_chaincode_project --out path_to_postman_collection_to_generate

Postman-Sammlungsstruktur

Die generierte Postman-Collection umfasst zwei Typen von Anforderungen, Aufrufs und Abfrageanforderungen:
  • Aufrufanforderungen umfassen alle Schreibvorgänge, die den Endpunkt /transactions verwenden
  • Abfrageanforderungen umfassen alle get-Vorgänge, die den Endpunkt verwenden /chaincode-queries

Um zwischen Getter- und Nicht-getter-Methoden in den Controller-APIs zu unterscheiden, wird ein Decorator in TypeScript-Kettencodes und ein Kommentar in Go-Kettencodes verwendet. Wenn Sie eine Getter-Methode im Controller definieren, müssen Sie den Decorator GetMethod für TypeScript oder den Kommentar GetMethod für Go verwenden, wie in der folgenden Tabelle dargestellt.

TypeScript Los
Jede Getter-Methode hat einen GetMethod-Dekorator:
@GetMethod()
@Validator()
public async getAllTokenAdmins() {
  await this.Ctx.ERC1155Auth.checkAuthorization("ERC1155ADMIN.getAllAdmins", "TOKEN");
  return await this.Ctx.ERC1155Admin.getAllAdmins();
}
 Jede Getter-Methode hat einen GetMethod-Kommentarblock:
/**
 * GetMethod
 */
func (t *Controller) GetAllTokenAdmins() (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Admin.GetAllAdmins", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.Ctx.Admin.GetAllTokenAdmins()
}

Generierte Postman-Collections enthalten Variablen mit Standardwerten, wie in der folgenden Tabelle dargestellt.

Variablenname Beschreibung Standardwert Kontext
bc-url Die REST-Proxy-URL der Oracle Blockchain Platform-Instanz, in der der Chaincode bereitgestellt wird https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy alle Chaincodes
bc-channel Der Kanal, in dem der Chaincode bereitgestellt wird default alle Chaincodes
bc-admin-user Der Name des Administrators (ein Benutzer mit der Rolle admin, der auf alle POST-Anforderungen zugreifen kann). Standardmäßig ist dieser Benutzer der Aufrufer aller POST-Anforderungen im Chaincode bc-admin-user value alle Chaincodes
bc-admin-password Das Kennwort für den Administratorbenutzer bc-admin-password value alle Chaincodes
bc-timeout Der Timeoutwert im Body jeder POST-Anforderung zur Angabe des Timeoutintervalls 6000 alle Chaincodes
bc-sync Der Synchronisierungswert im Hauptteil jeder POST-Anforderung, der angibt, ob die Anforderung synchron oder asynchron ist true alle Chaincodes
bc-chaincode-name Der Chaincode-Name, der in jeder POST-Anforderung verwendet wird chaincode name alle Chaincodes
bc-org-id Der Standardparameter orgId für alle POST-Anforderungen bc-org-id value Nur Token Chaincodes
bc-user-id Der Standardparameter userId für alle POST-Anforderungen bc-user-id value Nur Token Chaincodes
bc-token-id Der Standardparameter tokenId für alle POST-Anforderungen bc-token-id value Nur Token Chaincodes

In jeder generierten Anforderung werden alle Parameter mit Standardwerten generiert. Funktionen mit Struktur-/Klassenparametern haben ein Platzhalterobjekt im Anforderungsbody, wie in den folgenden Beispielen gezeigt.

API mit einem Struktur-/Klassenparameter 
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "CreateArtCollectionToken",
        "{\"TokenId\":\"{{bc-token-id}}\",\"TokenDesc\":\"TokenDesc value\",\"TokenUri\":\"TokenUri value\",\"TokenMetadata\":{\"Painting_name\":\"Painting_name value\",\"Description\":\"Description value\",\"Image\":\"Image value\",\"Painter_name\":\"Painter_name value\"},\"Price\":999,\"On_sale_flag\":true}",
        "quantity value"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}
API ohne Struktur-/Klassenparameter 
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "CreateAccount",
        "{{bc-org-id}}",
        "example_minter",
        "true",
        "true"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}

Der Standardwert für die meisten API-Parameter ist parameter_name value, mit einigen Ausnahmen. Die folgenden Beispiele zeigen einige der Ausnahmen.

  • Der Filterparameter in GetAccountTransactionHistoryWithFilters: 
    "{\"PageSize\":20,\"Bookmark\":\"\",\"StartTime\":\"2022-01-16T15:16:36+00:00\",\"EndTime\":\"2022-01-17T15:16:36+00:00\"}"
  • Der Filterparameter in GetSubTransactionsByIdWithFilters:
    "{\"PageSize\":20,\"Bookmark\":\"\}"

Eine Struktur oder Klasse hat andere Standardwerte, wie in der folgenden Tabelle dargestellt:

Datentyp Standardwert
boolean/bool true
int/number 999
date 2022-01-16T15:16:36+00:00
other parameter_name value

ERC-1155 Token-Projekte

Der ERC-1155-Standard umfasst gängige Methoden für fungible und nicht fungible Token. Die generierte Postman-Sammlung für ein ERC-1155-Projekt, das sowohl fungible als auch nicht fungible Token verwendet, umfasst zwei verschiedene POST-Anforderungen, eine für jeden Tokentyp, für diese gemeinsamen Methoden. Wenn ein ERC-1155-Projekt nur fungible oder nicht fungible Token, aber nicht beide Typen verwendet, enthält die generierte Postman-Sammlung nur eine POST-Anforderung für diese allgemeinen Methoden. In der folgenden Tabelle wird die generierte API für die Methode AddRole dargestellt.
Anforderungselement Fungible Token Nicht-Fungible Token
Anforderungsname AddRole -For Fungible AddRole -For NonFungible
Anforderungsbody 
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "AddRole",
        "{{bc-org-id}}",
        "{{bc-user-id}}",
        "role value (for example, minter / burner)",
        "{\"TokenId\":\"{{bc-token-id}}\"}"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}
 
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "AddRole",
        "{{bc-org-id}}",
        "{{bc-user-id}}",
        "role value (for example, minter / burner)",
        "{\"TokenName\":\"TokenName value\"}"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}