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は、すべてのsetterメソッドのリクエスト・ペイロードに追加パラメータを含めることで、その機能を拡張します。汎用チェーンコード(機密モードではなく)の場合、パラメータは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を取得します:

  1. Oracle Cloud Infrastructure (OCI)アカウントへのサインイン。Oracle Blockchain Platformインスタンスを含むコンパートメントを選択します。
  2. コンソールで、「ナビゲーション」メニューをクリックし、「アイデンティティおよびセキュリティ」をクリックします。
  3. 「アイデンティティ」で、「ドメイン」を選択します。
  4. 「ドメイン」ページで、「Oracle Identity Cloud Service」をクリックします。
  5. Oracle Identity Cloud Serviceのナビゲーション・メニューで、「Oracle Cloud Services」を選択します。Oracle Blockchain Platformインスタンスを見つけて、そのインスタンスの詳細ページを開きます。
  6. 表示されるデフォルト・ページは、OAuth構成ページです。「クライアントID」および「クライアント・シークレット」フィールドは、「一般情報」セクションにあります。
  7. 「ドメイン」ページに戻り、Oracle Blockchain Platformインスタンスで使用されるドメインをクリックします。
  8. ドメインURLがドメインの詳細に表示されます。

これらのグローバル変数は、access_tokenプレースホルダを生成するためにリクエスト前スクリプトで使用されます。このスクリプトは、bc-adminユーザーのトークンを生成し、すべてのリクエストがbc-admin認可で実行されるようにします。

最初のリクエストは、指定された資格証明を使用してbc-adminトークンを生成します。トークンと有効期限の値は、Postmanコレクション変数に格納されます。欠落または期限切れのトークンは自動的に再生成されます。クライアントIDまたはクライアント・シークレットが変更された場合、スクリプトは自動的に変更を検出し、前のトークンを無効にして、更新された資格証明を含むトークンを生成します。access_token値を手動で変更すると、リクエストが失敗する可能性があります。access_token値をクリアすると、スクリプトによって別のbc-adminトークンが自動的に生成されます。

PostmanコレクションのGenerate Access Token for Userリクエストを使用して、デフォルトのbc-adminトークン以外のトークンを生成して使用できます。カスタム・アクセス・トークンを生成するには、次のステップを実行します。

  1. 「ユーザーのアクセス・トークンの生成」リクエストを開きます。デフォルトでは、usernameおよびpasswordの値はbc-adminに設定されています。
  2. コレクション変数のusernameおよびpassword値を更新します。
  3. 「Generate New Access Token」をクリックします。「アクセス・トークンの管理」ウィンドウが開きます。
  4. デフォルト名を更新し、その他の詳細を確認して、「保存」をクリックします。トークンが使用可能になり、「認可」ページの「使用可能なトークン」セクションに表示されます。

生成された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 トークンの検証および再生成に使用される資格証明のハッシュ値。 最初は使用できません。スクリプトによって管理されます