概要

OpenAPI 仕様では、標準的な形式を使用して RESTful API を記述します。JSON 形式または YAML 形式で記述された OpenAPI 仕様は、機械で読み取り可能でありながら、人間も簡単に読んで理解できます。

この仕様では、ベースパス、リソースパスと動詞、オペレーション、ヘッダー、クエリ パラメータ、レスポンスなど、API の要素を記述します。また、OpenAPI 仕様は API ドキュメントの生成にもよく使用されます。

このラボでは、小売業のバックエンド サービスの OpenAPI 仕様を確認します。次に、この OpenAPI 仕様を使用して、バックエンド API に機能とセキュリティを追加するために使用する API プロキシを作成します。

目標

このラボでは、次のタスクの実行方法について学びます。

• OpenAPI 仕様を確認し、さまざまなコンポーネントを理解する。
• プロキシ ウィザードを使用して、OpenAPI 仕様から API プロキシを作成する。
• API プロキシをトレースする。

設定

各ラボでは、新しい Google Cloud プロジェクトとリソースセットを一定時間無料で利用できます。

1. シークレット ウィンドウを使用して Google Skills にログインします。

2. ラボのアクセス時間（例: 1:15:00）に注意し、時間内に完了できるようにしてください。 一時停止機能はありません。必要な場合はやり直せますが、最初からになります。

3. 準備ができたら、[ラボを開始] をクリックします。

4. ラボの認証情報（ユーザー名とパスワード）をメモしておきます。この情報は、Google Cloud コンソールにログインする際に使用します。

5. [Google コンソールを開く] をクリックします。

6. [別のアカウントを使用] をクリックし、このラボの認証情報をコピーしてプロンプトに貼り付けます。 他の認証情報を使用すると、エラーや料金が発生します。

7. 利用規約に同意し、再設定用のリソースページをスキップします。

Google Cloud Shell の有効化

Google Cloud Shell は、開発ツールと一緒に読み込まれる仮想マシンです。5 GB の永続ホーム ディレクトリが用意されており、Google Cloud で稼働します。

Google Cloud Shell を使用すると、コマンドラインで Google Cloud リソースにアクセスできます。

1. Google Cloud コンソールで、右上のツールバーにある [Cloud Shell をアクティブにする] ボタンをクリックします。

   

2. [続行] をクリックします。

環境がプロビジョニングされ、接続されるまでしばらく待ちます。接続した時点で認証が完了しており、プロジェクトに各自のプロジェクト ID が設定されます。次に例を示します。

gcloud は Google Cloud のコマンドライン ツールです。このツールは、Cloud Shell にプリインストールされており、タブ補完がサポートされています。

• 次のコマンドを使用すると、有効なアカウント名を一覧表示できます。

gcloud auth list

出力:

Credentialed accounts: - @.com (active)

出力例:

Credentialed accounts: - google1623327_student@qwiklabs.net

• 次のコマンドを使用すると、プロジェクト ID を一覧表示できます。

gcloud config list project

出力:

[core] project =

出力例:

[core] project = qwiklabs-gcp-44776a13dea667a6 注: gcloud ドキュメントの全文については、 gcloud CLI の概要ガイド をご覧ください。

タスク 1. バックエンド サービスの OpenAPI 仕様を確認する

このタスクでは、API プロキシで使用するバックエンド サービス用に作成された OpenAPI 仕様を確認します。

OpenAPI 仕様をダウンロードする

• Cloud Shell で、次の curl コマンドを使用してバックエンド サービスの OpenAPI 仕様をダウンロードします。

  curl https://storage.googleapis.com/cloud-training/developing-apis/specs/retail-backend.yaml?$(date +%s) --output ~/retail-backend.yaml

  この curl コマンドにより、retail-backend.yaml という名前のファイルがダウンロードされ、ホーム ディレクトリに同じ名前のファイルで保存されます。ラボの後半では、API プロキシを作成するときに、この同じ仕様を使用します。

  注: "?$(date +%s)" は、現在の日時の文字列表現であるクエリ パラメータを URL に追加します。このように動的に変化する変数を URL に含めることで、以前のバージョンがキャッシュされている場合でも、curl は必ずファイルの最新バージョンを取得するようになります。

Cloud Shell エディタで OpenAPI 仕様を表示する

1. Cloud Shell で [エディタを開く] をクリックします。

   

2. エディタで、retail-backend.yaml ファイルを選択します。

   

仕様の各セクションを確認する

1. OpenAPI 仕様を確認します。

   これは、コースの多くのラボで使用されるバックエンド サービスの OpenAPI 仕様です。OpenAPI 仕様の各セクションを見てみましょう。

   openapi フィールドは、OpenAPI 仕様のバージョンを指定します。ファイルの先頭にあるバージョン番号が示しているとおり、これは OpenAPI バージョン 3 の仕様です。

   openapi: "3.0.0"

   info オブジェクトは、API 自体に関するメタデータを提供します。表示されているバージョンは、Retail Backend 仕様のバージョンです。

   info: version: 1.0.0 title: Retail Backend description: Retail backend database used for Developing APIs course contact: name: Google Cloud (Apigee) email: apigee@example.org url: https://cloud.google.com/apigee license: name: MIT url: https://opensource.org/licenses/MIT

   servers 配列には、ターゲット サーバーの接続情報を指定するサーバー オブジェクトのリストが含まれます。この仕様には、API プロキシが呼び出す単一のバックエンド サービスが含まれています。

   servers: - url: "https://gcp-cs-training-01-test.apigee.net/training/db" description: Retail backend for Developing APIs course

   tags 配列は、以下のようにオペレーションで使用されるタグにメタデータを追加します。タグは複数のオペレーションで共有されることがあり、タグを使用して詳細な説明や外部ドキュメントへのリンクを提供できます。

   tags: - name: categories description: Product Categories - name: products description: Products - name: orders description: Orders - name: stores description: Stores

   paths オブジェクトには、個々のエンドポイントへの相対パスと、そのオペレーションが保持されます。このようなパスの一つである /categories/{categoryId} は、単一のカテゴリを指定するために使用されます。ここでは、ID でカテゴリを取得するために指定された get オペレーションを示しています。get オブジェクトは、パラメータとレスポンスを表示します。PATCH /products/{productId} のようにリクエスト本文を含むオペレーションの場合、リクエスト本文も指定されます。

   /categories/{categoryId}: get: summary: Get a specific category operationId: getCategoryById tags: - categories parameters: - name: categoryId in: path required: true description: category id schema: type: integer responses: '200': description: Selected category content: application/json: schema: $ref: "#/components/schemas/Category" '404': description: Category not found content: application/json: schema: $ref: "#/components/schemas/Error" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error"

   components オブジェクトには、OpenAPI 仕様のさまざまな部分で再利用できるオブジェクトが含まれています。securitySchemes コンポーネント オブジェクトには、オペレーションで使用されるさまざまな種類のセキュリティ スキームの定義が含まれています。この仕様では、PATCH /products/{productId} オペレーションで参照される単一の基本認証スキームを定義しています。schemas コンポーネント オブジェクトには、入力データ型と出力データ型が含まれています。以下の Category オブジェクトは、GET /categories/{categoryId} オペレーションが正常に返されたときに返されるオブジェクトです。

   components: securitySchemes: basicAuth: type: http description: basic auth scheme: basic schemas: Category: type: object description: product category required: - color - id - name properties: color: description: use this color for displaying this category type: string id: description: integer id (used for access) type: integer format: int32 minimum: 0 name: description: category name type: string

   この仕様と OpenAPI 仕様のドキュメントを自由に参照してください。

2. この OpenAPI 仕様の詳細については、エディタの Gemini Code Assist パネルを使用してください。[プロンプト] セクションでコンテキスト アイテムを開き、現在のファイル retail-backend.yaml ファイルが選択されていることを確認します。

3. プロンプトに次のように入力します。

   Explain the contents of this file.

4. [送信]（）をクリックします。

   Gemini が、バックエンドの OpenAPI 仕様の内容を説明する回答を生成します。回答には、定義されている各セクションの目的を説明する概要と主要なセクションが含まれています。

OpenAPI 仕様をマシンにダウンロードする

1. [ターミナルを開く] をクリックします。

2. Cloud Shell のその他メニュー（）を選択し、[ダウンロード] をクリックします。

3. 「retail-backend.yaml」と入力して、[ダウンロード] をクリックします。

   これでファイルがローカルマシンにダウンロードされます。

タスク 2. OpenAPI 仕様を使用して API プロキシを作成する

このタスクでは、バックエンド サービスの OpenAPI 仕様を使用して API プロキシを作成します。

Apigee コンソール ページを固定する

1. Google Cloud コンソールのナビゲーション メニュー（）で、[お気に入りのプロダクト] セクションの [Apigee] を探します。

   Apigee コンソール ページが開きます。

2. [Apigee] が表示されない場合は、上部の検索バーで「Apigee」を検索し、[Apigee] サービスに移動します。

3. コンソールで Apigee を固定するには、お気に入りアイコン（）をクリックします。

   Apigee コンソール ページがナビゲーション メニューのお気に入りプロダクトとして表示されます。

プロキシ ウィザードを使用してプロキシを作成する

1. 左側のナビゲーション メニューで、[プロキシ開発] > [API プロキシ] を選択します。

2. [+ 作成] をクリックして、プロキシ ウィザードを起動します。

3. [Proxy template] で、[OpenAPI spec template] > [Reverse proxy (Most common)] を選択します。

4. [OpenAPI specs] で [Browse] をクリックし、ダウンロードした retail-backend.yaml ファイルを選択して、[Open] をクリックします。

5. [Next] をクリックします。

6. [Proxy details] で次のように指定します。

   プロパティ	値
   Proxy name	retail-v1
   Base path	/retail/v1
   Description	My retail API

   ターゲットは、OpenAPI 仕様の servers 配列から取得されました。ターゲットは変更しないでください。

   注: [Base path] には「/retail-v1」ではなく「/retail/v1」を使用してください。

7. [Next] をクリックします。

   OpenAPI 仕様で見つかったオペレーションが一覧表示されます。

8. [Flows] のヘッダー行で、[Select all rows] をクリックします。

   すべてのフローが選択されているはずです。

9. [Next] をクリックします。

10. [Deployment environments] で [eval] 環境を選択し、[OK] をクリックします。

    注: [Service Account] フィールドは空のままにします。

11. [Create] をクリックします。

    プロキシが生成され、デプロイ対象としてマークされます。

ランタイムが使用可能になるまでに時間がかかることがある

通常、Apigee 組織の完全なプロビジョニングには 30 分以上かかります。ほとんどの時間は、API プロキシの実行に使用されるランタイム クラスタ、ランタイム データベース、サービスのプロビジョニングに費やされます。長期有効な Apigee 組織を作成する場合、プロビジョニングの遅延は問題になりません。ただし、各ラボを開始する前に 30 分も待つことは避けたいところです。

ラボに入った時点で、組織のプロビジョニングがすでに終了していることがあります。また、ラボを開始したときに初めて Apigee 組織のプロビジョニングが開始されることもあります。

組織の管理プレーン操作は、プロビジョニング プロセスの数分後に実行可能になります。これらのラボでは、ランタイムが完全にプロビジョニングされるのを待たなくても、ランタイムが使用可能になる前にプロキシ編集などの操作を行うことができます。ランタイムが使用可能になる前にプロキシを環境にデプロイすると、ランタイムのプロビジョニングが完了するまでトラフィックを受け付けることができません。

デプロイされたプロキシのステータス アイコンにカーソルを合わせると、次の図のように、ステータスを報告しているインスタンスがないことが示される場合があります。これは、Apigee 組織のランタイムが完全にプロビジョニングされるまでの正常な状態です。

Apigee プロキシのデプロイについて学習する

Apigee 環境への API プロキシのデプロイ プロセスについて詳しく知りたい場合は、Google Cloud コンソールで Gemini Cloud Assist を使用できます。

Gemini Cloud Assist を開く

1. Gemini Cloud Assist を開くには、Google Cloud コンソールで Gemini Cloud Assist チャットを開始または終了するアイコン（）をクリックします。

2. [Cloud Assist] パネルでメッセージが表示されたら、[Gemini Cloud Assist を入手する] をクリックします。

3. 必要に応じて、有効にすることが必要な API と推奨 API を表示します。

4. [Gemini Cloud Assist を無料で有効にする] をクリックします。

5. [チャットを開始] をクリックします。

Gemini にプロンプトを入力する

1. プロンプトに次のように入力します。

   In Apigee X, explain the deployment process of an API proxy to an Apigee environment.

2. [送信]（）をクリックします。

   Gemini Cloud Assist によって生成された回答を読みます。

3. 必要に応じて、[関連コンテンツを表示] をクリックして関連ドキュメントを参照します。

デプロイ ステータスを確認する

デプロイされ、トラフィックを受信する準備ができているプロキシは、[概要] タブに緑色のステータスで表示されます。

プロキシがデプロイ済みとしてマークされているが、ランタイムがまだ利用可能になっておらず、環境が接続されていない場合、赤い警告マークが表示されることがあります。[ステータス] アイコンにカーソルを合わせると、現在のステータスが表示されます。

プロキシがデプロイされ、緑色で表示されている場合、プロキシは API トラフィックの準備ができています。ランタイム Pod がないためプロキシがデプロイされていない場合は、プロビジョニングのステータスを確認できます。

プロビジョニングのステータスを確認する

• Cloud Shell で、ランタイム インスタンスがインストールされ、評価環境が接続されていることを確認するには、次のコマンドを実行します。

  export PROJECT_ID=$(gcloud config list --format 'value(core.project)'); echo "PROJECT_ID=${PROJECT_ID}"; export INSTANCE_NAME=eval-instance; export ENV_NAME=eval; export PREV_INSTANCE_STATE=; echo "waiting for runtime instance ${INSTANCE_NAME} to be active"; while : ; do export INSTANCE_STATE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/instances/${INSTANCE_NAME}" | jq "select(.state != null) | .state" --raw-output); [[ "${INSTANCE_STATE}" == "${PREV_INSTANCE_STATE}" ]] || (echo; echo "INSTANCE_STATE=${INSTANCE_STATE}"); export PREV_INSTANCE_STATE=${INSTANCE_STATE}; [[ "${INSTANCE_STATE}" != "ACTIVE" ]] || break; echo -n "."; sleep 5; done; echo; echo "instance created, waiting for environment ${ENV_NAME} to be attached to instance"; while : ; do export ATTACHMENT_DONE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/instances/${INSTANCE_NAME}/attachments" | jq "select(.attachments != null) | .attachments[] | select(.environment == \"${ENV_NAME}\") | .environment" --join-output); [[ "${ATTACHMENT_DONE}" != "${ENV_NAME}" ]] || break; echo -n "."; sleep 5; done; echo "***ORG IS READY TO USE***"; これらのコマンドは、ランタイム インスタンスが作成され、評価環境がインスタンスに接続されたタイミングを、Apigee API を使用して特定します。Gemini にコマンドの仕組みを説明してほしい場合は、このコマンドを Cloud Assist にコピーできます。

  スクリプトが ORG IS READY TO USE を返したら、次の手順に進むことができます。

処理が終わるまでの間

• Web API Design: The Missing Link - API 設計の原則に関する電子書籍
• OpenAPI 仕様

タスク 3. API プロキシを探索してトレースする

デバッグツールを起動する

1. [Develop] タブを選択します。

   このタブは、生成されたプロキシを編集するために使用します。OpenAPI 仕様の各オペレーションに対して条件付きフローが作成されています。これらの条件付きフローは、左側のナビゲーターのプロキシ エンドポイントに表示されます。条件付きフローをクリックすると、そのリクエストとレスポンスのセクションがビジュアル エディタ ペインで選択されます。以下の default.xml コードは、プロキシ エンドポイント フローのコード表現です。

   

   これらの条件付きフローの多くは、後のラボで更新します。

2. [Debug] タブを選択します。

   デバッグツールは、プロキシによって処理される API リクエストをトレースするために使用されます。

3. [Start Debug Session] をクリックします。

4. [デバッグ セッションを開始] ペインで、環境のプルダウンから [eval] を選択します。

   デプロイされたリビジョン番号もプルダウンに表示されます。

5. [Start] をクリックします。

   デバッグ セッションは 10 分間実行されます。

プライベート DNS を使用して API プロキシをテストする

Apigee 組織の eval 環境は、eval.example.com というホスト名で呼び出すことができます。このホスト名を Apigee ランタイム インスタンスの IP アドレスに解決する DNS エントリは、すでにプロジェクト内に作成されています。この DNS エントリは限定公開ゾーンに作成されているため、内部ネットワークのみで表示されます。

Cloud Shell は内部ネットワークに存在しないため、Cloud Shell のコマンドではこの DNS エントリを解決できません。プロジェクト内の仮想マシン（VM）は、限定公開ゾーンの DNS にアクセスできます。この目的で、apigeex-test-vm という名前の仮想マシンが自動的に作成されています。このマシンから API プロキシ呼び出しを行うことができます。

curl コマンドは、API プロキシに API リクエストを送信するために使用されます。curl に -k オプションを指定すると、TLS 証明書の検証がスキップされます。このラボの Apigee ランタイムでは自己署名証明書を使用します。本番環境では、信頼できる認証局（CA）によって作成された証明書を使用する必要があります。

1. Cloud Shell で新しいタブを開き、テスト VM への SSH 接続を開きます。

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   1 つ目の gcloud コマンドでテスト VM のゾーンを取得し、2 つ目のコマンドで VM への SSH 接続を開きます。

2. プロンプトが表示されたら、「Y」と入力して続行します。

   Cloud Shell で確認されるすべての項目について、Enter キーまたは Return キーを押して、デフォルトの入力を指定します。

   プロジェクトのオーナーとしてログインしているため、このマシンへの SSH 接続が許可されます。

   これで、Cloud Shell セッションを VM 内で実行できるようになります。

API プロキシを呼び出す

1. eval 環境でホストされているプロキシを呼び出すには、Cloud Shell SSH セッションで次のコマンドを使用して API プロキシにリクエストを送信します。

   curl -i -k -X GET https://eval.example.com/retail/v1/categories

   このリクエストのトランザクションが、左側の [トランザクション] ペインに表示されます。トランザクションを選択すると、Apigee を介したリクエストとレスポンスのトレースが表示されます。バックエンド URL が正しく設定され、[Send Requests] の URL が正しく更新された場合は、200 ステータス コードが表示されます。

   注: Apigee デバッグ セッションのトラフィックは、新しい API 呼び出しを非同期でポーリングすることによって取得されます。そのため、API リクエストが完了してからデバッグツールに表示されるまでに遅延が発生する可能性があります。

2. [Back] ボタンと [Next] ボタンをクリックして、トランザクションのステップを移動します。

   リクエストは GET /retail/v1/categories でした。このリクエストはバックエンドに送信され、バックエンドはカテゴリを含む JSON 配列で応答しました。

お疲れさまでした

このラボでは、OpenAPI 仕様について学び、OpenAPI 仕様の機能の一部を確認しました。小売業のバックエンド サービスの OpenAPI 仕様を使用して API プロキシを作成し、そのプロキシを介した呼び出しをトレースしました。

ラボを終了する

ラボが完了したら、[ラボを終了] をクリックします。ラボで使用したリソースが Google Skills から削除され、アカウントの情報も消去されます。

ラボの評価を求めるダイアログが表示されたら、星の数を選択してコメントを入力し、[送信] をクリックします。

星の数は、それぞれ次の評価を表します。

• 星 1 つ = 非常に不満
• 星 2 つ = 不満
• 星 3 つ = どちらともいえない
• 星 4 つ = 満足
• 星 5 つ = 非常に満足

フィードバックを送信しない場合は、ダイアログ ボックスを閉じてください。

フィードバックやご提案の送信、修正が必要な箇所をご報告いただく際は、[サポート] タブをご利用ください。

Copyright 2026 Google LLC All rights reserved. Google および Google のロゴは、Google LLC の商標です。その他すべての社名および製品名は、それぞれ該当する企業の商標である可能性があります。