oinume journal

Scratchpad of what I learned

grpc-gatewayでRESTful APIを実装する

背景

何かしらの理由でRESTでAPIを実装しなくてはいけない時に、JSONを直接扱うのは面倒くさい。具体的には、JSONをデシリアライズして内部のデータ構造にマッピングする処理を書くのが面倒だ。というわけで、grpc-gatewayを使ってProtocol Buffersを定義するだけでREST APIを実装できないかを検討してみた。

gRPCとは

gRPCはサービスの定義やリモートから呼び出されるメソッドの詳細な定義(引数や戻り値)をProtocol Buffers(以降Protobuf)を用いて定義する。つまりgRPCではProtobufがIDL(Interface Definition Language)として使われていて、protocというコマンドからProtobuf上のサービス・メソッド定義から各プログラミング言語のソースコードが生成できる。

grpc-gatewayとは

grpc-gatewayはprotocのプラグインとして実装されている。Protobufで定義されたサービスやメソッドの定義から、RESTful JSON APIをgRPCに変換するReverseProxyサーバーのソースコードを生成する。

例えば、以下のような定義を.protoファイルに書いておくと、 GET /users/{id} のRESTful APIのendpointを受け付けるサーバーのコードが生成される。

service Users {
    rpc GetUser(GetUserRequest) returns (User) {
        option (google.api.http) = {
            get: "/v1/users/{id}"
        };
    }
}

message GetUserRequest {
    string id = 1;
}

message User {
    string id = 1;
    string name = 2;
    string real_name = 3;
}

Protocol BuffersでAPIを定義してみる

では実際にprotoファイルに以下のAPIを定義してみる。RESTのendpointやgRPCのメソッドの命名についてはGoogleが公開しているAPIのスタンダードに沿っている。これはかなり参考になるドキュメントなので一通り読んでおくと良いと思う。Googleが提供しているAPIの70%以上はこのスタンダードに沿っているらしい。

API REST endpoint gRPC method
ユーザーの一覧取得 GET /v1/users ListUsers
ユーザーの単体取得 GET /v1/users/{id} GetUser
ユーザーの作成 POST /v1/users CreateUser
ユーザーの更新 PUT /v1/users/{id} UpdateUser
ユーザーの削除 DELETE /v1/users/{id} DeleteUser

サンプルのProtobufファイル users.proto

protocコマンドでgoのコードを生成

https://github.com/oinume/grpc-sample のリポジトリを $GOPATH/src/github.com/oinume 配下にcloneすることで、makeとgoがインストールされていば以下のコマンドで.protoファイルからgoのソースが生成できる。(ソースは proto-gen ディレクトリに生成される)

$ make setup
$ make proto/go

grpc-gatewayのサーバーを起動

最後に、サーバーの実装をビルドしてgrpc-gatewayのサーバーを起動してみよう。

ビルド

$ make
go build -o bin/grpc-sample github.com/oinume/grpc-sample/cmd

サーバーの起動

$ ./bin/grpc-sample

Listening on 5000
Starting gRPC server on 5001

5000番ポートでHTTPをLISTENする。バックエンドのgRPCサーバーは5001番ポートでLISTEN。

curlでREST APIを呼び出す

サーバーを立ち上げたら実際にcurlコマンドでREST APIのendpointにAPIリクエストを投げてみよう。例えば、新しいユーザーを作成するAPIは以下のコマンドを実行する。

$ curl -v -X POST -d '{"name": "oinume", "real_name": "kazuhiro oinuma"}' http://localhost:5000/v1/users | jq .

{
  "id": "12345",
  "name": "oinume",
  "real_name": "kazuhiro oinuma"
}

READMEに各APIのcurlでの呼び出し方法も書いてあるので参考にして欲しい。ちなみにサーバーの実装はただのモックなので、実際にどこかのDBにデータができるということはない。

サーバーの実装

https://github.com/oinume/grpc-sample/blob/master/server/server.go

これが今回のAPIサーバーのgRPCでの実装部分なのだが、あくまで生成されたgRPCのinterfaceを満たすようにGoのメソッドを定義すれば良い。メソッドの引数であるリクエストと戻り値のレスポンスのデータはProtobufで定義されたものがGoの構造体になっているので、そのまま使えば良い。

あとは、以下のようにgrpc-gatewayのためのおまじない的なコードを少し書くだけでRESTful API serverが出来上がる。

https://github.com/oinume/grpc-sample/blob/master/cmd/main.go#L64-L73

まとめ

このようにgrpc-gatewayを使うことで、RESTful APIを定義する上で手間だったJSONの変換部分を手で書く必要がなくなった。たくさんのAPIを実装するプロジェクトでは、ProtobufでAPI定義を書く必要が発生するとはいえ、手作業でJSON<->structの変換処理を書かなくて済むことが大きなメリットになるはずなので、興味がある人はぜひ試してみて欲しい。

Google Apps Scriptで外部のREST APIを呼び出す

Google Apps Script(GAS)から外部のREST APIを呼ぶには、UrlFetchApp.fetch というメソッドを呼び出せば良い。例えばJSONをリクエストのペイロードとして送る場合のサンプルコードはこんな感じ。

  var data = {
    'email': email,
    'subject': subject,
    'message': message,
  };
  var credential = PropertiesService.getScriptProperties().getProperty('FRESHDESK_CREDENTIAL');
  var options = {
    'method': 'post',
    'contentType': 'application/json',
    'headers': {
      'Authorization': 'Bearer ' + Utilities.base64Encode(String(credential))
    },
    'payload': JSON.stringify(data)
  };
  
  var response = UrlFetchApp.fetch('<api endpoint>', options);

fetchの第2引数に渡すoptions に以下のフィールドをセットしている。

  • method: HTTP method
  • contentType: application/json を指定
  • headers.Authorization でAPIのトークンを指定
    • ベーシック認証もできる
  • payload: リクエストのペイロードをJSONにしておく

また、上のコードのAPIのキーである credential はスクリプトのプロパティから値を取得している。ログインIDやパスワードなどをスクリプトの中に埋め込みたくない場合は環境変数みたいな感じで使えるスクリプトのプロパティを使うのが良いみたい(ソース)。

ハマったポイントとして、外部のAPIを呼び出す場合は、scopeに https://www.googleapis.com/auth/script.external_request がないと権限がないというエラーになるので注意。ファイル→プロジェクトのプロパティ→スコープ のタブで確認できる。スクリプトに対するスコープを再設定したい場合は、GUIだとプロジェクトを作り直してコードをコピペするしかなさそうな雰囲気。

自分は、Googleフォームで受けた問い合わせをFreshDeskというSaaSのシステムにAPIで投げて問い合わせを管理するということがやりたかったので、頑張ってスクリプトを書いた。これでGoogleフォームのインタフェースを使いつつ、バックエンドはちゃんとしたシステムで問い合わせを管理するということができるようになりましたとさ。

仕事で使える!Google Apps Script (仕事で使える!シリーズ(NextPublishing))

仕事で使える!Google Apps Script (仕事で使える!シリーズ(NextPublishing))

Google Driveの画像をブログに埋め込む

いっっっつもやり方を忘れるので未来の自分のためにメモ。

1.Google Driveで対象の画像ファイルを選択して開く

2.画像が表示されるので、右上のメニュー(縦の...のアイコン)から 新しいウィンドウで開く をクリックする。

3.開いたウィンドウの右上のメニューから アイテムを埋め込む をクリックすると iframe のHTMLコードが表示されるので、それをコピーしてブログに貼り付ける。

Googleフォームでメールアドレスを収集する場合にそのメールアドレスをGASから取得する

ググってもあまり出てこなかったのでメモ。Googleフォームで メールアドレスを収集する という設定をONにすると、フォームの回答を記録するSpreadsheetにメールアドレスが保存されるようになる。

これをGASのスクリプトからどうやって取るんだろうと思って調べてみたら、e.response.getRespondentEmail()というメソッドを呼ぶと取れるということがわかった。

試しにやってみたら見事にメールアドレスが取れた...! これでメアドを取るために独自のフィールドを足さなくて済む!

HerokuのName lookup timeoutが短すぎて困ってる話

最近HerokuのDynoで以下のようなエラーが出るようになった。アプリケーションから接続するMySQLのホスト名の解決が失敗しているっぽい。

Jan 18 08:20:25 ***** app/web.1:  {"level":"error","ts":"2018-01-17T23:20:24Z","msg":"InternalServerError","error":"errors.Internal: Failed to gorm.Open(): dial tcp: lookup ******** on 172.16.0.23:53: write udp 172.18.167.70:36855->172.16.0.23:53: i/o timeout

なんで?って思って /etc/resolv.conf を見てみたら

$ cat /etc/resolv.conf
options timeout:2
nameserver 172.16.0.23
search ec2.internal

↑のように timeout が2秒に設定されていた... 妥当な値かもしれないけど、ログにエラーが残るのが嫌だったのでIP直指定することで対応した... なんかいい方法ないかな。