API の設計と編集

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

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

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

API の設計に必要な追加ロール

このページで説明する API の設計手順とテスト手順の一部を実施するには、以下のロールが必要です。

タスク	必要なロール
Gemini Code Assist を使用して API を設計する	Gemini for Google Cloud ユーザー Service Usage ユーザー Google Cloud プロジェクトで Gemini Code Assist の IAM ロールを付与するをご覧ください。
API を設計する際に API Hub の既存の API からエンタープライズコンテキストを使用する	Cloud API Hub 閲覧者
新しい API を API Hub に登録する	Cloud API Hub 編集者または管理者
Cloud Code で API Hub の API を編集する	Cloud API Hub 編集者または管理者
API をテストするためのリモートモックサーバーを設定して管理する	Artifact Registry 管理者 Cloud Build サービスアカウント Cloud Run 管理者 Service Usage 管理者 IAM の基本ロールと事前定義ロールのリファレンスをご覧ください。

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 を生成する

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

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

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

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

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

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

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

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

API Hub に API を登録する

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

[Register to API Hub] をクリックします。
画面の指示に沿って 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 パネルで、エンタープライズコンテキストから含まれている変更の数を確認します（変更がある場合）。
[出力] パネルで、含まれている変更を確認します。

新しい仕様生成でエンタープライズコンテキストを無効にするには、次の行を "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 に設定されている場合にのみ適用されます。

API を編集する

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

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

API 仕様を編集するには:

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

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

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

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

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

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

[サーバー] プルダウンで、ローカルモックサーバー（開発サーバー）を選択します。
パスを開いて [Try it out] をクリックします。
リクエストパラメータを入力して、[Execute] をクリックします。
プロンプトから 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 のドキュメントもご覧ください。

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

[その他] メニューから [Deploy mock server (Google Cloud)] を選択します。
API Hub に API がまだ登録されていない場合は、プロンプトが表示されます。指示に従って登録してください。
リモートモックサーバーの詳細（プロジェクト ID、サーバー名、リージョン）を指定し、[作成] をクリックしてリモートモックサーバーを作成します。
重要: 現在、ユーザーインターフェースで同じ名前のリモートモックサーバーを複数作成できますが、そうしないでください。
リモートモックサーバーの生成には数分かかります。進行状況は Google Cloud の [出力] パネルで確認できます。
リモートモックサーバーの作成が完了すると、Swagger パネルのサーバーリストと [出力] パネルにリモートサーバーの URL が表示されます。
モックサーバーを使用するには、パスを開いて [Try it out] をクリックします。

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

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

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

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

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

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