Postman Collect 的增強功能

Oracle Blockchain Platform Digital Assets Edition 為 Blockchain App Builder 產生的 Postman Collection 新增了背書參數、機密鏈碼和 OAuth 2.0 的支援。

Blockchain App Builder 可讓您建立 Postman 集合，其中包括所有鏈碼控制器 API 的有效負載範例。如需詳細資訊，請參閱使用 CLI 產生 Postman Collection 和使用 Visual Studio Code 產生 Postman Collection 。

Oracle Blockchain Platform Digital Assets Edition 透過在所有 Setter 方法的要求有效負載中包含額外的參數來擴充該功能。對於一般 (與機密模式相反) 鏈碼，參數為 endorsers 或 sameOrgEndorser。sameOrgEndorser 參數 (若為 true) 表示交易背書必須來自與要求者相同的組織。endorsers 參數會指定必須為交易背書的對等清單。

鏈碼中 .ochain.json 檔案的 sameOrgEndorserOptionInWrapperAPI 參數指定哪些 API 需要 sameOrgEndorser 值。與 sameOrgEndorserOptionInWrapperAPI 參數相關聯的 API 其有效負載中的 sameOrgEndorser 參數設為 true。所有其他 API 都包含 endorsers 參數，而非 sameOrgEndorser 參數。

下列程式碼片段顯示批發 CBDC 鏈碼套件中 .ochain.json 檔案中的 sameOrgEndorserOptionInWrapperAPI 參數。

"sameOrgEndorserOptionInWrapperAPI": ["addConversionRate","addTokenAdmin","addTokenAuditor","approveBurn","approveMint","burnTokens","createExchangePoolAccounts","deleteHistoricalTransactions","initializeCBDCToken","initializeExchangePoolUser","issueTokens","mintWithFundingExchangePool","rejectBurn","rejectMint","removeTokenAdmin","removeTokenAuditor","requestBurn","requestMint","updateCBDCToken","updateConversionRate"]

您可以視需要自訂此參數。產生包裝函式 API 時，指定的 API 在其有效負載中將 sameOrgEndorser 參數設為 true。

下列有效負載範例顯示這些背書參數。

addOrgAdmin

{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "addOrgAdmin",
        "{{bc-org-id}}",
        "{{bc-user-id}}"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}},
    "endorsers": {{endorsers}}
}

addTokenAdmin

{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "addTokenAdmin",
        "{{bc-org-id}}",
        "{{bc-user-id}}"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}},
    "sameOrgEndorser": true
}

機密鏈碼支援

在機密模式中產生的鏈碼處理與一般模式不同的參數。在機密鏈碼中，會使用要求有效負載中的暫時對應傳送 API 引數。這可確保引數保持機密，且不會顯示在日誌中。如需機密鏈碼的詳細資訊，請參閱機密付款簡介。

所有 getter 方法都包含 peer 參數 (不在一般模式鏈碼中)。

所有 setter 方法都包含 endorsers 參數，此參數指定必須為交易背書的對等清單。.ochain.json 檔案中的 sameOrgEndorserOptionInWrapperAPI 參數設為空白陣列：

"sameOrgEndorserOptionInWrapperAPI": []

Setter 方法需要一個 Confidential-Transaction 標頭，代表從 Oracle Blockchain Platform 執行處理擷取機密交易所需的連結因子。Postman 對機密交易的要求中需有此標頭。

為了維護機密模式鏈碼的安全性，請傳送 transientMap 物件中的引數。您可以直接在暫時對應中的 args 參數中傳送引數，如下列 activateAccount 方法範例所示：

"transientMap": { "args": "[\"account_id value\"]" }

對於僅限包裝函式 API Postman 集合 (不是一般的 Postman 集合)，您也可以使用 transientMapArgsFlag 旗標，如果設為 true，就會自動將所有引數傳遞至暫時對應，如下列 activateAccount 方法範例所示：

{
   "accountId": "account_id value",
   "transientMapArgsFlag": true
}

下列 Postman 要求範例會顯示這些參數和標頭。

createAccount (setter 方法)

curl --location 'https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy/api/v2/channels/default/transactions' \
--header 'Content-Type: application/json' \
--header 'Confidential-Transaction: true' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "activateAccount"
    ],
    "timeout": 6000,
    "sync": true,
    "endorsers": ["org1-xyz-abc.blockchain.ocp.oraclecloud.com:20009", "org2-xyz-abc.blockchain.ocp.oraclecloud.com:20009"],
    "transientMap": {
        "args": "[\"account_id value\"]"
    }
}'

getAllActiveAccounts (getter 方法)

curl --location 'https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy/api/v2/channels/default/chaincode-queries' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "getAllActiveAccounts"
    ],
    "timeout": 6000,
    "sync": true,
    "peer": "org-xyz-abc.blockchain.ocp.oraclecloud.com:20009",
    "transientMap": {
        "args": "[\"bc-org-id value\",\"bc-token-id value\"]"
    }
}'

OAuth 2.0 支援

依照預設，Blockchain App Builder 產生的 Postman Collection 設定為 OAuth 2.0 授權。您必須在 Postman 集合的全域變數中提供下列值，才能啟用 OAuth 2.0。

client-id: Oracle Blockchain Platform 執行處理的用戶端 ID。
client-secret: Oracle Blockchain Platform 執行處理的用戶端密碼。
access-token-url: 存取權杖 URL 包含 Oracle Blockchain Platform 執行處理的網域 URL，格式如下：https://<domain-URL>/oauth2/v1/token

完成下列步驟，以擷取 Oracle Blockchain Platform 執行處理的用戶端 ID、用戶端密碼及網域 URL：

登入您的 Oracle Cloud Infrastructure (OCI) 帳戶。選取包含 Oracle Blockchain Platform 執行處理的區間。
在主控台中，按一下導覽功能表，然後按一下識別與安全。
在識別下，選取網域。
在網域頁面中，按一下 Oracle Identity Cloud Service 。
在 Oracle Identity Cloud Service 導覽功能表中，選取 Oracle Cloud Services 。尋找您的 Oracle Blockchain Platform 執行處理，然後開啟該執行處理的詳細資訊頁面。
顯示的預設頁面為 OAuth 組態頁面。「用戶端 ID」和「用戶端密碼」欄位位於「一般資訊」區段中。
回瀏覽至網域頁面，然後按一下 Oracle Blockchain Platform 執行處理所使用的網域。
網域 URL 會顯示在網域詳細資訊中。

這些全域變數用於要求前命令檔，以產生 access_token 預留位置。命令檔會產生 bc-admin 使用者的記號，讓每個要求都以 bc-admin 授權執行。

第一個要求會使用指定的證明資料產生 bc-admin 記號。記號與到期值會儲存在 Postman 集合變數中。系統會自動重新產生遺漏或過期的記號。如果用戶端 ID 或用戶端密碼變更，則程序檔會自動偵測出變更、使先前的記號無效，並以更新的憑證產生記號。如果您手動修改 access_token 值，可能會導致要求失敗。如果清除 access_token 值，命令檔會自動產生另一個 bc-admin 記號。

您可以使用 Postman 集合中的產生使用者的存取權杖要求，產生並使用預設 bc-admin 權杖以外的權杖。若要產生自訂存取權杖，請完成下列步驟。

開啟產生使用者的存取權杖要求。依預設，username 和 password 值會設為 bc-admin。
更新收集變數中的 username 和 password 值。
按一下產生新存取權杖。管理存取權杖視窗便會開啟。
更新預設名稱、複查其他詳細資訊，然後按一下儲存。記號現已可供使用，並顯示在授權頁面的可用的記號段落中。

產生的 Postman 集合包括 OAuth 2.0 支援所需的變數，如下表所示。

變數	描述	預設值
`client-id`	Oracle Blockchain Platform 執行處理的用戶端 ID。	`client-id` 值
`client-secret`	Oracle Blockchain Platform 執行處理的用戶端密碼。	`client-secret` 值
`access-token-url`	OAuth Oracle Blockchain Platform 執行處理網域的 2.0 記號端點。	`access-token-url` 值
`access_token`	為 `bc-admin` 或自訂使用者產生的 OAuth 2.0 存取權杖。	一開始無法使用；由指令碼管理
`access_token_expiry`	所產生存取權杖的到期時間。	一開始無法使用；由指令碼管理
`admin_credentials_hash`	用於權杖驗證和重新產生的證明資料雜湊值。	一開始無法使用；由指令碼管理