使用 CLI 產生 Postman Collection

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

Postman 是一種可以用來處理和測試 REST API 的工具。產生命令會根據從宣告式規格檔案自動產生的鏈碼，建立 Postman 集合。Postman 集合包含鏈碼控制器檔案中指定之所有方法的有效負載。您可以變更 Postman 集合檔案中的變數值，以進行 REST API 呼叫。

產生的 Postman 集合包括控制器中所有 API 的預設值。若要進一步瞭解 Postman，請參閱 https://www.postman.com/ 。產生 Postman 集合之後，您可以直接匯入它，然後藉由變更有效負載和變數中的預設值來使用它。

用法：

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.

若要產生 Postman 集合，請瀏覽至包含專案的目錄，然後輸入下列命令。您必須從鏈碼目錄執行 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 要求之 admin 角色的使用者)。依照預設，此使用者是鏈碼中所有 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 中的篩選參數： 
    "{\"PageSize\":20,\"Bookmark\":\"\",\"StartTime\":\"2022-01-16T15:16:36+00:00\",\"EndTime\":\"2022-01-17T15:16:36+00:00\"}"
  • GetSubTransactionsByIdWithFilters 中的篩選參數：
    "{\"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}}
}