CLIを使用したPostmanコレクションの生成

generateコマンドを使用して、すべてのチェーンコード・コントローラAPIのペイロードの例を含むPostmanコレクションを作成できます。

Postmanは、REST APIの操作およびテストに使用できるツールです。generateコマンドは、宣言仕様ファイルから自動的に生成されたチェーンコードに基づくPostmanコレクションを作成します。Postmanコレクションには、チェーンコードコントローラファイルで指定されたすべてのメソッドのペイロードが含まれます。Postmanコレクション・ファイルの変数値を変更して、REST APIコールを行うことができます。

生成されたPostmanコレクションには、コントローラ内のすべてのAPIのデフォルト値が含まれています。Postmanの詳細は、https://www.postman.com/を参照してください。Postmanコレクションを生成した後、ペイロードおよび変数のデフォルト値を変更することで、そのコレクションを直接インポートして使用できます。

使用方法:

generate [options]
my-mac:TsProject myname$ 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.

Postmanコレクションを生成するには、プロジェクトを含むディレクトリに移動し、次のコマンドを入力します。チェーンコード・ディレクトリからgenerateコマンドを実行する必要があります。実行しないと、エラーが発生します。指定したPostmanコレクションがすでに存在する場合は、上書きするかどうかを確認するプロンプトが表示されます。 

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

Postmanコレクション構造

生成されたPostmanコレクションには、呼出しリクエストと問合せリクエストの2つのタイプのリクエストが含まれます。
  • 呼出しリクエストには、エンドポイント/transactionsを使用するすべての書込み操作が含まれます
  • 問合せリクエストには、エンドポイント/chaincode-queriesを使用するすべてのget操作が含まれます。

コントローラAPIのgetterメソッドとgetter以外のメソッドを区別するために、TypeScriptチェーンコードでデコレータが使用され、Goチェーンコードでコメントが使用されます。コントローラでゲッター・メソッドを定義する場合は、次の表に示すように、TypeScriptにGetMethodデコレータを使用するか、GoにGetMethodコメントを使用する必要があります。

TypeScript 移動
すべてのgetterメソッドには、GetMethodデコレータがあります。
@GetMethod()
@Validator()
public async getAllTokenAdmins() {
  await this.Ctx.ERC1155Auth.checkAuthorization("ERC1155ADMIN.getAllAdmins", "TOKEN");
  return await this.Ctx.ERC1155Admin.getAllAdmins();
}
 すべてのgetterメソッドには、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()
}

次の表に示すように、生成されたPostmanコレクションにはデフォルト値を持つ変数が含まれます。

変数名 説明 デフォルト値 コンテキスト
bc-url チェーンコードがデプロイされているOracle Blockchain PlatformインスタンスのRESTプロキシURL https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy すべてのチェーンコード
bc-channel チェーンコードがデプロイされるチャネル default すべてのチェーンコード
bc-admin-user 管理ユーザーの名前(すべてのPOSTリクエストにアクセスできる管理ロールを持つユーザー)。デフォルトでは、このユーザーはチェーンコード内のすべてのPOSTリクエストのコール元です bc-admin-user value すべてのチェーンコード
bc-admin-password 管理ユーザーのパスワードです。 bc-admin-password value すべてのチェーンコード
bc-timeout タイムアウト間隔を示すすべてのPOSTリクエストの本文のタイムアウト値 6000 すべてのチェーンコード
bc-sync すべてのPOSTリクエストの本文の同期値。リクエストが同期か非同期かを示します。 true すべてのチェーンコード
bc-chaincode-name チェーンコード名。すべてのPOSTリクエストで使用されます。 chaincode name すべてのチェーンコード
bc-org-id すべてのPOSTリクエストに対するデフォルトのorgIdパラメータ bc-org-id value トークンチェーンコードのみ
bc-user-id すべてのPOSTリクエストに対するデフォルトのuserIdパラメータ bc-user-id value トークンチェーンコードのみ
bc-token-id すべてのPOSTリクエストに対するデフォルトのtokenIdパラメータ bc-token-id value トークンチェーンコードのみ

生成されたすべてのリクエストで、デフォルト値を持つすべてのパラメータが生成されます。構造体/クラスのパラメータを持つ関数は、次の例に示すように、リクエスト本文にプレースホルダ・オブジェクトを持ちます。

struct/classパラメータを持つAPI 
{
    "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}}
}
struct/classパラメータのないAPI 
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "CreateAccount",
        "{{bc-org-id}}",
        "example_minter",
        "true",
        "true"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}

ほとんどのAPIパラメータのデフォルト値はparameter_name valueですが、例外もあります。次の例は、いくつかの例外を示しています。

  • GetAccountTransactionHistoryWithFiltersのfiltersパラメータ: 
    "{\"PageSize\":20,\"Bookmark\":\"\",\"StartTime\":\"2022-01-16T15:16:36+00:00\",\"EndTime\":\"2022-01-17T15:16:36+00:00\"}"
  • GetSubTransactionsByIdWithFiltersのfiltersパラメータ:
    "{\"PageSize\":20,\"Bookmark\":\"\}"

構造体またはクラスには、次の表に示すように異なるデフォルト値があります。

データ・タイプ デフォルト値
boolean/bool true
int/number 999
date 2022-01-16T15:16:36+00:00
other parameter_name value

ERC-1155トークンプロジェクト

ERC-1155規格には、真菌性トークンと非真菌性トークンの両方の共通メソッドが含まれています。真菌性トークンと非真菌性トークンの両方を使用するERC-1155プロジェクト用に生成されたPostmanコレクションには、これらの共通メソッドについて、トークンのタイプごとに1つずつ、2つの異なるPOSTリクエストが含まれています。ERC-1155プロジェクトが、真菌性トークンまたは非真菌性トークンのみを使用し、両方の型を使用しない場合、生成されたPostmanコレクションには、これらの共通メソッドに対するPOSTリクエストが1つのみ含まれます。次の表に、AddRoleメソッド用に生成されたAPIを示します。
要求要素 Fungibleトークン 無菌トークン
リクエスト名 AddRole -For Fungible AddRole -For NonFungible
リクエスト本体 
{
    "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}}
}