皆さん、ごきげんよう！！
今回は、Bubbleのプラグイン構築におけるAPI接続について解説をしていきます。そもそもAPIとは簡単に説明すると、外部のサービスやソフトウェアの一部を共有するための窓口になります。APIを通じてBubbbleのプラグイン構築を自らしていきたい人には特におすすめの記事になっているので、是非最後までご覧になってみてください。
この記事の目次
概要
APIコールは、外部サービスからデータを取得したり、サービス側のアクション(メッセージの送信、カードのチャージなど)をトリガーするための方法です。通常 、最初のタイプのコールはGETリクエストで、2 番目のタイプのコールはPOSTリクエストです。呼び出しには通常何らかの認証が必要で、サービスは誰が呼び出しているかを識別します 。このような呼び出しはPluginエディタの API タブで追加します。ここでは、呼び出しの認証方法や、どの呼び出しをデータソースとして使用するか、アクションとして使用するかを定義します。
今回は、iTunes APIの呼び出しの実装例を見ていきます。
ほとんどのAPIはいくつかの標準に従っています。しかし、API接続の実装はAPIによって異なる場合があり、もし問題が発生した場合には、APIプロバイダに連絡を取ったり、フォーラムで助けを求めたりすることをお勧めします。
認証
呼び出しの設計は、実行モードで呼び出しに署名する認証メソッドから始まります。認証はいくつかの標準的な方法で行うことができます。いくつかのキーを使ってAPI接続を構築しているときはいつでも、テストのために実際のキーを入力する必要があることに注意してください。これらのキーがプラグインを使うユーザーに送られることはありませんが、ユーザーはエディタのプラグインタブに自分のAPIキーを入力しなければなりません。
認証なし
呼び出しには何も追加されていないか、カスタムパラメータやハンドラを使って認証を処理しています。自分で認証を処理するよりも、より安全な接続のために、Bubbleの組み込みの認証システムを使用することをお勧めします。
URLの秘密鍵
URLに鍵が追加され、エディタで鍵名を変更することができます。
ヘッダ内の秘密鍵
すべてのリクエストのヘッダにキーが追加されます。これは前のオプションと非常に似ています。多くの場合、ヘッダは Authorization.KEY のようになりますが、必要に応じて Authorization という名前をカスタマイズすることができます。KEY のようになりますが、必要に応じて Authorization という名前をカスタマイズすることができます。
HTTP の基本的な認証
HTTP Basic Authプロトコルにしたがって、ユーザ名/パスワードがリクエストごとに送信されます。
Oauth2のパスワードの流れ
パスワードとユーザー名は、トークンを取得するために使用されます。トークンは、エディタに入力する必要のあるエンドポイントを呼び出すときに返されます。エンドポイントはAPIドキュメントに記載されています。ドキュメントで「token」または「OAuth Bearer token」を検索してください。
Oauth2 カスタムトークン
このフローはパスワードのフローに似ていますが、上記の標準的なアプローチに従っていない場合に備えて、トークンを返す呼び出しを自分で定義することができます。トークンはベアラートークンとしてコールに追加され、必要に応じて自動的に更新されます。トークンを機能させるためには、トークンはaccess_tokenとexpires_inの2つのキーを持つオブジェクトとして返されなければならないことに注意してください。
Oauth2のユーザーエージェントフロー
このフローは、ユーザーに代わってAPIを利用する際に、ほとんどのサービスが接続する方法です（Facebook、Pinterest、Googleなど）。これにより、APIを使用する際にユーザーのデータ（Facebookのプロフィール名など）にアクセスできるようになります。このようなサービスを設定するには、編集モードで認証された呼び出しをしたり、呼び出しを初期化したりするために、自分のアカウントで認証する必要があるため、いくつかの手順が必要になります。
通常は、認証したいサービスの「アプリ」を設定することから始めます。このサービスは、クライアントIDとアプリがサービスと通信するために使用する秘密を設定した後に提供します。
まず、トークンとユーザーIDを取得するために必要ないくつかの情報とエンドポイントを入力する必要があります。このエンドポイントは、トークンを生成するために使用され、サービスを使用してユーザーのIDを取得します。これらの情報はすべてAPIのドキュメントに記載されています。このようなドキュメントを見るときは、SDKなしのセクションを探すことをお勧めしますが、その中のweb/HTTPのセクションを探すことをお勧めします)。
・スコープ: 各Oauth2プロバイダは、ユーザーに求めるパーミッションのレベルを定義するスコープを入力する必要があります。読み取り専用、書き込み、メッセージの送信などが可能です。
・ログインダイアログのリダイレクト: これは、アプリを認証するためのサービスにユーザーを連れて行くURLです(そしておそらくサービスに最初にログインします)。多くの場合、https://www.facebook.com/v2.8/dialog/oauthのようになります。
・アクセストークンエンドポイントとは、一時的なコードからアクセストークンを取得するためにサーバー側で使用するURLのことです。Facebookの場合は https://graph.facebook.com/v2.8/oauth/access_tokenです。
・ユーザープロファイルエンドポイントは、一度認証されると、現在のユーザーのプロファイルを取得するために使用する URL です。これには ID と通常は電子メールが含まれます（サービスが API を介して電子メールを提供しない場合を除く）。Facebookの場合、このようなURLはhttps://graph.facebook.com/v2.7/meです。場合によっては、前のURLのレスポンスのトップレベルでIDが返ってこなかったり、’id’とは異なるキーを持っていたりする場合は、エンドポイントボックスの下の2つの設定で上書きすることができます。
Spotifyの認証はこんな感じです。
Oauth2 User-Agent Flowの場合、通話を初期化できるようにするには、自分の個人アカウントで認証する必要があります。ボタンを押すと、フォローを通過するように促され、プロセスを通過したらトークンを保存します。ここでも、サービスとあなたの個人的なアイデンティティと資格情報は、あなたのプラグインを使用しているユーザーと共有されません.
JSONのWebトークン
一部のサービスでは、より高度なプロトコルを使用してスコープとパーミッションを処理しています。これは通常、BoxやGoogle Cloudのようなエンタープライズタイプのサービス向けです。このようなサービスで認証を行うには、スコープ、サービスアカウントの設定に使用するメール、トークンを返すエンドポイントを入力する必要があります。また、接続を設定するためにサービスが提供しているRSA秘密鍵も入力する必要があります。鍵は、’—–BEGIN RSA PRIVATE KEY—–‘ と ‘—–END RSA PRIVATE KEY—–‘ を含むフォーマットにする必要があることに注意してください。
共有ヘッダ
認証を行うものを含むすべてのコールに共有ヘッダを追加する必要がある場合は、 次のセクションで定義します。ここで設定する値は ‘hidden’ または ‘secret’ にすることができることに注意してください。非表示の設定はプラグインビルダーがハードコーディングしたもので、プラグインのユーザはこのキーを入力しません。ほとんどの場合、これはコンテンツタイプなどの技術的なヘッダーに使用されます。シークレットタイプは、プラグインのユーザーにプラグインタブでキーを入力するように促します。
呼び出しエンドポイントの定義
認証情報を適切に入力したら、呼び出しの設定を開始できます。リクエストメソッドを定義し、ヒットするエンドポイントをコピーし、ユーザーが入力しなければならないさまざまなパラメータを定義することから始めます。URL の一部を[and]の間に入力すると、その間の値がパラメータになることに注意してください。
パラメータにはいくつかのタイプがあります: 公開、非公開、秘密です。
・パブリックパラメータは、ユーザーがコールレベルで変更することができます 。
・隠しパラメータはプラグインビルダーのためのもので、プラグインを使用しているユーザには公開されません。例えば、エンコーディングの種類などです。
・シークレットパラメータはキーなどに適しています。ユーザーはエディタのプラグインタブでこれらを入力します。
呼び出しを定義したら、Bubbleで使えるようにするために初期化する必要があります。APIコールは5種類のデータを返すことができます。
JSON
これはREST APIの最も典型的なケースで、キーと値を持つオブジェクトを返します。このタイプを選ぶと、呼び出しの初期化後にポップアップで各キーのデータタイプを選ぶように促されます。呼び出しを初期化すると、Bubbleは実際のリクエストを行い、返されたデータを解析します。
XML
APIによっては、レスポンスをXMLとして返すものもあります。多くの場合、これをJSONオブジェクトに変換することができます。そのようなAPIを扱っている場合は、XMLを使用してJSONオブジェクトとしてデータを取得し、上記のフローを実行します。なお、すべてのXMLレスポンスがJSONとして変換できるわけではありません。Bubbleがそれに失敗した場合は、エラーメッセージが表示されます。
画像
APIによっては、生の画像をレスポンスとして返すものもあります。例えば、<img>タグで使用できるURLであったりします。このような場合、BubbleのAPIコールは、Image要素で使用できる画像や、ページの背景として使用できる画像を返します。
テキスト、数字
API が文字列または数値を返す場合 、このオプションを選択する必要があります。
API が公開された後に型を変更すると後方互換性がなくなる可能性があることに注意してください。
日付範囲、数値範囲
これらはBubbleのデータ型ですが、API Connector ではこれらのデータ型はサポートしていません。API Connector を使用して日付の範囲または数値の範囲に使用する場合、回避策としては、日付/数値を 2 つの別々のフィールドとして送信するか、日付/数値の 2 つの項目のリストとして送信し、アプリ内の他の場所で範囲としてフォーマットすることです。API Connector を使用して他の Bubble アプリから範囲データをクエリする場合は、代わりにApp Connector を使用することをお勧めします。
まとめ
今回の記事では、Bubbleのプラグイン構築において、API接続法について細かく説明していきました。注意すべき点に関しては太文字にしておきました。多少わかりにく部分もあるとは思いますが、焦らずゆっくりAPI接続の操作していきましょう。そして、様々なAPIを活用し、自分だけのBubbleプラグインを構築していきましょう。
ここまでご覧頂き、ありがとうございました。
