Postman 收帐增强功能

Oracle Blockchain Platform Digital Assets Edition 为 Blockchain App Builder 生成的 Postman 集合增加了对背书参数、机密链代码和 OAuth 2.0 的支持。

Blockchain App Builder 允许您创建 Postman 集合，其中包含所有链代码控制器 API 的示例有效负载。有关更多信息，请参见 Generate a Postman Collection Using the CLI 和 Generate a Postman Collection Using Visual Studio Code 。

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 参数通过在请求有效负载中使用瞬态映射来传递。这可确保参数保持机密性，并且不会在日志中公开。有关机密链代码的更多信息，请参见 Confidential Payments Overview 。

所有 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 集合配置为 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 值。
单击 Generate New Access Token 。此时将打开管理访问令牌窗口。
更新默认名称，查看其他详细信息，然后单击保存。该令牌现在可供使用，并显示在授权页面上的可用令牌部分中。

生成的 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`	用于标记验证和重新生成的身份证明的散列值。	初始不可用；由脚本管理