使用 CLI 產生 Postman Collection

您可以使用 generate 命令來建立 Postman 集合，其中包含所有鏈碼控制器 API 的有效負載範例。

Postman 是可用來處理和測試 REST API 的工具。產生命令會根據從宣告式規格檔案自動產生的鏈碼，建立 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 集合，請瀏覽至包含該專案的目錄，然後輸入下列指令。您必須從 chaincode 目錄執行 generate 命令，否則將會發生錯誤。如果指定的 Postman 集合已存在，系統會提示您是否要加以覆寫。 

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

Postman Collection 結構

產生的 Postman 集合包括兩種類型的要求，呼叫要求和查詢要求：
  • 呼叫要求包括使用 /transactions 端點的所有寫入作業
  • 查詢要求包括使用 /chaincode-queries 端點的所有 get 作業

為了區分控制器 API 中的 getter 和非 getter 方法，TypeScript 鏈碼中使用了修飾器，並在 Go 鏈碼中使用註解。如果您在控制器中定義 getter 方法，則必須使用 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 僅限記號鏈碼

在每一個產生的要求中，都會產生含有預設值的所有參數。具有結構 / 類別參數的函數在要求主體中會有一個預留位置物件，如下列範例所示。

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}}
}
不含結構 / 類別參數的 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 集合，同時使用有趣與不可行的記號，包括兩個不同的 POST 要求，每個記號類型各有一個用於這些通用方法。如果 ERC-1155 專案只使用有趣或非有趣的記號，但不是兩種類型，則產生的 Postman 集合只會包含一個 POST 要求供這些一般方法使用。下表說明為 AddRole 方法產生的 API。
要求元素 有趣的代幣 非真偽令牌
要求名稱 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}}
}