Postman Collectionsの機能改善

Oracle Blockchain Platform Digital Assets Editionは、ブロックチェーン・アプリケーション・ビルダーによって生成されたPostmanコレクションに、エンドースメント・パラメータ、機密チェーンコードおよびOAuth 2.0のサポートを追加します。

ブロックチェーン・アプリケーション・ビルダーを使用すると、すべてのチェーンコード・コントローラAPIのペイロード例を含むPostmanコレクションを作成できます。詳細は、CLIを使用したPostmanコレクションの生成およびVisual Studio Codeを使用したPostmanコレクションの生成を参照してください。

Oracle Blockchain Platform Digital Assets Editionは、すべてのセッター・メソッドのリクエスト・ペイロードに追加パラメータを含めることで、その機能を拡張します。(機密モードではなく)汎用チェーンコードの場合、パラメータはendorsersまたはsameOrgEndorserです。sameOrgEndorserパラメータ(trueの場合)は、トランザクション・エンドースメントがリクエスタと同じ組織に属している必要があることを示します。endorsersパラメータは、トランザクションを承認する必要があるピアのリストを指定します。

チェーンコードの.ochain.jsonファイルのsameOrgEndorserOptionInWrapperAPIパラメータは、sameOrgEndorser値を必要とするAPIを指定します。sameOrgEndorserOptionInWrapperAPIパラメータに関連付けられたAPIのペイロードでは、sameOrgEndorserパラメータがtrueに設定されます。その他のすべてのAPIには、sameOrgEndorserパラメータのかわりにendorsersパラメータが含まれます。

次のスニペットは、卸売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オブジェクトに引数を渡します。activateAccountメソッドの次の例に示すように、一時マップのargsパラメータで引数を直接渡すことができます。

"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のサポート

デフォルトでは、ブロックチェーン・アプリケーション・ビルダーによって生成されたPostmanコレクションは、OAuth 2.0認可用に構成されます。OAuth 2.0を有効にするには、Postmanコレクションのグローバル変数に次の値を指定する必要があります。

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`	Oracle Blockchain PlatformインスタンスのドメインのOAuth 2.0トークン・エンドポイント。	`access-token-url`値
`access_token`	`bc-admin`またはカスタム・ユーザーに対して生成されたOAuth 2.0アクセス・トークン。	最初は利用できません。スクリプトによって管理されます。
`access_token_expiry`	生成されたアクセス・トークンの有効期限。	最初は利用できません。スクリプトによって管理されます。
`admin_credentials_hash`	トークンの検証および再生成に使用される資格証明のハッシュ値。	最初は利用できません。スクリプトによって管理されます。