一応ドキュメントがあるが、FMS にアクセスしないとみれない。
認証
流れとしては、
- アクセストークンを取得し、
- そのアクセストークンを使って実際の API コールを行う
ような使い方。
専用 API を使ってアクセストークンを取得する
Request Access Token API /user/auth に対して管理者のアカウント名とパスワードを使ってアクセストークンを取得し、それを使って API コールするというマニュアル通りの方法。
例えば、curl でトークン取得用の API コールを行う場合は下記の様な感じ。
% curl -k -XPOST -H 'Authorization: Basic <Base64 エンコード文字列>' https://fms.host.name/fmi/admin/api/v2/user/auth
返却された JSON 内に token として入ってくる。
{
"response": {
"token": "<アクセストークン>"
},
"messages": [
{
"code": "0",
"text": "OK"
}
]
}
アクセストークンを使う場合は Authorization: Bearer <アクセストークン> をリクエストヘッダーとして送る。
例えばデータベースの一覧を取得する API をアクセストークンを使って呼び出す場合はこんな感じ。
% curl -k -H 'Authorization: Bearer <アクセストークン>' https://fms.host.name/fmi/admin/api/v2/databases
という感じ。
ちなみに、 <Base64 エンコード文字列> には管理者の ユーザー名:パスワード を base64 でエンコードしたものを入れる。
例えば、管理者のユーザー名が adminuser で パスワードが adminpassword の場合、mac なら下記のような感じで取得した値 YWRtaW51c2VyOmFkbWlucGFzc3dvcmQ= を使う。
% echo -n 'adminuser:adminpassword' | base64
YWRtaW51c2VyOmFkbWlucGFzc3dvcmQ=
いきなり API コールを行いつつアクセストークンを取得する方法
API コールをするときに認証を行い、その流れでアクセストークンを取得することも可能。
例えばデータベースの一覧を curl を使って取得する場合はこんな感じ。（レスポンスヘッダーに返ってくるので -i をつける）
% curl -i -k -H 'Authorization: Basic <Base64 エンコード文字列>' https://fms.host.name/fmi/admin/api/v2/databases
レスポンスヘッダー x-fm-access-token にアクセストークンが返ってくるので、次回以降はそのトークンを使って実行すれば良い。
HTTP/2 200
date: Tue, 05 Apr 2022 07:29:08 GMT
server: Apache
x-frame-options: SAMEORIGIN
x-powered-by: Express
x-fm-access-token: <アクセストークン>
・・・
API コールすると 401 エラーになる場合
こうして見ると、普通にユーザー名とパスワードで API コールできるように見えるので、アクセストークン取得せず都度認証して APIコールしようと思ってしまうが、そんな感じで使ってると下記の様に 401 エラーになる。
{
"response": {},
"messages": [
{
"code": "956",
"text": "Maximum number of Admin API sessions exceeded"
}
]
}
Maximum number of Admin API sessions exceeded
なので、Admin API のセッション数の上限を超えたということだと思うが、この状態になると発行済のアクセストークンを使っての API コールしか受け付けなくなる。
既存の Admin API セッションを無効にするには Invalidate Access Token API コールを使うしかないと思うが、下記の様な URI なので、そもそもアクセストークンを控えてないとどうしようもない。
/fmi/admin/api/v2/user/auth/<アクセストークン>
そのため、アクセストークンを控えていない状況下でこのエラーに遭遇したら、15分間待って既存のアクセストークンが無効になったら再度トークンの取得を行う。
FileMaker Admin API では、アクセストークンを使用してホストへの接続を定義します。トークンは Invalidate Access Token (アクセストークンの無効化) 呼び出しを使用して無効にされるか、またはそのトークンを指定した最後の呼び出しから 15 分経過するまで有効です。(トークンが有効な間は、そのトークンを指定して呼び出しを行うたびにセッションタイムアウトカウンタがゼロにリセットされます。)
https://help.claris.com/ja/admin-api-guide/content/authentication-server.html
というわけで、大人しくアクセストークンを取得して Admin API をコールするような運用をした方がよさそう。