Bubble 外部サービス向け API workflow 構築の基本

みなさん、こんにちは！

今回は Bubble の Workflow API についてです！Workflow API は、過去の記事でも何度も取り上げてきましたが、今回は Workflow API の中でも、更に外部に公開する API workflow についてをフォーカスしていきたいと思います。

外部サービス向けの API workflow を構築することで、Data API と同様に Bubble のデータベースに格納されている情報を簡単に共有したり、逆に外部からのデータを受け取って、Bubble 内で処理することができるようになります。API workflow は Bubble の受信接続（Incoming connections）において、アプリケーション間のシームレスなデータ連携を実現するために必要不可欠な機能です。

Bubble の Data API については、以下の記事でもご紹介していますので、あわせてご参考ください。

blog.nocodelab.jp

なお、Bubble で API workflow を使用するには Starter プラン以上への加入が必要となりますので、ご承知おきください。

また、今回は外部サービスとして、一部の動作確認を Postman で行っています。

1. API workflow とは？
2. BubbleでのAPI開発
3. API workflow をサンプルアプリで動かしてみる
- 3.1. App➀：サーバー側の設定
- 3.2. App➁：クライアント側の設定
4. Bubble の Swagger ファイル
5. まとめ
6. 参考ドキュメント

1. API workflow とは？

API workflow は、アプリ内でスケジュールやトリガーしたり、API リクエストを通じて外部サービスからトリガーされるように公開することができる、サーバーサイドのワークフローです。

通常の Workflow タブで設定されるワークフローと異なる点は、以下の表のようになっています。

アクション	API workflow	Regular workflow
外部アプリケーションからトリガー可能	はい	いいえ
ページが閉じられても動き続ける	はい	いいえ
再帰的ワークフローをスケジュールできる	はい	いいえ
将来的に実行するようスケジュール可能	はいページを閉じても実行できる	はいただしページは開いたままにしておく必要がある
プライバシールールを	はい	いいえ
100%サーバーサイドで実行される	はい	いいえ

そして、今回は API workflow でも、外部公開としてエンドポイントを持つ API workflow の作成について取り上げていきます。具体的には API workflow の設定で「Expose as a public API workflow」のチェックをオンに設定したワークフローです。

なお、Bubble の API workflow とは、Backend workflows エディターで作成・管理するワークフローそのもののことですが、Bubble で使用される API に関する用語は、Bubble 独自の表現で、かつ似たような用語が沢山存在しますので、Bubble の公式認定試験の受験を検討されている方は一度整理しておくと良いですね。

用語	説明
Bubble API	Data APIとWorkflow APIの総称。
Data API	データベースへの直接リクエストを扱う Bubble API の部分
Workflow API	API workflow をトリガーするリクエストを扱う Bubble API の部分
API workflow	Backend workflows エディターで作成・管理するワークフローそのもの
Backend workflow	Backend workflows エディターで利用可能なさまざまなワークフローの総称。(API workflow、Database Trigger、Recurring event、Custom event)

Bubble における API 関連の用語を、より詳細に整理したい方は、以下ドキュメントをご参考ください。

manual.bubble.io

2. BubbleでのAPI開発

では、まず API workflow を作成するための準備から始めていきます。既に設定を理解されている方は読み飛ばしてくださいね。

2.1. 事前準備

まずは、API workflow が使用できるように、Settings > API > Public API endpoints にある「Enable Workflow API and backend workflows」のチェックボックスをオンに設定しておきます。

これで https://YOUR-APPNAME.bubbleapps.io/version-test/api/1.1/wf （開発環境）というWorkflow API root URL の使用と、Backend workflow の作成ができるようになりました。

API workflow は Backend workflows エディターで作成してきますので、ページ選択のドロップダウンから「Backend workflows」をクリックします。

なお、Backend workflows は、サーバーサイドで実行される内部処理のため、実画面を実装することはできません。

2.2 API workflow の作成

新しい API workflow を作成するには「New API workflow…」を選択します。

API workflow で設定する項目は、以下のような内容となっています。

項目	詳細
API workflow name	API workflow の名前。外部へ公開するエンドポイントとする場合は、スペースや特殊文字を含まないURLフレンドリーで、かつ一意の名前を持つ必要があります。
Expose as a public API workflow	外部に公開するには、このチェックボックスを「オン」に設定する必要があります。逆に Bubble 内部でしか使用しない API workflow の場合は、このチェックボックスを「オフ」にしておきます。
This workflow can be run without authentication	このチェックボックスを「オン」にすることで、認証なしで API workflow を誰でもトリガーすることが出来るようになります。
Ignore privacy rules when running the workflow	API workflow 実行時に、プライバシールールを適用させない場合は、このチェックボックスを「オン」に設定します。
Trigger workflow with	HTTPリクエスト時のメソッドを定義します。デフォルトでは「POST」メソッドを使用しますが、「GET」メソッドに切り替えることもできます。
Parameter difinition	「Manual definition（手動）」か「Detect request data（自動検出）」かを選択します。Manual definition は、「+Add a new parameter」でAPI workflow が受け取るパラメータを自身で設定します。Detect request data は、初期化用のエンドポイントを使用して Bubble が自動でパラメータを検出します。（GETの場合は手動のみ）
Response type	レスポンスはJSONオブジェクトとして返却するか、アプリ内のページにリダイレクトさせるかを選択できます。
Return a 200 if condition is not met	Response type で「JSON Object」を選択している場合に表示されます。ワークフローに設定した条件を満たさない場合、デフォルトでは 400 エラーを返します。この設定を変更し、代わりに 200 コードを返したい場合は、このチェックボックスを「オン」に設定します。
Redirection on success	Response type で「Page redirect (302)」を選択している場合に表示されます。ワークフロー終了時に Bubble がリダイレクトするページを選択します。ワークフローがデータを返す場合は、URLにクエリストリングとして追加されます。
Redirection on error	Response type で「Page redirect (302)」を選択している場合に表示されます。ワークフローが失敗したときにリダイレクトするページをここで選択します。statusCode とメッセージはクエリ文字列として URL に追加されます。

2.3. API workflow 実行時の認証方法

API workflow を実行する場合の認証方法には、以下の３種類があります。

認証無し
管理者として
ユーザーとして

1 の「認証無し」は「This workflow can be run without authentication」のチェックボックスを「オン」に設定することで「誰でも API workflow をリガーできる」状態にすることです。

2 の「管理者として」は、Settings > API > API Tokens で「Generate a new API token」のボタンをクリックして生成したトークンを使用することで認証を通す方法です。

3 の「ユーザーとして」は、実行時にユーザーを通常のログインと同じ方法で認証を行い、ユーザー毎に発行するトークンを使用して API workflow をトリガーできるようにする方法です。

API workflow を実装する際に適切な認証方法を選択することは、セキュリティ上においても、最初に検討するべき重要なステップです。具体的な設定方法は以下の記事の項「2. 認証方法」で解説していますので、ぜひ併せてご参考ください。

blog.nocodelab.jp

今回はユーザーとして認証したものを、項「3. API workflow をサンプルアプリで動かしてみる」で実装していきます。

2.4. パラメータの自動検出「Detect request data」の使い方

Bubble では、API workflow 実装時に外部サービスから受け取るパラメータを自動検出で設定することができます。

例えば、ユーザーの認証トークンを取得する「generate-api-token」という名前の API workflow を実装する場合、このワークフローではパラメータとして、ユーザーの「メールアドレス」と「パスワード」を必要としますが、これらのパラメータを自動で検出するには、以下のステップで行います。

Step1. Parameter difinition で「Detect request data」を選択して「Detect data」をクリックします。

Step2. 「Detecting Request Data」に表示されたエンドポイントをクリックでコピーして取得します。自動検出時の URL は Workflow API root URL に「API workflow 名/initialize」を加えた api/1.1/wf/API-WORKFLOW-NAME/initialize となります。

Step3. 外部サービス側（今回は Postman を使用します）で、送信したいパラメータ「email」と「pass」をリクエストボディに設定して、コピーしておいたエンドポイントに向かってリクエストを送信します。送信が成功すれば「The endpoint generate-api-token was sucessfully initialized」を取得します。

Step4. Bubble エディタでは「API Workflow Request data」で、外部から送信してきたパラメータを受け取っているため「SAVE」ボタンで保存すれば検出完了です。もし、検出したパラメータの型を変更したい場合は「Modify types」で修正することができます。

「Include headers in the detected data」のチェックを「オン」にすると、外部から送信されてきたリクエストヘッダー情報も検出に含めることができます。この設定は、クライアント側の環境（user-agent など）を取得したい場合などに便利です。下図は「Include headers in the detected data」の設定を「オン」にして、Postman から受け取った情報の例です。

3. API workflow をサンプルアプリで動かしてみる

では、実際に API workflow の動作を確認してみましょう。今回はサンプルとして、Bubble で2つのアプリを作成しました。ひとつが API workflow を実装したデータベースを持つ Bubble アプリ（App➀）、もうひとつが外部サービスを想定した App➀ の情報を取得するアプリ（App➁）です。

App➀はサーバー側、App➁はクライアント側として考えます。サーバー、クライアントの両方を作成して、データ送受信の設定を確認していきます。

実際のアプリは以下のリンクをご参照ください。

App➀：https://bubble.io/page?type=api&id=sample-createapi00&tab=tabs-2

App➁：https://bubble.io/page?type=page&name=index&id=sample-createapi01&tab=tabs-1

3.1. App➀：サーバー側の設定

今回は、POST メソッドを使用した認証用のトークン生成とトークン破棄、GET メソッドを使用したデータ取得の API workflow の合計3つを作成します。

No	API workflow	詳細
1	generate-api-token	認証ユーザーのトークン生成 API。通常のログインと同じ、メールアドレスとパスワードで認証を行い、レスポンスとしてトークンを返却します。
2	revoke-api-token	認証で使用したユーザーのトークンを破棄する API。
3	get-items	データベースから商品情報を取得する API。認証されたユーザーのみが実行できて、かつデータの取得にはプライバシールールが適用されます。

3.1.1. トークン生成

認証トークンの生成する場合、ログイン画面と同じ権限として考えますので、「This workflow can be run without authentication」のチェックは「オン」にして設定します。

なお上図では、前項で解説した「Detect request data」でパラメータを検出し作成していますので、ログインで指定する「Email」と「Password」は「Request Data’s body～」で取得します。

3.1.2. トークン破棄

トークンの破棄は、認証されたユーザーが実行できるアクションとなるので、「This workflow can be run without authentication」のチェックは「オフ」で設定します。

3.1.3. 商品情報取得

データベースから商品データを取得する GET メソッドを定義します。

この API workflow も認証されたユーザーのみが実行でき、またデータに関する権限は、Data type に設定されたプライバシールールを適用させるため「Ingore privacy rules when running the workflow」のチェックは「オフ」にしておきます。

データは「Return data from API」アクションを使って返却します。返却する Content-type は「Structured JSON」「Plain text」「Other content-type」を選択することができます。

今回は「Item」という名前の Data type から取得したデータを返却するようにデフォルトの「Structured JSON」を使用します。

Key には、呼び出し側で取得したい任意の名称を設定します。ここでは「Items」としました。

3.1.4. Data type について

App➀ のデータベースは「Item」という名前の Data type を持っていて、商品に関する情報を持っています。

3.1.5. プライバシールール

権限は、アプリにログインしたユーザーのみに一部のデータ参照を許可しています。データの作成者でなければ、作成者や作成日の情報は参照できません。

3.2. App➁：クライアント側の設定

App➁の方は外部サービスの役割として考えます。App➁はユーザーや商品に関するデータは持っていませんが、App➀の API workflow を呼び出すことで認証を行い、データベースの情報を取得します。

App➀の API workflow の呼び出しは API Connector プラグインを使って行います。

No	API Call	メソッド	詳細
1	GET Token	POST	generate-api-token の呼び出しを行う。
2	Revoke Token	POST	revoke-api-token の呼び出しを行う。
3	Get Items	GET	get-items の呼び出しを行う。

設定する API Name は任意のもので問題ありません。ここでは「Item Box」としました。また、リクエストヘッダーには「Content-Type: application/json」だけ設定しておきます。

3.2.1. GET Token

トークン生成の generate-api-token の呼び出しを行います。リクエストボディには、認証用のメールアドレスとパスワードを設定して Initialize を行います。

Returned values を受け取ったら SAVE で保存しておきます。

3.2.2. Revoke Token

次にトークン破棄を行う revoke-api-token の呼び出しを設定します。

リクエストヘッダーに「Authorization」を設定して Value には「Bearer+半角スペース+取得したトークン」を設定し、Initialize を行います。トークンは先程の GET Token の時に Returned values で取得した値を設定します。Initialize 時に取得した Returned values の値は GET Token の「Reinitialize call」ボタンの右側にある「Manually enter API response」をクリックすれば何度でも確認することができます。