API の設計と編集

このページは Apigee と Apigee ハイブリッドに適用されます。

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

このページでは、Gemini Code Assist を活用して API 仕様の作成、編集、管理を迅速化し、Cloud Code の Apigee で API を設計、編集する方法について説明します。

始める前に

このガイドの機能を使用する前に、次の準備を行います。

Apigee で Gemini Code Assist を使用するなど、VS Code 用の Cloud Code で Apigee API Management を設定するの手順で設定が完了していることを確認します。
ユーザーアカウントに、Apigee で Gemini Code Assist を使用するのに必要なロールに記載されているロールがタスクごとに付与されていることを確認します。

効果的な API 仕様プロンプトを作成する

API 仕様の作成時と編集時に、Apigee で Gemini Code Assist が起動します。生成される API 仕様の精度と適合性は、モデルに提供されたプロンプトに大きく依存します。

効果的な API 仕様の作成と編集のプロンプトを作成するには:

Gemini Code Assist のチャットでは、API 仕様の作成または編集を行うプロンプトの先頭に必ず Apigee ハンドル（@Apigee）を使用します。Apigee ハンドルを使用すると、このガイドで説明する堅牢で機能豊富な API 仕様開発機能を含む Apigee ツールにアクセスできます。
自然言語を使用する: 仕様を作成するユーザーに話しかけるようにプロンプトを作成します。
具体的に記述する: 歯科医院の予約 API には予約タイプと歯科医院の場所を複数含める必要があるなど、可能な限り正確な要件を指定します。
オブジェクト名を指定せずに企業のコンテキストを活用する: Gemini Code Assist は、API Hub カタログ内の既存のスキーマ、メタデータ、セキュリティ定義をインテリジェントに検出して再利用します。正確なオブジェクト名を指定する必要はありませんが、プロンプトに Use API Hub や Leverage Enterprise Context などのフレーズを含めることで、この機能をヒントとして示唆できます。
フォローアッププロンプトを使用して API を反復処理する:「この API から場所のエンティティを削除」などのプロンプトを使用して、API に変更を加えることができます。

以下は、API 仕様の作成と編集に効果的ではないプロンプトと効果的なプロンプトの例です。

効果的ではないメッセージ	プロンプトの説明	より適切なプロンプト
「ストアの API を作成して。」	このプロンプトには、完全かつ正確な仕様をモデルが生成するには情報が少なすぎます。	「ユーザーが商品の在庫状況を確認してショッピングカートに商品を追加できるように、ショップ用の API を作成して。」「購入者がクレジットカードやデビットカードといったさまざまな支払い方法で注文の支払いを行えるようにする API を作成して。」
「注文オブジェクトを再利用する新しい払い戻し API を作成して。」	API の作成時に Gemini Code Assist が再利用するオブジェクトを指定する必要はありません。再利用するのに最適なオブジェクトを Gemini Code Assist が自動的に検出します。	「購入者が以前の注文の払い戻しをリクエストできるようにする新しい払い戻し API を作成して。」
「配送サービスの API を作成して。」	生成される API は一般的すぎるものになります。	「ピザ店で、カスタマイズされたオンラインピザ配達ソリューションを構築したいと考えています。ピザのサイズとトッピングを指定してピザの注文を受け付ける API を作成して。」「食品宅配ビジネス用の API。ピザ、ハンバーガー、サンドイッチの組み合わせをまとめて 1 回で注文できます。そうした食べものの種類にはそれぞれ独自のスキーマがあります。ピザにはトッピングとサイズがあります。ハンバーガーにはトッピングとパティが用意されています。サンドイッチには、パンの種類、肉の種類、野菜、チーズがあり、注文のカスタマイズもできます。

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

Cloud Code の Gemini Code Assist を使用して、OpenAPI 仕様（OAS）バージョン 3.0 API を設計できます。設計される API には、新しい API の生成時に企業のコンテキストを含めることができます。API Hub を使用するプロジェクトでのみ使用できます。

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

Gemini Code Assist で新しい API を生成する手順は次のとおりです。

次のいずれかの方法で API 仕様作成プロンプトにアクセスします。
- Gemini Code Assist のチャットの場合: チャットウィンドウで Apigee ハンドル @Apigee を入力し、Apigee ツールを選択します。
- Cloud Code の Apigee の場合: [Apigee] の行にある魔法の杖アイコンをクリックします。これにより、Gemini Code Assist のチャットが読み込まれます。@Apigee を使用して Apigee ツールを呼び出し、仕様の作成を開始します。
Apigee ツールのオプションから [Create API specification] を選択します。
新しい API の説明をプロンプトに入力します。効果的な API 仕様プロンプトを作成するをご覧ください（@Apigee ハンドルにコピーして貼り付けないでください。代わりに、ハンドルの後にテキストを入力または貼り付けてプロンプトを完成させます）。
プロンプトを送信します。
Gemini Code Assist により、API を定義する OAS が生成されます（これには 1 分ほどかかります）。API Hub に他の API が含まれている場合、新しい OAS にはカタログのオブジェクトとコンテキストが組み込まれることがあります。コンテキストチャットの概要には、生成された API と使用されたソースに関する情報が表示されます。
生成された仕様を確認します。新しい API の YAML コード仕様と Swagger パネルの両方が、タブに自動的に表示されます。
新しい仕様が完成したら、モックサーバーを使用してテストできます。モックサーバーを使用して API をテストするをご覧ください。
新しい API を API Hub カタログに保存するには、API Hub に API を公開するをご覧ください。
この仕様から Apigee API プロキシバンドルを作成するには、API を API プロキシバンドルとして保存するをご覧ください。

API を編集する

ローカルに保存した API や API Hub カタログの API を編集できます。Cloud Code で行った変更は、API Hub に保存するか、Apigee API プロキシバンドルとして保存できます。

API Hub から API 仕様を編集する

API Hub カタログに保存されている API 仕様を編集するには:

Cloud Code で選択したプロジェクトが、編集する API を含む API Hub カタログを持つプロジェクトであることを確認します。
左側のナビゲーションで、[Apigee] セクションの [API Hub] ツリーを展開します。
リストから編集する API とバージョンを選択します。
Swagger パネルで API オペレーションを確認します。Swagger パネルの [コードを表示] をクリックして、編集タブで YAML ファイルを開きます。

ローカルに保存されている API 仕様を編集する

ローカルに保存されている API 仕様を編集するには、Cloud Code で API 仕様ファイルを開きます。仕様を手動で更新することも、Gemini Code Assist のチャットを利用して仕様を反復処理することもできます。

Gemini Code Assist のチャットを利用して API 仕様を反復処理する

既存の API 仕様を変更するには、Gemini Code Assist のチャットを使用します。

API Hub の API 仕様またはローカル API 仕様ファイルの手順に沿って、仕様ファイルを Cloud Code に読み込みます。
仕様を含む YAML ファイルが、エディタで現在アクティブなタブに表示されていることを確認します。
Gemini Code Assist のチャットウィンドウで Apigee ハンドル @Apigee を入力し、Apigee ツールを選択します。
仕様を更新するためのプロンプトを入力します。ガイダンスについては、効果的な API 仕様プロンプトを作成するをご覧ください。
必要に応じて、モックサーバーを使用して API をテストします。
新しい API を API Hub カタログに保存するには、API Hub に API を公開するをご覧ください。
この仕様から Apigee API プロキシバンドルを作成するには、API を API プロキシバンドルとして保存するをご覧ください。

API Hub に API を公開する

API Hub を使用している場合は、API Hub に API を登録して、他の開発者が API を使用できるようにできます。

新しい API 仕様または編集した API 仕様の Swagger パネルで、[API Hub に公開] をクリックします。
フォームで API のメタデータを指定すると、API Hub カタログ内の API の検出と整理を改善できます。ほとんどのフィールドは API 仕様から自動入力されますが、値は変更できます。API Hub への登録と提供する必要がある情報については、API を登録するをご覧ください。
- API Display Name（必須）: 他の開発者に表示される API の名前。
- API Description（省略可）: 社内向け / 開発者向けの API の説明。
- API Owner Name（省略可）: API オーナーの名前。
- API Owner Email（省略可）: オーナーのメールアドレス。
- API Version（必須）: API のバージョン。
- Lifecycle Stage（省略可）: リストからステージを選択します。
[Publish] をクリックして、API Hub に API を公開します。
しばらくすると、Cloud Code の Apigee セクションの API Hub ツリーに変更内容が表示されます。

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

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

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

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

また、ローカルモックサーバーについて、次の点に注意してください。

Cloud Shell エディタまたは Cloud Workstations を使用している場合は機能しません。
VS Code Remote Explorer を使用すると、正しく動作しない可能性があります。

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

[サーバー] プルダウンで、ローカルモックサーバーを選択します（まだ選択されていない場合）。
Swagger パネルでパスを開き、[試してみる] をクリックします。
リクエストパラメータを入力して、[実行] をクリックします。

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

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

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

Google Cloud リモートモックサーバーをデプロイすると、新しい Cloud Run サービスが作成されます。Cloud Build を使用してモックサーバーのコンテナイメージをビルドし、Google プロジェクトの Cloud Artifact Registry にコンテナイメージをアップロードします。Cloud Run とはをご覧ください。また、サービスの管理と Artifact Registry のドキュメントもご覧ください。

Cloud Run アプリケーションをデプロイには、デフォルトのサービスアカウントを使用することも、より制限されたサービスアカウントを指定することもできます。詳細については、Cloud Code for VS Code で Cloud APIs と Cloud クライアントライブラリを管理するをご覧ください。

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

Swagger パネルで [Deploy mock server] を選択します。
API Hub に API がまだ登録されていない場合は、プロンプトが表示されます。指示に沿って登録してください。
リモートモックサーバーの詳細（サーバー名、セキュアサーバー、サービスアカウント（デフォルトのサービスアカウントを使用する場合は空白のまま）、サーバー URL を API 仕様に追加するかどうか）を指定し、[作成] をクリックしてリモートモックサーバーを作成します。
重要: 現在、ユーザーインターフェースで同じ名前のリモートモックサーバーを複数作成できますが、実際に作成することは避けてください。
リモートモックサーバーの生成には数分かかります。進行状況は、Cloud Code の [出力] パネルと、VS Code の右下にある通知ポップアップで確認できます。
リモートモックサーバーの作成が完了すると、Swagger パネルのサーバーリストと [出力] パネルにリモートサーバーの URL が表示されます。
モックサーバーを使用するには、パスを開いて [Try it out] をクリックします。

リクエストパラメータを入力して、[実行] をクリックします。

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

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

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

デプロイされたリモートモックサーバーを管理するには:

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

API を API プロキシバンドルとして保存する

API を Apigee API プロキシバンドルとして保存すると、Apigee ローカル開発環境内で作業できます。Cloud Code での API プロキシの操作方法については、API プロキシを開発するをご覧ください。

Swagger パネルで [Create API proxy bundle] をクリックします。
プロンプトフィールドに API プロキシの名前を入力して続行します。
API プロキシが、ローカルワークスペースの Apigee 左側のメニューの [apiproxies] の下に表示されます。

仕様の生成で企業のコンテキストを制御する

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

企業のコンテキストはデフォルトで有効になっています。

新しい仕様生成で企業のコンテキストを無効にするには、次の行を "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 は、enabled が true に設定されている場合にのみ適用されます。
includeSchema は、スキーマコンテキストを含めるかどうかを決定します。この設定では、API Hub 内の他の API のスキーマ情報を含めるか除外するかを指定します。includeSchema は、enabled が true に設定されている場合にのみ適用されます。
includeSecurity は、セキュリティ関連のコンテキストを含めるかどうかを決定します。この設定では、API Hub 内の他の API のセキュリティ情報を含めるか除外するかを指定します。includeSecurity は、enabled が true に設定されている場合にのみ適用されます。