4.3. API/ファンクション定義の登録¶
作成したコードをカスタムAPIから呼び出すためには、API定義とファンクション定義の登録が必要です。
4.3.1. API定義の作成¶
カスタム API 定義は Swagger 定義ファイルとして作成します。 Swagger 定義ファイルは YAML または JSON ファイルとして作成します。
hello-api.yaml という名前で以下の内容のファイルを作成してください。
swagger: '2.0'
basePath: /hello
produces:
- application/json
paths:
/sayHello:
get:
operationId: sayHello
summary: Hello world
basePath に指定された "hello" が API の識別子(API名)となります。
API内に任意の個数のオペレーションを定義することができます。 ここでは /sayHello サブパスに対して GET メソッドの API を定義しています。
operationId には、後述するファンクション名を指定する必要があります。
注意
basePath や path に指定するパス文字列について、いくつかの制約事項があります。 詳細は パス使用可能文字列の制約 を参照してください。
URI へのマッピング¶
BaaS サーバに対する実際の URI は以下のような対応となります。 /api/1/{tenantId}/api までは固定となっており、これ以下の階層を API 名と サブパスで定義できます。
http://{servername}/api/1/{tenantId}/api/{apiname}/{subpath}
上記例の sayHello の場合は、以下の REST API に対応します。
GET http://{servername}/api/1/{tenantId}/api/hello/sayHello
注釈
APサーバ側で context path を変更している場合は、 先頭の /api 部分が異なりますので、適宜読み替えてください。
basePath に関する注意事項¶
basePath の値は、CLI から API 定義をサーバに登録するときにのみ参照されます。 具体的には basePath の末端部分の名称が API 名としてサーバに登録されます。 (それより前の部分は何を記述しても無視されます)
したがって、以下の basePath はすべて API 名 "hello" として認識します。
- /hello
- /api/hello
- /api/1/tenant1/api/hello
注意
サーバに登録後は、basePath は一切参照されません。 URI は API名とサブパスのみから決定されます。
Swagger 定義と BaaS サーバの URI を完全に一致させたい場合は、 host に BaaS サーバのホスト名を、 basePath に "/api/1/{tenantId}/api/{apiname}" を指定してください。
パステンプレート¶
サブパスには、Swagger 仕様で定められるパステンプレートが使用できます。 パステンプレートは '{', '}' で記述します。
たとえば、サブパスに '/products/{id}' と記述すると、'/products/a' や '/products/b' などのリクエストにもマッチします。
テンプレートにマッチした部分の値は、パスパラメータとして clientContext に に引き渡され、ユーザコードから参照することができます。
clientContext については clientContext(Node.js) または clientContext(Java) を参照してください。
パス使用可能文字列の制約¶
basePath 末尾の API 名については、使用できる文字列に制限があります。
- 1文字目は1バイト英数字とアンダースコアのみが使用可能。
- 2文字目以降はこれに加えてハイフンが使用可能。
- API名は1文字以上です。
サブパスについては、'/' で区切られるそれぞれのパス要素について以下の制約があります。
- 各パス要素は固定文字列もしくはパステンプレートにします。
- パステンプレートはパラメータ名を '{', '}' を囲んだものです。
- 固定文字列、パラメータ名はともに、1文字目は1バイト英数字とアンダースコアのみが使用可能、2文字目以降はこれに加えてハイフンとピリオドが使用可能です。
- パステンプレートの前後に文字を追加することはできません。
なお、サブパスは必ず '/' で開始しなければならず、末尾は '/' であってはなりません。 ただし、例外的に '/' 1文字は許可されます。
サブパスの例をいくつか示します。
| パス | 判定 | 備考 |
|---|---|---|
| / | OK | |
| /a | OK | |
| /a/b/c | OK | |
| /a/{b.c}/_d | OK | |
| a/b | NG | 先頭が '/' でない |
| /a/b/ | NG | 末尾が '/' になっている |
| /a+b | NG | 使用禁止文字 |
| /.a | NG | 先頭にピリオドは使用不可 |
| /-a | NG | 先頭にハイフンは使用不可 |
| /a/{b | NG | パステンプレートが不正 |
| /a/b{c} | NG | パステンプレートが不正 |
4.3.2. ファンクション定義の作成¶
ファンクションは、カスタム API とコードのひも付け定義です。 ファンクションも YAML または JSON で記述します。
hello-function.yml という名前でファイルを作成してください。
Node.js の場合:
# ファンクション名
sayHello:
# コード指定
code:
bucket: CUSTOM_CODE
file: hello-1.0.0.tgz
# ハンドラ名
handler: sayHello
# 実行環境
env:
spec: node6
timeout: 600
memorySize: 256
Java の場合:
# ファンクション名
sayHello:
# コード指定
code:
bucket: CUSTOM_CODE
file: hello-1.0.0.tgz
# ハンドラ名
handler: com.example.Hello::sayHello
# 実行環境
env:
spec: java8
timeout: 600
memorySize: 512
"sayHello" がファンクション名となります。これは上述した API 定義内の operationId と合わせる必要があります。
注意
ファンクション名に指定できるのは1バイト英数字と '_' のみです。 記号は使用できません。
- code : 実行するコードを指定します。値は、前節で登録したコードに合わせます。
- bucket : コードを格納したファイルバケット名
- file : コードのファイル名。Node.js の場合はファイルの拡張子は "tgz"、Java の場合は "tgz"。
- handler: 実行するハンドラ名を指定します
- Node.js の場合は、export したハンドラ名を記述します。
- Java の場合は、"パッケージ名.クラス名::メソッド名" を記述します。
- env : コードを実行するときの環境を指定します
- spec : 実行環境のスペック名
- timeout : リクエストタイムアウト(秒)
- memorySize : Dockerコンテナに割り当てるメモリサイズ(MB) (Dockerレス構成時は無効)
スペック名はコードを実行する環境のスペックを一意に識別するもので、 起動する Docker コンテナ名やサーバプログラムの格納位置などの指定に使用されます。 スペック名は Cloud Functions サーバ側で設定した名称に合わせてください。
- Node.js の場合は、"node6" がデフォルトです。
- Java の場合は、"java8" がデフォルトです。
スペックの詳細は Cloud Functionsサーバ 利用手順書 の「設定」の章を参照してください。
注意
memorySize は Docker レス構成時は無効です。
また、memorySize は Docker コンテナに割り当てられるメモリサイズですので、 Node.js や Java VM の起動時オプションで指定するメモリサイズ指定とは関係ありません。
起動時オプションを変更したい場合は、サーバマネージャ設定ファイル内のコマンドライン指定を変更する必要があります。 詳細は、Cloud Functionsサーバ 利用手順書 の「サーバーマネージャ設定ファイル」を参照ください。
4.3.3. API定義とファンクション定義の登録¶
以下手順で API 定義とファンクション定義をサーバに登録します。
CLIを使用する場合¶
$ nebula create-api hello-api.yml
$ nebula create-function hello-function.yml
API・ファンクションの一覧はそれぞれ "nebula list-apis", "nebula export-functions" で確認できます。
API・ファンクションを削除したい場合はそれぞれ "nebula delete-api <API名>", "nebula delete-function <function名>" です。
デベロッパーコンソールを使用する場合¶
ブラウザを使用してデベロッパーコンソールから API定義、ファンクション定義を登録することも可能です。
デベロッパーコンソールにログイン後、画面左メニューの「API Gateway」、「Cloud Functions」⇒「Functions」から、それぞれ API定義、ファンクション定義の管理画面に入ることができます。
「追加」ボタンを押して、定義を登録します。定義ファイルの内容を画面上でコピー・ペーストで入力することで定義を投入できます。