IBM Cloud FunctionsでAPIを作成する

はじめに

IBM Cloud Functions上に作成したActionを、APIとして呼び出す方法にはいくつかあります。
WEBアクションを有効にするのが一番お手軽ですが、指定出来ることが少なく、
APIゲートウェイを使用するの若干手間がかかりますが、より複雑な指定が可能になります。

以下では、それぞれの方法での作り方について、覚書としてまとめます。

サンプルのアクション

APIとして呼び出して実行するサンプルのアクションは次の通りです。
パラーメータとして渡されたnameに対して、Hello name!を返します。
nameの指定がなかった場合は、Hello Someone!を返します。

function main(params) {
    let name = (params.name) ? params.name : 'Someone';
	return {message : 'hello '+name+'!' };
}

方法1.Webアクション

一番簡単な方法は、Webアクションを有効にすることです。
アクション名横の「Web Action」をクリックします。

「Enable as Web Action」にチェックを入れて、Saveします。

下のURLがAPIの呼び出し先となります。
Webアクションが対応しているHTTPメソッドは、GET,POST,PUT,PATCH,DELETEになります。
注意: 上記URLを呼び出しても上手くいかない場合は、末尾に.jsonを付けて呼び出して下さい。

呼び出し結果は次のようになります。

$ curl -X GET https://jp-tok.functions.cloud.ibm.com/api/v1/web/XXXXX/default/testAction.json
{
  "message": "hello Someone!"
}
curl -X GET https://jp-tok.functions.cloud.ibm.com/ap/v1/web/XXXXX/default/testAction.json?name=Smith
{
  "message": "hello Smith!"
}

この方法の欠点は、トークン認証の仕組みがないので、URLを知っていれば誰でも実行できてしまう点です。

方法2.IAMトークンを使ったREST API

IAMトークンを利用すれば、APIの実行に認証の仕組みを導入できます。
IBM CloudのIAMトークンの取得方法はいくつか存在しますが、ここでは、サービスIDを使います。
他の方法は、こちらの記事を参考にして下さい。
https://qiita.com/testnin2/items/3a4ca8a1a2b79b713c48

サービスIDのAPIキーの取得

「管理」>「アクセス(IAM)」>「サービスID」から、API呼び出ししたいアクションがデプロイされている、Cloud Functionsの名前空間を選択します。
「作成」ボタンが有効でない場合は、右上のメニューからロックを解除します。

ここで、対象の名前空間のAPIキーを作成します。

IAMトークンの取得

サービスIDのAPIキーを取得したら、次のページを参考に、curlをコピペしてきて実行します。
https://cloud.ibm.com/docs/iam?topic=iam-iamtoken_from_apikey&locale=ja

curl -k -X POST \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Accept: application/json" \
  --data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
  --data-urlencode "apikey=<apikey>" \
  "https://iam.cloud.ibm.com/identity/token"

次のようなjsonが帰ってくるので、access_tokenの値を使用します。

{"access_token":"XXXXX","refresh_token":"XXXXX","token_type":"Bearer"}

IAMトークンを使ってAPI実行

WebアクションのURLを確認したページに、同じくIAMを利用する場合のURLが記載されています。
基本的に記載のcurlをそのまま実行すれば、アクションが実行されます。

返ってきたjsonのresponseの中に実行結果が含まれています。

  "response": {
    "result": {
      "message": "hello Someone!"
    },
    "size": 28,
    "status": "success",
    "success": true
  }

この方法の欠点は認証の仕組みがあるものの、IAMのトークンの有効期限が60分なので、再取得する必要がある点です。
参考：https://cloud.ibm.com/docs/iam?topic=iam-iamtoken_from_apikey&locale=ja
また、2019年11月現在、-dなどで、パラメータを渡しても上手く動作しないようです。
参考：https://stackoverflow.com/questions/56616014/how-to-fix-error-parameter-name-when-using-ibm-cloud-functions-rest-api

方法3.APIゲートウェイ

APIゲートウェイを使う方法は、これまでの方法よりも複雑な指定が可能になります。

• APIのパスの指定
• HTTPメソッドの指定
• 複数のアクションを1つのAPIとしてラップ
• レート制限の導入
• APIキーと秘密鍵による認証
• OAuthによる認証

など、他にもありますが、ここでは単純にAPIキーを発行して、外部ユーザーがIBM Cloud Functionのアクションを、APIとして実行出来る状態にします。

APIの作成

Cloud Functionsのトップから、「API」を選択して、「Creat Cloud Functions API」を選択します。

API情報の設定

APIゲートウェイでは、WebアクションやIAMを使う方法よりも、多くのことが設定可能です。
ここでは、外部から実行するために、基本的な設定のみ行います。

API basics

APIの名前とAPIのベースのパスを指定します。

Operations

呼び出すアクションと、呼び出し先のパス、呼び出す際のHTTPメソッドなどを指定します。

複数のパス・メソッド・アクションを指定して、1つのAPIとしてラップすることもできます。

Application authentication

APIの認証の仕組みを指定します。認証なし・APIキーのみ・APIと秘密鍵の3種類が指定できます。

Rate limiting

レート制限の設定をします。ここでは、1秒間に1000回までとしています。

APIキーの取得

設定が済み、APIを作成したら、APIキーを取得します。(最大5つまで作成可能です。)
「共有」から「Sharing Outside of Cloud Foundry organization」から外部ユーザー用のAPIキーを取得します。

API Portal Linkから、このAPIの簡単なドキュメントが参照できます。
ただし、2019年11月現在IAMの名前空間では利用できません。
補足のCF-basedの名前空間の作成方法を参考にして下さい。

(参考)
APIの認証設定で秘密鍵を指定した場合は、内部ユーザー向けの「Sharing within Cloud Foundry organization」から秘密鍵が取得できます。

APIの実行

APIキーを取得したら、Application authenticationの欄にしたがって、ヘッダーにAPIキーを入れて、Operationsの通り、HTTPメソッドを実行します。
ルートのURLは、「サマリー」から確認できます。

上記で設定した情報は次の通りでした。

セクション	設定項目	設定値
Operations	パス	/test
Operations	HTTPメソッド	GET
Application authentication	APIキーパラメータ名	X-IBM-Client-Id

したがって、次のようなcurlで実行し、次のような実行結果となります。

$ curl -X GET https://XXXXX.jp-tok.apigw.appdomain.cloud/API-TEST/test \
 -H 'X-IBM-Client-Id:XXXXX'
{
  "message": "hello Someone!"
}

$ curl -X GET https://XXXXX.jp-tok.apigw.appdomain.coud/API-TEST/test?name=Smith \
 -H 'X-IBM-Client-Id:XXXXX'
{
  "message": "hello Smith!"
}

注意: 上手く実行されない場合はWEBアクションを有効にしてみて下さい。

[補足]CF-basedの名前空間の作成

「管理」>「アカウント」から「Cloud Foundryの組織」を選びます。
既に存在するCloud Foundryの組織を選ぶか、「作成」から新規作成を行います。

「スペースの追加」から新しく名前空間を作ります。

注意: シドニーはIBM Cloud Functionsでは使用できないので、米国南部(ダラス)などを選んで下さい。