Generare una raccolta Postman mediante l'interfaccia CLI

È possibile utilizzare il comando generate per creare una raccolta Postman che include payload di esempio per tutte le API del controller concatenato.

Postman è uno strumento che è possibile utilizzare per utilizzare e testare le API REST. Il comando generate crea una raccolta Postman basata sul codice concatenato generato automaticamente da un file di specifica dichiarativa. L'insieme Postman contiene i payload per tutti i metodi specificati nel file controller del codice concatenato. È possibile modificare i valori delle variabili nel file di raccolta Postman per effettuare chiamate API REST.

La raccolta Postman generata include valori predefiniti per tutte le API nel controller. Per ulteriori informazioni su Postman, vedere https://www.postman.com/. Dopo aver generato una raccolta Postman, è possibile importarla direttamente e utilizzarla modificando i valori predefiniti nel payload e nelle variabili.

Uso:

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.

Per generare una raccolta Postman, passare alla directory che contiene il progetto, quindi immettere il comando seguente. È necessario eseguire il comando generate dalla directory chaincode oppure si verificherà un errore. Se la raccolta Postman specificata esiste già, viene richiesto se sovrascriverla. 

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

Struttura raccolta postman

La raccolta Postman generata include due tipi di richieste, le richieste di richiamo e le richieste di query:
  • Le richieste di richiamo includono tutte le operazioni di scrittura, che utilizzano l'endpoint /transactions
  • Le richieste di query includono tutte le operazioni get, che utilizzano l'endpoint /chaincode-queries

Per distinguere tra metodi getter e non-getter nelle API del controller, un decoratore viene utilizzato nei codici concatenati TypeScript e un commento viene utilizzato nei codici concatenati Go. Se si definisce un metodo getter nel controller, è necessario utilizzare il decoratore GetMethod per TypeScript o il commento GetMethod per Go, come mostrato nella tabella seguente.

TypeScript Vai
Ogni metodo getter ha un decoratore GetMethod:
@GetMethod()
@Validator()
public async getAllTokenAdmins() {
  await this.Ctx.ERC1155Auth.checkAuthorization("ERC1155ADMIN.getAllAdmins", "TOKEN");
  return await this.Ctx.ERC1155Admin.getAllAdmins();
}
 Ogni metodo getter ha un blocco di commento GetMethod:
/**
 * 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()
}

Le raccolte Postman generate includono variabili con valori predefiniti, come mostrato nella tabella seguente.

Nome variabile Descrizione Valore predefinito Contesto
bc-url URL proxy REST dell'istanza di Oracle Blockchain Platform in cui viene distribuito il codice concatenato https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy tutti i codici concatenati
bc-channel Il canale in cui viene distribuito il codice concatenato default tutti i codici concatenati
bc-admin-user Il nome dell'amministratore (un utente con il ruolo admin che può accedere a tutte le richieste POST). Per impostazione predefinita, questo utente è il chiamante di tutte le richieste POST nel codice concatenato bc-admin-user value tutti i codici concatenati
bc-admin-password La password per l'utente amministratore bc-admin-password value tutti i codici concatenati
bc-timeout Valore di timeout nel corpo di ogni richiesta POST per indicare l'intervallo di timeout 6000 tutti i codici concatenati
bc-sync Valore di sincronizzazione nel corpo di ogni richiesta POST per indicare se la richiesta è sincrona o asincrona true tutti i codici concatenati
bc-chaincode-name Il nome del codice concatenato, utilizzato in ogni richiesta POST chaincode name tutti i codici concatenati
bc-org-id Parametro orgId predefinito per tutte le richieste POST bc-org-id value solo codici concatenati del token
bc-user-id Parametro userId predefinito per tutte le richieste POST bc-user-id value solo codici concatenati del token
bc-token-id Parametro tokenId predefinito per tutte le richieste POST bc-token-id value solo codici concatenati del token

In ogni richiesta generata vengono generati tutti i parametri con valori predefiniti. Le funzioni con parametri di struttura/classe avranno un oggetto segnaposto nel corpo della richiesta, come mostrato negli esempi seguenti.

API con un parametro struct/class 
{
    "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 senza un parametro struct/class 
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "CreateAccount",
        "{{bc-org-id}}",
        "example_minter",
        "true",
        "true"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}

Il valore predefinito per la maggior parte dei parametri API è parameter_name value, con alcune eccezioni. Gli esempi riportati di seguito mostrano alcune eccezioni.

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

Una struttura o una classe ha valori predefiniti diversi, come illustrato nella tabella riportata di seguito.

Tipo di dati Valore predefinito
boolean/bool true
int/number 999
date 2022-01-16T15:16:36+00:00
other parameter_name value

Progetti token ERC-1155

Lo standard ERC-1155 include metodi comuni per token sia fungibili che non fungibili. La raccolta Postman generata per un progetto ERC-1155 che utilizza token sia fungibili che non fungibili include due diverse richieste POST, una per ogni tipo di token, per questi metodi comuni. Se un progetto ERC-1155 utilizza solo token fungibili o non fungibili ma non entrambi i tipi, la raccolta Postman generata include solo una richiesta POST per questi metodi comuni. La tabella seguente illustra l'API generata per il metodo AddRole.
Elemento richiesta Token fungibili Token non fungibili
Nome richiesta AddRole -For Fungible AddRole -For NonFungible
Corpo richiesta 
{
    "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}}
}