API の設計と編集

このページの内容は ApigeeApigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

このページの手順に沿って、Cloud Code を使用して API を設計、編集します。

Gemini Code Assist を使用して API を設計する

Cloud Code を使用すると、Gemini Code Assist を使用して OpenAPI 仕様(OAS)バージョン 3.0 API を設計できます。Gemini Code Assist は、API 開発プロセスで生成 AI アシスタント用の企業コンテキストを含めることができます。エンタープライズ コンテキストは、新しい API の生成時にプロジェクトの API Hub API をコンテキストとして使用します。API Hub を使用するプロジェクトでのみ使用できます。

このセクションの機能を使用する設定手順については、Gemini Code Assist を使用するをご覧ください。

API を生成する手順は次のとおりです。

  1. 左側のナビゲーションにある魔法の杖をクリックして、Gemini Code Assist を使用して新しい API 仕様を作成します。API 仕様を作成する際にすべての機能がサポートされているわけではないため、Gemini Code Assist チャットではなく、この方法を使用して API 仕様を作成してください。
    Cloud Code Gemini Code Assist による仕様の作成の魔法の杖
  2. [Create an API spec] 入力ウィンドウに、新しい API を説明するプロンプトを入力します。
    1. 必要に応じて、表示されるテンプレート チップからプロンプト テンプレートを選択します。プロンプト テンプレートは、プロンプトのフレームワークを提供して、プロンプトの作成を支援します。
    2. プロンプトを入力します。効果的な API 仕様プロンプトの作成方法をご覧ください。

      Cloud Code Gemini Code Assist プロンプト
  3. Gemini Code Assist は、API を定義する OAS を生成します。
  4. 仕様を確認します。
    1. [View code] をクリックして、コードエディタで仕様を確認します。
    2. API レンダラパネルには、API の説明やその他のドキュメントなど、デベロッパーが表示できるのと同じように API のプレビューが表示されます。
    3. API Hub に API がすでに存在する場合、そのエンタープライズ コンテキストを使用して、他の API からこの OAS にオブジェクトが再利用されます。これは、OUTPUT パネルに列挙されます。
      Cloud Code Gemini Code Assist で生成された仕様
    4. 皆様からのフィードバックをお待ちしております。Swagger パネルの高評価アイコンまたは低評価アイコンをクリックして、生成された仕様に関するフィードバックを送信します。
      Cloud Code Gemini Code Assist のレート仕様
    5. プレビュー プロンプトを編集して仕様を再生成する場合は、プロンプトの上にあるプロンプト履歴の矢印をクリックして、以前のプロンプト間を移動します。
      Cloud Code Gemini Code Assist プロンプトのナビゲーション
  5. 仕様をテストします。新しい仕様が完成したら、モックサーバーを使用してテストできます。モックサーバーを使用して API をテストするをご覧ください。
  6. [保存] をクリックして、任意の名前で新しい API を保存します。
  7. この仕様から Apigee API プロキシを作成するには、[More] メニューから [Create API proxy] をクリックします。作成プロセスでは、プロキシ バンドルが作成されます。プロキシの左側のメニューリストに新しいプロキシが表示されます。Cloud Code からプロキシを作成する方法について詳しくは、Cloud Code に統合された API プロキシの作成チュートリアルをご覧ください。
    Cloud Code Gemini Code Assist による API プロキシの作成

効果的な API 仕様プロンプトの作成方法

生成された API 仕様の精度と適合性は、モデルに提供されたプロンプトに大きく依存します。

以下は適切なプロンプトの例です。

  • 顧客がクレジット カードやデビットカードなどのさまざまな支払い方法を使用して注文の支払いを行えるようにする API を作成します。
  • API を使用して特別なコーヒー豆の購入注文を受け付けます。
  • 私たちはピザ店で、カスタマイズされたオンラインピザ配達ソリューションを構築したいと考えています。ピザの注文を受け付ける API を作成します。
  • 食品宅配ビジネス用の API。ピザ、ハンバーガー、サンドイッチの組み合わせをまとめて 1 回で注文できます。そうした食べものの種類にはそれぞれ独自のスキーマがあります。ピザにはトッピングとサイズがあります。ハンバーガーにはトッピングとパティが用意されており、サンドイッチには、パンの種類、肉の種類、野菜、チーズがあり、注文のカスタマイズもできます。

次の例は、効果の低いプロンプトを示しています。次のような構造のプロンプトは避けてください。

  • ストアの API を作成します。このプロンプトには、完全かつ正確な仕様をモデルが生成するには情報が少なすぎます。
  • 注文オブジェクトを再利用する新しい払い戻し API を作成します。新しい API の作成時に Gemini Code Assist が再利用するオブジェクトを指定する必要はありません。Gemini Code Assist が再利用するのに最適なオブジェクトを自動的に検出します。

API Hub に API を登録する

API が審査され、完成したら、API Hub に登録してデベロッパーが使用できるようにします。

  1. [Register to API Hub] をクリックします。
  2. 画面の指示に沿って API を登録します。API Hub への登録と提供する必要がある情報については、API を登録するをご覧ください。

Cloud Code から API Hub API を更新する

Cloud Code から API Hub 仕様を編集するときに、API Hub 仕様の新しいバージョンを保存できます。

仕様を新しいバージョンとして保存するには、Swagger パネルの [その他] ボタンと [API hub に公開] をクリックします。新しい API バージョン ID を指定します。Cloud Code の [API Hub] リストにある API のバージョン リストに新しいバージョンが表示されます。

設定ファイルを使用して Gemini Code Assist の動作を制御する

このセクションでは、設定ファイルから Gemini コード アシスタンスの使用可否と使用方法を管理する方法について説明します。

Gemini Code Assist を無効または有効にする

Cloud Code で Apigee を設定したら(Cloud Code での Apigee の設定をご覧ください)、この行を設定ファイルに追加して Gemini Code Assist のすべての機能を一時的に無効にできます。

"cloudcode.apigee.gemini.enable": false

Gemini Code Assist を再度有効にするには、行を削除するか、true(デフォルト)に設定します。

仕様の生成でエンタープライズ コンテキストを制御する

OAS の生成には、組織の他の API のスキーマ、メタデータ、セキュリティ定義を含めることができます。このプロセスでは、API Hub・カタログのオブジェクト名と説明を使用して、アクセスが許可されている類似の API を検索します。API Hub API のデプロイ ステータスは考慮されません。

エンタープライズ コンテキストはデフォルトで有効になっています。

指定できる操作は次のとおりです。

  • Swagger パネルで、エンタープライズ コンテキストから含まれている変更の数を確認します(変更がある場合)。 Cloud Code Gemini Code Assist でのエンタープライズ コンテキストの参照数
  • [出力] パネルで、含まれている変更を確認します。 Cloud Code Gemini Code Assist 仕様の出力

新しい仕様生成でエンタープライズ コンテキストを無効にするには、次の行を "cloudcode.apigee.gemini.enable": true の後の settings.json ファイルに追加します。

"cloudcode.apigee.gemini.options": {
        "enterpriseContext": {
          "enabled": false,
          "includeMetadata": false,
          "includeSchema": false,
          "includeSecurity": false
        }
    }
ここで、

  • enabled は、エンタープライズ コンテキストを全体的に有効にするかどうかを指定します。エンタープライズ コンテキストを無効にするには、false に設定します。
  • includeMetadata は、メタデータ コンテキストを含めるかどうかを制御します。この設定では、API Hub 内の他の API のメタデータを含めるか除外するかを指定します。includeMetadata は、enabledtrue に設定されている場合にのみ適用されます。
  • includeSchema は、スキーマ コンテキストを含めるかどうかを制御します。この設定では、API Hub 内の他の API のスキーマ情報を含めるか除外するかを指定します。includeSchema は、enabledtrue に設定されている場合にのみ適用されます。
  • includeSecurity は、セキュリティ関連のコンテキストを含めるかどうかを制御します。この設定では、API Hub 内の他の API のセキュリティ情報を含めるか除外するかを指定します。includeSecurity は、enabledtrue に設定されている場合にのみ適用されます。

API を編集する

Cloud Code を使用して API Hub カタログの既存の API を編集するには、次の手順を行います。Cloud Code で行った変更は、API Hub に保存できます。

この手順は、Apigee の Gemini Code Assist アドオンを使用していないユーザーを対象としています。API の設計と編集時に Gemini Code Assist で利用できる追加機能については、Gemini Code Assist を使用して API を設計するをご覧ください。

API 仕様を編集するには:

  1. Cloud Code で選択したプロジェクトが、編集する API を含む API Hub カタログを持つプロジェクトであることを確認します。
  2. 左側のナビゲーションで、[API Hub] ツリーを展開します。
  3. リストから編集する API とバージョンを選択します。
  4. 編集パネルで仕様を編集します。API オペレーションは、Swagger パネルでも表示できます。
  5. 必要に応じて、モックサーバーを使用して API をテストします。
  6. Swagger パネルの [その他] ボタンを使用して変更を新しいバージョンとして保存し、[API Hub に公開] をクリックします。プロンプトが表示されたら、バージョンを確認または更新し、変更を API Hub に保存します。Cloud Code の [API Hub] リストにある API のバージョン リストに新しいバージョンが表示されます。

モックサーバーを使用して API をテストする

ローカルのモックサーバーまたは Google Cloud ベースのリモート モックサーバーを使用して API をテストできます。ローカルのモックサーバーはデフォルトでインストールされ、使用できますが、Google Cloud のモックサーバーは設定と管理が必要です。

ローカルのモックサーバーを使用する

ローカル モックサーバーは、この API へのリクエストを受け入れ、レスポンスをエミュレートします。現在のユーザーが現在のセッション中にのみ使用できます。ただし、リモートのモックサーバーとは異なり、セットアップや管理は不要です。費用もかかりません。

ローカルのモックサーバーを使用するには:

  1. [サーバー] プルダウンで、ローカル モックサーバー(開発サーバー)を選択します。
    Cloud Code Gemini Code Assist プロンプトのナビゲーション
  2. パスを開いて [Try it out] をクリックします。
    Cloud Code Gemini Code Assist プロンプトのナビゲーション
  3. リクエスト パラメータを入力して、[Execute] をクリックします。
    Cloud Code Gemini Code Assist プロンプトのナビゲーション
  4. プロンプトから curl を使用してリクエストを送信することもできます。[サーバー] プルダウンからサーバー アドレスとポートを使用します。

リモート モックサーバーを使用する

リモート モックサーバーを使用すると、永続的なモックサーバー インスタンスを作成できます。このインスタンスは、ローカルのモックサーバーとは異なり、組織内の他のユーザーと共有して使用できるため、本番環境にデプロイする前に新しい API をテストできます。リモート モックサーバーは、API Hub に登録されている API でのみ使用できます。

現在、リモート モックサーバーは Google Cloud で作成できます。Google Cloud のリモート モックサーバーでは、モックサーバーをデプロイした後に API に加えた変更が自動的に更新されません。そのため、API を完全に作成するまで、モックサーバーを追加しないでください。

Google Cloud でリモート モックサーバーをデプロイすると、新しい Cloud Run サービスが作成されます。Cloud Build を使用してモックサーバーのコンテナ イメージをビルドし、Google プロジェクトの Cloud Artifact Registry にコンテナ イメージをアップロードします。作成後の費用はお客様の負担となります。また、メンテナンスはお客様の責任で実施していただきます。不要になった場合は、お客様ご自身で削除してください。Cloud Run とはをご覧ください。また、サービスの管理Artifact Registry のドキュメントもご覧ください。

リモート モックサーバーをデプロイするには:

  1. [その他] メニューから [Deploy mock server (Google Cloud)] を選択します。
  2. API Hub に API がまだ登録されていない場合は、プロンプトが表示されます。指示に従って登録してください。
  3. リモート モックサーバーの詳細(プロジェクト IDサーバー名リージョン)を指定し、[作成] をクリックしてリモート モックサーバーを作成します。
  4. リモート モックサーバーの生成には数分かかります。進行状況は Google Cloud の [出力] パネルで確認できます。
  5. リモート モックサーバーの作成が完了すると、Swagger パネルのサーバーリストと [出力] パネルにリモート サーバーの URL が表示されます。
  6. モックサーバーを使用するには、パスを開いて [Try it out] をクリックします。
    Cloud Code Gemini Code Assist プロンプトのナビゲーション

    リクエスト パラメータを入力して、[実行] をクリックします。
    Cloud Code Gemini Code Assist プロンプトのナビゲーション

    プロンプトから curl を使用してリクエストを送信することもできます。[サーバー] プルダウンからサーバー アドレスとポートを使用します。

モックサーバーのアクセス権を他のユーザーと共有するには:

  1. デプロイされたサービスの呼び出し元ロールを他のユーザーに付与します。デベロッパーの認証をご覧ください。
  2. 限定公開サービスをテストするの手順で、モックサーバーにリクエストを送信します。

デプロイされたリモート モックサーバーを管理するには、次の操作を行います。

  1. API Hub に移動し、リモート モックサーバーを含む API のすべてのデプロイを確認します。
  2. リソース URL を使用してデプロイに移動し、モックサーバーの停止や削除などの管理作業を行います。