クラウド同上

14min

App Engineを使って簡単！迅速！にWebAPI開発をしよう

Author
sano
sano (他の投稿記事を見る)
Lv：3　Exp：3125

サーバーサイドの開発をメインとしたJavaおじさんです。
注意
この記事は2019年5月29日に更新されたもので、内容が古い可能性がありますのでご注意ください。

会社で新しいプロジェクトが立ち上がってWebAPIを作ることになったけど作り方がわからない。WebAPIつくってみたいけど大変そうだな。
あと、作ったあとのドキュメントのメンテナンスとか面倒だし何かいい方法ないかな。

こんな悩みに答えます。

今回はWeb APIの作り方として、 App Engine上で稼働する「Cloud Endpoints Framework for Java」を使って解説します。また、ドキュメントのメンテナンスとしてGCP上で確認できるデベロッパーポータルの解説をします。

開発プラットフォームにGoogle Cloud Platform（以下、GCP）を使っていきます。

WebAPIの作り方

それでは早速WebAPIをつくっていきましょう。

今回作るWebAPIはREST APIに則って単純なリクエストを受け取りメッセージを返すようなAPIを目指します。

ポイントをまとめるとこんな感じです。

  • Cloud Endpoints Frameworkとは
  • 開発の準備
  • コードの実装
  • 動作の確認

Cloud Endpoints Framework for Javaを使いましょう

Web API開発にはフレームワークを使って開発していきましょう。
フレームワークを使うことで技術的なリスクや煩わしさを減らすことができるので、実装に集中することができます。

今回はCloud Endpoints Framework for Javaで開発を進めていきます。

Cloud Endpoints Frameworkとは…
App Engineの標準環境であるPython、Javaのランタイムに対応するWebフレームワークです。HTTPリクエストとレスポンス通信の処理を行い、リクエストのURLを適切にコード内の関数にルーティングします。また、戻り値をJson形式に自動変換してレスポンスを送信します。

小難しいこと書いてありますが、HTTP等の通信を特に気にしなくても良しなにアクセス処理してくれますよ。ということです。

開発の準備

開発の準備をしていきます。

今回はGCPを使った開発ですので事前にGCPプロジェクトの準備（https://www.apps-gcp.com/gcp-startup/）を行ってください。

開発ツールは以下を使用します。
・Java 1.8
・Maven 3.0
・Git
・gcloudコマンド

gcloudはCLIツールです。App Engine アプリケーションのデプロイなどの作業を行うために使います。こちら（https://cloud.google.com/sdk/docs/quickstarts?hl=ja）からインストールをできます。

コードを書きましょう

それでは、実際にコードを書いていきます。

３ステップで作っていきます。

ステップ1： ベースとなるアプリケーションをgit cloneします
ステップ2： リクエストを受け付けるプログラムを書きます
ステップ3： 設定ファイルを変更します

具体的にプログラムで書かなけれならいないところとしては、「リクエストを受け付けるところ」です。

ステップ１

Googleが公開している雛形アプリケーションを取得します。

$ git clone https://github.com/GoogleCloudPlatform/java-docs-samples
$ cd java-docs-samples/appengine-java8/endpoints-v2-skeleton

ステップ２

雛形アプリケーションに用意されている下記のファイルを開きます。

・src/main/java/com/example/skeleton/MyApi.java

クラスの中身は空っぽですね。
ここにリクエストに応じたメソッドを追加していきます。

下記のように編集して保存してください。

package com.example.skeleton;

import com.google.api.server.spi.config.*;
import javax.inject.Named;

@Api(name = "myFirstApi", version = "v1")
public class MyApi {

    @ApiMethod(httpMethod="get", path="/hello/{name}")
    public Message hello(@Named("name") String name) {
        return new Message("Welcome! " + name);
    }

    class Message {
        private String message;
        public Message(String message) {
            this.message = message;
        }
        public String getMessage() {
            return message;
        }
    }

}

これで、 /hello/文字列 へGETアクセスをするとhelloメソッドの処理が行われるようになります。

プログラムの解説です。

メソッド

処理を行いたいメソッドに対して @ApiMethod アノテーションを付与することでリクエストとプログラムをマッピングすることができます。

  • アノテーションの引数
    • httpMethod
      HTTPメソッド（GET, POST, PUT, DELETEなど）を指定します。
    • path
      リクエストのURIを指定ます。中括弧で囲むことで変数として扱うことができます。
メソッド引数

パスに含まれる変数はメソッドの引数に @Named アノテーションを付与することで取得することができます。パスのみならずクエリーパラメータも同様に取得できます。

メソッド戻り値

Javaオブジェクトを返却するだけで大丈夫です。フレームワークが自動でJSONへパースしてくれるので特に操作は必要ありません。

ステップ３

アプリケーションの設定ファイルを変更します。プロジェクト直下にあるpom.xmlを編集します。

・pom.xml

YOUR_PROJECT_ID.appspot.com

YOUR_PROJECT_IDを自身のGCPプロジェクトIDに変更して保存してください。

コードは以上です。

アプリケーションの確認

それでは作ったアプリケーションの動作を確認していきましょう。

５つのステップで確認します。

ステップ１： アプリケーションのビルド
ステップ２： APIドキュメントの生成
ステップ３： Web API のデプロイ
ステップ４： Webアプリケーションのデプロイ
ステップ５： 動作確認

自分が書いたコードが想定した通り動作するかの検証します。

ステップ１

まずは、プロジェクトのビルドを行います。
アプリケーションのRootフォルダで以下のコマンドを実行します。

$ mvn clean package

BUILD SUCCESSメッセージが表示されたら成功です。

[INFO] ------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------
[INFO] Total time:  16.486 s
[INFO] Finished at: 2019-05-23T16:52:00+09:00
[INFO] ------------------------------------------

ステップ２

次にOpen APIの構成ファイルを生成します。
以下のコマンドを実行して、openapi.json という名前の OpenAPI ドキュメントを生成します。

$ mvn endpoints-framework:openApiDocs

こちらも先ほどと同じようなBUILD SUCCESSメッセージが表示されれば成功です。

target/openapi-docs/openapi.json が生成されていることを確認してください。

Open APIとは
REST API を定義するための定められた業界標準の仕様です。

ステップ3

前のステップで生成した OpenAPI 構成ファイルをデプロイします。

$ gcloud endpoints services deploy target/openapi-docs/openapi.json

これにより、新しい Endpoints サービスが作成され、YOUR_PROJECT_ID.appspot.com という形式の名前が付けられます。正常に完了すると、サービス構成 ID とサービス名を示す次のような行が表示されます。

Service Configuration [2019-05-24r0] uploaded for service [ca-sano-test.appspot.com]

ステップ4

いよいよGCP環境にアプリケーションをデプロイします。

$ mvn clean appengine:deploy

しばらく待ち、次のうようなメッセージが表示されれば成功です。

[INFO] GCLOUD: Deployed service [default] to [https://ca-sano-test.appspot.com]

ローカル環境で動かす
今回はGCP環境へデプロイしましたが、実際の開発時にはロカール環境で動作確認しながらの開発になるかと思います。以下のコマンドでローカル環境で起動できます。
$ mvn clean appengine:run

ステップ５

最後のステップとしてアプリケーションにリクエストを投げてみしょう。
YOUR_PROJECT_IDは自身のプロジェクトIDに変更してください。

$ curl https://YOUR_PROJECT_ID.appspot.com/_ah/api/hello/Taro

注）/_ah/api/がURIに含まれていますが、これはフレームワークがデフォルトで設定してるbasePathです。

次のようなレスポンスが帰って来れば成功です。

{
    "message": "Welcome! Taro"
}

ドキュメントは自動生成でメンテナンスする

ここまでコードを書いて動作を確認してきました。

チーム開発をしている場合、作ったWeb API をフロント開発者などに共有する必要があるかと思います。

もし、手書きのドキュメントを書いていたら、コードの変更のたびに開発者が手で編集が必要になります。コードがそのままドキュメントにるのが理想です。

実はこれまでの工程で、自動ドキュメント生成の準備は整っています。

ドキュメントを確認してみましょう。

デベロッパーポータルで確認する

GCPコンソールのメニューから[エンドポイント] → [デベロッパー ポータル]を開きます。

[ポータルを作成] をクリックします。

５〜１０分かかるのでお茶でも飲みながら待ちましょう。

作成できました。
URLをクリックして作成されたデベロッパーポータルを確認しましょう。

途中、アクセス認証のステップがあると思います。

デベロッパーポータルのトップページが確認できたらサービス名（YOUR-PROJECT-ID.appspot.com）をクリックして開いてみましょう。

見ることができましたね。

これで作ったWebAPIをチームで共有することができ、メンテナスフリーでドキュメント化も可能になります。

まとめ

App EngineでWeb APIを作る方法を解説してきました。

煩わしいコードを書かずに簡単にWebAPIを作ることができたのではないでしょうか。

今回は単純なAPIでしたがEndpoints Frameworkでは認証やアクセス制御もできます。
デベロッパーポータルを使えばドキュメントがメンテナンスフリーになるのでチーム開発に是非役立ててください。

それでは、よきWeb API開発ライフを！

前の記事

AutoML Natural Language を使って文豪っ…

次の記事

Firebase Hosting + Firebase Aut…