Compute Engine での Cloud Endpoints のスタートガイド

このチュートリアルでは、Compute Engine 上に事前構築された Docker コンテナ内で実行されるサンプル API と Extensible Service Proxy(ESP)を構成およびデプロイする方法について説明します。サンプルコードの REST API は、OpenAPI 仕様に従って作成されています。このチュートリアルでは、API キーを作成して API に対するリクエストで使用する方法も説明します。

Cloud Endpoints の概要については、Endpoints についておよび Endpoints アーキテクチャをご覧ください。

目標

タスクの概要を示す次のリストを参照しながら、チュートリアルを実施してください。API にリクエストを送信するには、すべてのタスクを行う必要があります。

  1. Google Cloud Platform(GCP)プロジェクトをセットアップします。始める前にをご覧ください。
  2. Compute Engine VM インスタンスを作成します。Compute Engine のインスタンスを作成するをご覧ください。
  3. サンプルコードをダウンロードします。サンプルコードを取得するをご覧ください。
  4. Endpoints の構成に使用する openapi.yaml ファイルを構成します。Endpoints を構成するをご覧ください。
  5. Endpoints 構成をデプロイして Endpoints サービスを作成します。Endpoints 構成をデプロイするをご覧ください。
  6. API と ESP を Compute Engine VM でデプロイします。API バックエンドをデプロイするをご覧ください。
  7. IP アドレスを使用して API にリクエストを送信します。IP アドレスを使用してリクエストを送信するをご覧ください。
  8. サンプル API の DNS レコードを構成します。Endpoints の DNS を構成するをご覧ください。
  9. 完全修飾ドメイン名を使用して API にリクエストを送信します。FQDN を使用してリクエストを送信するをご覧ください。
  10. API のアクティビティを追跡します。API の活動を追跡するをご覧ください。
  11. GCP アカウントに課金されないようにします。クリーンアップをご覧ください。

料金

このチュートリアルでは、以下の課金対象の Google Cloud Platform コンポーネントを使用します。

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを出すことができます。 GCP を初めてご利用の場合は、無料トライアルをご利用いただけます。

このチュートリアルを終了した後、作成したリソースを削除すると、それ以上の請求は発生しません。詳しくは、クリーンアップをご覧ください。

始める前に

  1. Google アカウントにログインします。

    Google アカウントをまだお持ちでない場合は、新しいアカウントを登録します。

  2. GCP プロジェクトを選択または作成します。

    プロジェクト セレクタのページに移動

  3. Google Cloud Platform プロジェクトに対して課金が有効になっていることを確認します。 詳しくは、課金を有効にする方法をご覧ください。

  4. 後で必要になるので、プロジェクト ID をメモしておきます。
  5. サンプル API にリクエストを送信するためのアプリケーションが必要です。

    • Linux ユーザーと macOS ユーザー: このチュートリアルでは、curl の使用例を示します。これは通常、オペレーティング システムにプリインストールされていますが、curl をお持ちでない場合は、curlリリースとダウンロードのページからダウンロードできます。
    • Windows ユーザー: このチュートリアルでは、Invoke-WebRequest の使用例を示しています。これは PowerShell 3.0 以降でサポートされています。
  6. Cloud SDK をダウンロードします
  7. Cloud SDK を更新し、Endpoints コンポーネントをインストールします。
    gcloud components update
  8. Cloud SDK(gcloud)が GCP にある対象のデータとサービスにアクセスできるよう許可されていることを確認します。
    gcloud auth login
    表示された新しいブラウザタブで、アカウントを選択します。
  9. プロジェクト ID にデフォルト プロジェクトを設定します。
    gcloud config set project YOUR_PROJECT_ID

    YOUR_PROJECT_ID は、実際のプロジェクト ID で置き換えます。他にも GCP プロジェクトがあり、gcloud を使用してそのプロジェクトを管理する場合は、Cloud SDK 構成の管理をご覧ください。

このチュートリアルを終了した後、作成したリソースを削除すると、それ以上の請求は発生しません。詳しくは、クリーンアップをご覧ください。

Compute Engine インスタンスの作成

    Compute Engine のインスタンスを作成するには:

    必要なオプションを設定した状態の VM インスタンス作成ウィンドウのスクリーンショット

    インスタンスが起動するまで、しばらくお待ちください。準備が完了すると、[VM インスタンス] ページに緑色のステータス アイコン付きで表示されます。

  1. VM インスタンスに接続できることを確認します。
    1. これで、ターミナルを使用して Debian インスタンスで Linux コマンドを実行できるようになります。
    2. インスタンスとの接続を切断するには、「exit」と入力します。
  2. 後で必要となるため、インスタンス名、ゾーン、外部 IP アドレスをメモします。

サンプルコードをダウンロードする

サンプルコードをローカルマシンにダウンロードします。

Java

サンプル API のクローンを作成するか、ダウンロードするには:

  1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

  2. サンプルコードが含まれているディレクトリに移動します。
    cd java-docs-samples/endpoints/getting-started
Python

サンプル API のクローンを作成するか、ダウンロードするには:

  1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

  2. サンプルコードが含まれているディレクトリに移動します。
    cd python-docs-samples/endpoints/getting-started
Go

サンプル API のクローンを作成するか、ダウンロードするには:

  1. GOPATH 環境変数が設定されていることを確認します。
  2. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
    go get -u -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. サンプルコードが含まれているディレクトリに移動します。
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

サンプル API のクローンを作成するか、ダウンロードするには:

  1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

  2. サンプルコードが含まれているディレクトリに移動します。
    cd php-docs-samples/endpoints/getting-started
Ruby

サンプル API のクローンを作成するか、ダウンロードするには:

  1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

  2. サンプルコードが含まれているディレクトリに移動します。
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

サンプル API のクローンを作成するか、ダウンロードするには:

  1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

  2. サンプルコードが含まれているディレクトリに移動します。
    cd nodejs-docs-samples/endpoints/getting-started

Endpoints を構成する

サンプルコードには、OpenAPI 構成ファイル openapi.yaml が含まれています。このファイルは OpenAPI 仕様 v2.0 に準拠しています。openapi.yaml をローカルマシンで構成してデプロイします。

Endpoints を構成するには:

  1. サンプルコードのディレクトリで openapi.yaml 構成ファイルを開きます。

    次の点にご注意ください。

    • この構成サンプルでは、host フィールドの近辺に表示されている行を変更する必要があります。openapi.yaml ファイルを Endpoints にデプロイするには、完全な OpenAPI ドキュメントが必要です。
    • サンプル openapi.yaml ファイルには、このチュートリアルでは不要な認証を構成するためのセクションが含まれています。YOUR-SERVICE-ACCOUNT-EMAILYOUR-CLIENT-ID の行を構成する必要はありません。
    • OpenAPI は言語に依存しない仕様です。利便性を考慮し、各言語の GitHub リポジトリの getting-started サンプルに同じ openapi.yaml ファイルが用意されています。
  2. host フィールドのテキストを Endpoints サービスの名前に置き換えます。次の形式で指定します。
    host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
    

    YOUR_PROJECT_ID は、実際の GCP プロジェクト ID に置き換えてください。次に例を示します。

    host: "echo-api.endpoints.example-project-12345.cloud.goog"
    

この echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog は、Endpoints サービスの名前です。これは、API にリクエストを送信するために使用する完全修飾ドメイン名(FQDN)ではありません。

Endpoints に必要な OpenAPI ドキュメントのフィールドについては、Endpoints を構成するをご覧ください。

次の構成手順をすべて完了し、IP アドレスを使用してサンプル API にリクエストを正常に送信できるようになったら、Endpoints の DNS を構成するを参照して、echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog を FQDN に構成する方法をご確認ください。

Endpoints 構成をデプロイする

Endpoints 構成をデプロイするには、gcloud endpoints services deploy コマンドを使用します。このコマンドでは、Service Management を使用してマネージド サービスが作成されます。

Endpoints 構成をデプロイするには:

  1. endpoints/getting-started ディレクトリ内にいることを確認します。
  2. 構成をアップロードしてマネージド サービスを作成します。
    gcloud endpoints services deploy openapi.yaml
    

その後で、gcloud コマンドが Service Management API を呼び出して、openapi.yaml ファイルの host フィールドで指定された名前でマネージド サービスを作成します。Service Management は、openapi.yaml ファイル内の設定に従ってサービスを構成します。openapi.yaml に変更を加えるときは、このファイルを再デプロイして Endpoints サービスを更新する必要があります。

Service Management でサービスの作成と構成が行われるとき、情報がデバイスに出力されます。openapi.yaml ファイル内のパスが API キーを要求していない、という警告は無視してかまいません。サービスの構成が完了すると、Service Management に、次のようなサービス構成 ID とサービス名を含むメッセージが表示されます。

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

前述の例では、2017-02-13r0 がサービス構成 ID で、echo-api.endpoints.example-project-12345.cloud.goog が Endpoiints サービスです。サービス構成 ID は、日付スタンプとそれに続くリビジョン番号で構成されます。openapi.yaml ファイルを同じ日に再度デプロイすると、サービス構成 ID のリビジョン番号が増えます。Endpoints サービス構成を確認するには、GCP Console で [Endpoints] > [サービス] ページに移動します。

エラー メッセージが表示された場合は、Endpoints 構成のデプロイのトラブルシューティングをご覧ください。

必要なサービスの確認

Endpoints と ESP を使用するには、少なくとも次のサービスが必要です。
名前 タイトル
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API
endpoints.googleapis.com Google Cloud Endpoints

ほとんどの場合、gcloud endpoints services deploy コマンドによってこれらの必須サービスが有効化されます。ただし、以下の状況では、gcloud コマンドが正常に完了しても必要なサービスが有効化されません。

  • Terraform などのサードパーティ製アプリケーションを使用していて、上記のサービスを含めていない場合。

  • 上記のサービスが明示的に無効にされている既存の GCP プロジェクトに Endpoints 構成をデプロイした場合。

必要なサービスが有効になっていることを確認するには、次のコマンドを実行します。

gcloud services list

必要なサービスがリストされない場合は、次のコマンドを使用してサービスを有効にします。

gcloud services enable SERVICE_NAME

SERVICE_NAME は、有効化するサービスの名前で置き換えます。

gcloud コマンドの詳細については、gcloud サービスをご覧ください。

API バックエンドをデプロイする

ここまでの手順で OpenAPI ドキュメントを Service Management にデプロイしましたが、API バックエンドを処理するコードはまだデプロイしていません。このセクションでは、VM インスタンス上で Docker を設定し、Docker コンテナで API バックエンド コードと ESP を実行する方法について説明します。

VM インスタンスに Docker をインストールする

Docker を VM インスタンスにインストールするには:

  1. 次のコマンドを実行して、プロジェクトのゾーンを設定します。
    gcloud config set compute/zone YOUR_INSTANCE_ZONE
    

    YOUR_INSTANCE_ZONE は、インスタンスが実行されているゾーンに置き換えます。

  2. 次のコマンドを使用して、インスタンスに接続します。
    gcloud compute ssh INSTANCE_NAME
    

    INSTANCE_NAME は、VM インスタンス名に置き換えます。

  3. Docker のドキュメントを参照して Docker リポジトリを設定します。VM インスタンスのバージョンとアーキテクチャに一致する手順に従ってください。
    • Jessie 以降
    • x86_64 / amd64

Docker コンテナで API と ESP を実行する

ESP は、ユーザーのバックエンド コードの前にある nginx ベースのプロキシです。受信トラフィックを処理し、認証、API キー管理、ロギングなどの Endpoints の API 管理機能を提供します。

サンプル API と ESP を Docker コンテナにインストールして実行するには:

  1. esp_net という独自のコンテナ ネットワークを作成します。
    sudo docker network create --driver bridge esp_net
    
  2. サンプル API を提供するサンプル エコーサーバーを実行します。
    Java
    sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-java:1.0
    
    Python
    sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-python:1.0
    
    Go
    sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-go:1.0
    
    PHP
    sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-php:1.0
    
    Ruby
    sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-ruby:1.0
    
    NodeJS
    sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-node:1.0
    
  3. あらかじめパッケージ化されたパブリック ESP Docker コンテナを実行します。ESP 起動オプションで、SERVICE_NAME を実際のサービス名に置き換えます。これは、OpenAPI ドキュメントの host フィールドで構成した名前と同じです。
    sudo docker run \
        --name=esp \
        --detach \
        --publish=80:8080 \
        --net=esp_net \
        gcr.io/endpoints-release/endpoints-runtime:1 \
        --service=[SERVICE_NAME] \
        --rollout_strategy=managed \
        --backend=echo:8080
    

    --rollout_strategy=managed オプションは、ESP がデプロイ済みの最新のサービス構成を使用するように構成します。このオプションを指定すると、新しいサービス構成をデプロイしてから 1 分以内に ESP が変更を検出し、自動的に使用します。ESP が特定の構成 ID でなく、このオプションを使用するようにしてください。 他の ESP オプションについては、ESP 起動オプションをご覧ください。

エラー メッセージが表示された場合は、Compute Engine の Endpoints をトラブルシューティングするをご覧ください。

詳細については、API バックエンドをデプロイするご覧ください。

IP アドレスを使用してリクエストを送信する

サンプル API と ESP が Compute Engine インスタンスで実行されたら、ローカルマシンから API にリクエストを送信できます。

API キーを作成し、環境変数を設定する

サンプルコードには API キーが必要です。リクエストを簡単にするために、API キーの環境変数を設定します。

  1. API に使用したのと同じ GCP プロジェクトの API 認証情報ページで API キーを作成します。別の GCP プロジェクトで API キーを作成するには、GCP プロジェクトでの API の有効化をご覧ください。

    [認証情報] ページに移動

  2. [認証情報を作成] をクリックして [API キー] を選択します。
  3. キーをクリップボードにコピーします。
  4. [閉じる] をクリックします。
  5. ローカル コンピュータで、API キーを貼り付けて環境変数に割り当てます。
    • Linux または Mac OS の場合: export ENDPOINTS_KEY=AIza...
    • Windows PowerShell の場合: $Env:ENDPOINTS_KEY="AIza..."

リクエストを送信する

Linux または macOS の場合

curl を使用し、前の手順で設定した ENDPOINTS_KEY 環境変数を指定して HTTP リクエストを送信します。IP_ADDRESS は、インスタンスの外部 IP アドレスで置き換えます。

curl --request POST \
   --header "content-type:application/json" \
   --data '{"message":"hello world"}' \
   "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"

上記の curl の各要素の内容は次のとおりです。

  • --data オプションは、API に送信するデータを指定します。
  • --header オプションは、データが JSON 形式であることを指定します。

PowerShell

Invoke-WebRequest を使用し、前の手順で設定した ENDPOINTS_KEY 環境変数を指定して HTTP リクエストを送信します。IP_ADDRESS は、インスタンスの外部 IP アドレスで置き換えます。

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

上記の例では、最初の 2 行はバッククォートで終わります。この例を PowerShell に貼り付けるとき、バッククォートの後にスペースがないことを確認してください。このリクエスト例で使用されているオプションについては、Microsoft のドキュメントの Invoke-WebRequest を参照してください。

サードパーティ製アプリ

Chrome ブラウザの拡張機能である Postman などのサードパーティ製アプリケーションを使用してリクエストを送信できます。

  • HTTP 動詞として POST を選択します。
  • ヘッダーで、キー content-type と値 application/json を選択します。
  • 本文で、次のように入力します。
    {"message":"hello world"}
  • URL では、環境変数ではなく実際の API キーを使用します。次に例を示します。
    http://192.0.2.0:80/echo?key=AIza...

API によって送信メッセージがエコーバックされ、次のようなレスポンスが返されます。

{
  "message": "hello world"
}

正常なレスポンスが返されなかった場合は、レスポンス エラーのトラブルシューティングをご覧ください。

これで Endpoints の API のデプロイとテストが完了しました。

Endpoints の DNS を構成する

API の Endpoints サービス名は .endpoints.YOUR_PROJECT_ID.cloud.goog ドメイン内にあるため、openapi.yaml ファイルで構成を少し変更するだけで完全修飾ドメイン名(FQDN)として使用できます。このようにすると、サンプル API にリクエストを送信するときに IP アドレスの代わりに echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog を使用できます。

Endpoints DNS を構成するには:

  1. OpenAPI 構成ファイル openapi.yaml を開き、次のスニペットに示されているように、ファイルのトップレベル(インデントやネストのないレベル)に x-google-endpoints プロパティを追加します。
        host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
        x-google-endpoints:
        - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
          target: "IP_ADDRESS"
    
  2. name プロパティの YOUR_PROJECT_ID を実際のプロジェクト ID で置き換えます。
  3. target プロパティの IP_ADDRESS を、サンプル API にリクエストを送信する際に使用した IP アドレスで置き換えます。
  4. 更新した OpenAPI 構成ファイルを Service Management にデプロイします。
        gcloud endpoints services deploy openapi.yaml
    

たとえば、次のように openapi.yaml ファイルを構成したとします。

    host: "echo-api.endpoints.example-project-12345.cloud.goog"
    x-google-endpoints:
    - name: "echo-api.endpoints.example-project-12345.cloud.goog"
      target: "192.0.2.1"

前述の gcloud コマンドを使用して openapi.yaml ファイルをデプロイすると、Service Management によって DNS A レコード echo-api.endpoints.my-project-id.cloud.goog が作成されます。これはターゲット IP アドレス 192.0.2.1 に解決されます。新しい DNS 構成が反映されるまでに数分かかる場合があります。

SSL を構成する

DNS と SSL の構成方法の詳細については、Endpoints で SSL を有効にするをご覧ください。

FQDN を使用してリクエストを送信する

サンプル API の DNS レコードが構成されたので、FQDN(YOUR_PROJECT_ID は実際のプロジェクト ID で置き換えます)と設定済みの ENDPOINTS_KEY 環境変数を使用してサンプル API にリクエストを送信します。
  • Linux または Mac OS の場合:
            curl --request POST \
                --header "content-type:application/json" \
                --data '{"message":"hello world"}' \
                "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"
  • Windows PowerShell の場合:
    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content

API のアクティビティを追跡する

API の活動を追跡するには:

  1. [エンドポイント] > [サービス] ページで API のアクティビティ グラフを確認します。

    [エンドポイント] の [サービス] ページに移動

    }
    グラフにリクエストが反映されるまでしばらくかかります。

  2. [ログビューア] ページで API のリクエストログを確認します。

    ログビューア ページに移動

API のデベロッパー ポータルを作成する

Cloud Endpoints Portal を使用してデベロッパー ポータルを作成できます。デベロッパー ポータルとは、サンプル API の操作に使用できるウェブサイトです。詳細については、Cloud Endpoints Portal の概要をご覧ください。

クリーンアップ

このチュートリアルで使用するリソースについて、Google Cloud Platform アカウントに課金されないようにする手順は次のとおりです。

  1. API を削除します。
    gcloud endpoints services delete SERVICE_NAME
    

    SERVICE_NAME は、実際のサービス名に置き換えます。

  2. GCP Console の [VM インスタンス] ページに移動します。

    [VM インスタンス] ページに移動

  3. 次のチェックボックスをオンにします。 削除するインスタンス。
  4. インスタンスを削除するには、[削除] () をクリックします。

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

OpenAPI を使用した Cloud Endpoints
ご不明な点がありましたら、Google のサポートページをご覧ください。