ラッパーAPIのデプロイ

Oracle Blockchain Platform Digital Assets Editionでは、ブロックチェーン・アプリケーション・ビルダーによって生成されたチェーンコード内のすべてのコントローラAPIのラッパーAPIを生成できます。ラッパーAPIパッケージをスタック・リソース・マネージャにデプロイし、関連付けられたPostmanコレクションを使用してラッパーAPIをテストするには、次のステップを実行します。

ブロックチェーン・アプリケーション・ビルダーを使用してラッパーAPIパッケージを生成すると、選択したディレクトリにデフォルトのネーミング規則を使用して2つのファイルが作成されます:

  • <ChaincodeName>WrapperAPI.zip: Oracle Cloud Infrastructure (OCI) Resource ManagerにラッパーAPIをデプロイするために必要なTerraformスクリプトを含むアーカイブ・ファイル。
  • <ChaincodeName>_WrapperAPI.postman_collection.json: デプロイメント後にラッパーAPIをテストするために使用されるPostmanコレクション。

ラッパーAPIをデプロイするには、WrapperAPI.zipファイルを使用してOCI Resource Managerにスタックを作成します。

ラッパーAPIパッケージをデプロイするには、次の前提条件を満たす必要があります。

  • ラッパーAPIパッケージは、ブロックチェーン・アプリケーション・ビルダーを使用して生成する必要があります。
  • パッケージには、ラッパーAPIに必要なすべての構成変数値およびエンドポイント値が含まれている必要があります。
  1. OCIにログインします
    OCIコンソールを開いてサインインします: https://cloud.oracle.com/。スタックがデプロイされるコンパートメントにいることを確認します。
  2. 「ナビゲーション」メニューを展開します。「開発者サービス」を選択します。「リソース・マネージャ」で、「スタック」を選択します。
    スタックのリソース・マネージャ・インタフェースが開きます。Terraform構成を使用して、既存のスタックを表示し、スタックを作成し、インフラストラクチャをコードとして管理できます。
  3. 「スタックの作成」をクリックします。
  4. スタック情報を構成します。
    1. 「Terraform構成」セクションで、「自分の構成」を選択します。
    2. 「スタック構成」の「Terraform構成ソース」で、.Zipファイルを選択します。
    3. 「参照」をクリックし、ラッパーAPIの.zipファイルに移動します。
    4. .zipファイルがアップロードされたら、スタック名が正しいことを確認します。
    5. 「Terraformバージョン」ドロップダウン・リストで、v1.2以上を選択します。デフォルトでは、Resource Managerは最新バージョンを使用します。v1.2 より前のバージョンを選択すると、デプロイメントは失敗します。
    6. 残りのすべての設定をデフォルトとして保持できます。「次へ」をクリックしてください。
  5. スタック変数を構成します。
    1. すべての構成変数の値が正確であり、デプロイメントの要件を満たすようにラッパーAPIパッケージで指定された構成変数と一致していることを確認します。
    2. ocir_user_nameに、OCIアカウントに関連付けられた電子メール・アドレスを入力します。
    3. ocir_user_passwordに、OCI認証トークンであるパスワードを入力します。このトークンは、OCIコンソールのプロファイルまたはユーザー設定セクションで生成できます。認証トークンは、Oracle Cloud Infrastructure Registryにログインするためのパスワードとして機能します。
      認証トークンの生成の詳細は、認証トークンの生成を参照してください。
    4. 残りのすべての設定をデフォルトとして保持できます。「次へ」をクリックしてください。
  6. スタック情報を確認します。すべてが正しいことを確認したら、「作成」をクリックします。
  7. Terraformプランを実行します。
    1. スタックの「詳細」ページで、「計画」をクリックして実行計画の作成を開始します。
    2. 必要に応じて、ジョブ計画を構成します。デフォルト名を編集したり、拡張オプションを選択してプロバイダのバージョンを変更したり、設定を調整したりできます。
    3. 「プラン」をクリックして、プラン・ジョブを作成して実行します。
      Terraform構成が解析され、実行計画が生成されて実行されるため、次のタスクが完了します。
      • Terraformスクリプトを検証して、構文エラーや構成エラーがないことを確認します。
      • 実際のインフラストラクチャを変更せずに、リソース作成プロセスをシミュレートします。
      • スクリプトが作成、変更または破棄するリソースをリストする出力サマリーを提供します。
    4. スタックの「ジョブ」セクションでステータスをモニターします。計画が正常に完了したら、出力を確認して作成されるリソースの数を確認し、問題がないことを確認します。
  8. Terraformプランをスタックに適用します。
    1. スタックの「詳細」ページで、「適用」をクリックします。
    2. 「Terraform Apply」パネルで、「Apply」をクリックします。
      Terraformプランを適用すると、次のタスクが完了します:
      • Terraformスクリプトで定義されている次のリソースをすべてプロビジョニングします:
        • 仮想クラウド・ネットワーク(VCN)
        • アプリケーション(OCI関数)
        • APIゲートウェイ
        • APIデプロイメント
        • IAMポリシー
        • OCIレジストリ・リポジトリ
      • ラッパーAPIに必要なすべてのインフラストラクチャを作成します。
    3. スタックの「ジョブ」セクションでステータスをモニターし、ジョブがエラーなしで正常に完了していることを確認します。
  9. APIゲートウェイ・エンドポイントを取得します。
    1. 適用ジョブが完了したら、「適用ジョブ」ページの「出力」セクションに移動して、生成された出力値を表示します。
    2. 出力は、キーがエンドポイント名を表し、値が対応するエンドポイント値であるJSONオブジェクトを返します。
      api_gateway_endpoints{"api_gateway_endpoint":"https://grqkdiwsugp3fp2m5z3zgpo4.apigateway.ap-mumbai-1.oci.customer-oci.com/WholesaleCBDC"}
    3. エンドポイントをコピーします。API Postmanコレクションを更新するには、エンドポイントが必要です。
Postmanを使用したラッパーAPIのテスト

Postmanを使用してラッパーAPIをテストできます。適切な値を割り当てて、ラッパーAPI Postmanコレクション内のすべての変数を構成します。動的に生成されたゲートウェイ・エンドポイントが提供されるOCIのスタック・デプロイメントの出力からapi_gateway_endpoint値を取得します。

Postmanコレクションの変数が更新されたら、ラッパーAPIをテストできます。コレクション内の各APIリクエストには、対応するラッパーAPIに固有の必要なペイロードが含まれます。

図4-1 Postmanを使用したAPIラッパー・コレクションのテスト


イメージは、生成されたゲートウェイAPIを使用してコレクションからAPIを実行しているPostmanを示しています。

ラッパーAPIをデプロイおよび使用する際の問題のトラブルシューティングには、次の情報を使用できます。

Unauthorized: ocir_user_nameまたはocir_user_passwordが無効です。
このエラーは、ユーザー名またはパスワード資格証明のいずれかが正しくない場合に発生します。この問題を解決するには、次のステップを実行します。
  1. スタックの「詳細」ページの「変数」セクションにナビゲートします。
  2. 「変数の編集」をクリックして、ユーザー名とパスワードの値を変更します。
  3. 正しい情報で資格証明を更新します。
  4. 「適用」をクリックしてスタックを再デプロイします。
Deployment Failure - "denied: Anonymous users are only allowed read access on public repos"
デプロイメントが次のエラーで失敗することがあります。
denied: Anonymous users are only allowed read access on public repos

これは、スタックのバックエンドのDocker操作に関連する断続的な問題です。具体的には、Dockerイメージを適切な認証なしでOracle Cloud Infrastructure Registryにプッシュしようとすると、このエラーが発生します。

ラッパーAPIパッケージには、イメージをプッシュする前に適切な認証を確保するためにdocker loginコマンドを実行するスクリプトが含まれていますが、このエラーは散発的に発生する可能性があります。通常は、イメージ・プッシュ時にDocker認証ステップがシステムによって正しく認識されない場合に発生します。

このエラーが発生した場合は、これらの手順に従って問題を解決してください。

  1. OCI Stack Resource Managerで「破棄」をクリックして、デプロイメント・プロセス中に作成されたすべてのリソースを破棄します。
  2. リソースが破棄されたら、「適用」を再度クリックしてスタックを再デプロイします。これにより、適切なDocker認証を含む必要なリソースの作成がトリガーされます。
一般的なデプロイメントの失敗: 断続的な問題
スタック・デプロイメントは、Dockerに関連するランダムな問題のために失敗することがあります。これを行った場合には、以下の手順を実施して問題を解決します:
  1. 「破棄」をクリックして、失敗したデプロイメント中に作成されたすべてのリソースを削除します。
  2. リソースが破棄されたら、スタックに戻り、「適用」をクリックしてスタックを再デプロイします。

これにより、断続的な問題を解決し、デプロイメントを成功させることができます。