API Plugin Advanced Tutorial

このシリーズの前編では、API Plugin とその基本的な使い方について学びました。まだ読んでいない場合は、この記事を続ける前にぜひ確認してみてください。後編では、さらに実践的な例をいくつか見ていきます。

例1: インタラクションに応じてリクエストをカスタマイズする

前回の記事で扱った基本例はシンプルでした。毎回同じ URL にリクエストを送り、そのレスポンスを使っていました。しかし、実際には毎回リクエスト URL をカスタマイズする必要があることがよくあります。この例では、任意の単語を入力して API に渡し、その定義を取得する辞書検索の体験を作ります。

ここでは Free Dictionary API を使います。API リクエスト URL は次のようになります:

https://api.dictionaryapi.dev/api/v2/entries/en/<word>

URL の末尾にある <word> と書かれた部分に注目してください。この部分を、実際に検索したい単語に置き換えます。

たとえば “chicken” の定義を調べるには、次の URL を使います:

https://api.dictionaryapi.dev/api/v2/entries/en/chicken

たとえば “little” の定義を調べるには、次の URL を使います:

https://api.dictionaryapi.dev/api/v2/entries/en/little

要するに、各単語にはそれぞれ固有の URL があります。ProtoPie Connect の API プラグインでは、前回の記事で触れたように、1つの URL しか設定できませんでした。この例では、この状況にどう対処するかを見ていきます。

API Plugin の設定

ProtoPie Connect の API Plugin では、Pie から渡された URL でリクエスト URL を上書きできます。これにより、Studio で URL を動的に組み立て、それを Pie が API リクエストをトリガーするために送信するメッセージの値として渡せます。

ProtoPie Connect では、前の例と同じようにプラグインを設定しますが、1つだけ大きな違いがあります:

• 今回は URL 欄を空欄のままにしておきます。その代わり、Message From Pie フィールドの下にある Override の横のチェックボックスをオンにしてください。ドロップダウンは既定の URL のままにします。

• Message from Pie と Message to Pie の欄には、好きなメッセージを入力してください。私はそれぞれ DICTIONARY_REQUEST と DICTIONARY_RESPONSE を使っています。

• Activate をクリックします。

API Plugin の設定。

注: プラグインはまだリクエストする URL を認識していないため、接続をテストすることはできません。

API プロトタイピングに関する限定ニュースやヒントに登録しましょう!

Pie を作成する

この例の開始用 Pie をダウンロードして、Studio で開きます。

開始用 Pie

この Pie には 2 つの Scene があります。“dictionary - home” と “dictionary - result.” です。作業はすべて “dictionary - result” Scene で行います。

“dictionary - result” Scene で作業を進めます。

多くの作業はすでに終わっていますが、まだ設定されていない 2 つの Send レスポンスに注目してください。1つは Start トリガーの下、もう1つは Return トリガーの下にあります。どちらも同じ内容なので、片方を設定してもう片方へコピーします。

Start トリガーの下の Send レスポンスを次のように設定します:

• チャネルに ProtoPie Studio を使用します。

• プラグインの Message to Pie フィールドで設定したメッセージを使用します。私の場合は DICTIONARY_REQUEST を使いました。

ここが重要です。このメッセージに添えて渡す値が、プラグインで使用される URL になります。

• Send Value Together の横のチェックボックスをオンにします。

• 表示される数式欄で、次の数式を使用します:

• "<https://api.dictionaryapi.dev/api/v2/entries/en/>" + searchWord

表示される数式欄で、示された数式を使用します。

何をしたのでしょうか？

リクエスト URL は毎回同じですが、最後の部分だけは例外です。そこに検索したい単語を付け加えます。その単語は searchWord 変数に保存されています。このように数式で URL を組み立てることで、リクエストを送るたびに動的に生成された URL をプラグインに渡せます。

Pie には、Return Trigger の下にまだ設定されていない Send レスポンスがもう1つあります。それは上で行ったのと同じように設定してもよいですし、今作成した Send レスポンスを下の Return Trigger にコピーしても構いません。必要なら、残っている未設定のプレースホルダーを削除しても大丈夫です。

プロのヒント:* コピーした Send レスポンスは、必ず “Assign searchWord = Input.text” レスポンスの下に貼り付けてください。そうしないと、Pie は前回の単語で API にリクエストしてしまいます。*

この Pie には、API からのレスポンスを受け取って利用する Receive trigger がすでに設定されています。その部分を設定する必要はありません。ただし興味があれば、その Trigger 内で使われている複数の Text レスポンスを見てみてください。JSON の複数のキーの値を使って、いくつかの Text レイヤーを埋めています。

Trigger 内で使われている複数の Text レスポンス。

ProtoPie Connect で Pie を実行する

前編と同じように、ライブデータを実際に見るには ProtoPie Connect で Pie を実行する必要があります。Pie を Connect にドラッグし、プレビューして、自分で試してみましょう!

注: 実行する前に、Pie を保存するのを忘れないでください!

ProtoPie Connect で Pie を実行する様子。

エラーへの対処

注: この記事執筆時点では ProtoPie Connect 2.6.1 はまだリリースされていませんでした。そのため、これを試していてお使いの最新バージョンが 2.6 であれば、このセクションは該当しません。2.6.1 は 2023 年 9 月末までにリリースされるはずなので、少しお待ちください。

試してみると、Pie に何も返ってこない状況に遭遇するかもしれません。これは、単語の入力を間違えた場合や、辞書に存在しない単語を検索した場合に起こります。API はこのような事態を処理するように作られており、エラーステータスコードを返します。

これは “bananas” のつづりを間違えた例です。次の URL をクリックしてください。

https://api.dictionaryapi.dev/api/v2/entries/en/bannas

API によるレスポンスは、実際の単語を検索したときとは異なります。Chrome の開発者ツールでページを右クリックして調べると、エラーが報告されているのが分かります。具体的には、標準的なインターネットのエラーコードである 404,、つまり “Not found.” を返しています。

エラーコード 404 - “Not found.” の標準的なインターネットエラーコード。

API Plugin はこの状況を認識し、別の JSON を Pie に返します。これが、結果が空白で返ってくる理由です。Pie は特定の形式の JSON を期待していましたが、返されるエラー JSON はその形式に一致しません。

プラグインから返されるエラー JSON は次のようになります:

Pie では、"status" キーの有無を確認し、その値が “Error.” かどうかを見ればよいです。もしそうなら、代替の処理を行い、ユーザーに適切なメッセージを表示できます。

Studio で、メッセージ DICTIONARY_RESPONSE を受け取る Trigger を探します。

• Condition を追加します

• 条件を次のように設定します:

• IF:

• Formula:

• parseJson(defintionJson, "status")

• EQUALS

• Value:

• “Error”

条件を追加します。

この Pie には “no results section” というレイヤーグループがあります。既定では非表示ですが、この状況では表示にします。

• 今作成した Condition の下に Opacity レスポンスを追加します。

• “no result section” レイヤーグループの Opacity を 100 に設定します。

“no result section” レイヤーグループの Opacity を 100 に設定します。

• 作業を保存し、ProtoPie Connect で再度プレビューしてください。

注: ProtoPie Connect と Studio を同時に使っている場合、ファイルが保存されると Connect はそれを認識し、Web 表示で Pie を自動的に再読み込みします。ブラウザーに戻って、もう一度操作してください。

これで、API が見つけられないものを検索すると、“No definitions found.” というメッセージが表示されます。

“No definitions found.” メッセージ。

例2: ChatGPT

これは、皆さんが一番見たかった例だと思います! はい、ProtoPie で ChatGPT のような対話型 AI を使った完全に動作する体験を作ることは 100% 可能です。

これは API plugin がどのように使えるかを示すかなり高度な例なので、ドキュメント を開いて ChatGPT API の仕組みをよく理解しておくとよいでしょう。API にリクエストを送る際には、自分で認証するための API Key も必要です。残念ながら無料ではありませんが、このような試験的な用途には非常に手頃です。始めるには Open API の料金ページ にアクセスしてください。

API Plugin の設定

これまでの例と同じように、まず ProtoPie Connect API Plugin を設定します。プラグインを次のように設定してください:

• Method: POST

• ここで触れる設定はこれまでありませんでした。RESTful API は GET 型または POST 型のリクエストで動作します。違いを完全に理解していなくても問題ありません。ほとんどの API のドキュメントには、どちらを使うべきかが書かれています。目安としては、プラグインで Body 設定を使う必要があるなら、POST を使う可能性が高いです。それ以外なら、GET でたいていはうまくいきます（うまいこと言ったつもりです）。

• URL: https://api.openai.com/v1/chat/completions

• Header:

• これもまだ使ったことのない設定です。Header を使うと、リクエストに関する情報を指定できます。すべてのリクエストには Header がありますが、前の例では内部で既定値を使っていました。この設定により、いくつかの Header 値を明示的に設定できます。この場合、リクエストの body が JSON 形式であることと、リクエストの認証方法を指定しています。

• <YOUR API KEY> と書かれた部分を、OpenAI から提供された実際の API Key に置き換えてください。

• Message from Pie: ASK CHAT GPT

• Override の横のチェックボックスをオンにして、今回はドロップダウンから Body を選択します。Pie 側でリクエストの body を組み立てます。

• Message to Pie: CHAT GPT ANSWER

• Activate をクリックします

• 注: Test Request をクリックするとエラーになります。現時点ではリクエストに body がないため、ChatGPT API には処理するものがありません。

API Plugin の設定。

Pie を作成する

下の開始用 Pie をダウンロードして、ProtoPie Studio で開きます。

開始用 Pie

今回も、Tap Send. という Trigger の下に、Send ASK CHAT GPT という未完成の Send レスポンスがあります。これを完成させましょう。

Send レスポンスを設定しています。

• いつものように、ProtoPie Studio チャネルを使用します。

• メッセージ ASK CHAT GPT を使用します

• 前の例と同様に、値を含めます。ただし今回は、URL ではなくリクエストの body を上書きします。

Chat GPT API へのリクエストの body パラメータを正しくフォーマットした例を1つ示します:

このケースでは、"content" キーの値を、ユーザーが入力欄に入力した質問に置き換えたいと考えています。要するに、置き換え用のトークンを含むテンプレートを作ることになります。次のような形です:

リクエストを送るとき、<<USER_QUERY>> の部分を、ユーザーが実際に尋ねた質問に置き換えます。さらに、ChatGPT にどのように応答してほしいかを指示しましょう。テンプレートを次のように変更します:

こうすることで、ユーザーの質問は必ず “3文以内で答えてください,” で始まり、その後に実際の質問が続くことになります。

では、これをテンプレートとして作るために、Studio で上記の内容を含むテキスト変数を作成します。

• ProtoPie Studio の左下にある Variables タブをクリックして、まだ開いていなければ変数パネルを開きます。

• 変数を作成し、BODY_TEMPLATE と名付けます。

• 変数の種類が Text になっていることを確認します。Studio の UI 右上で、変数のプロパティから Text を選択します。

• Text タイプを選んだすぐ下に空のテキストボックスがあります。上で示したテンプレートの断片をコピーして、このテキストフィールドに貼り付けます。これで変数の初期値が設定されます。

上のテンプレートの断片をコピーして、テキストフィールドに貼り付けます。

ボックスはテンプレート全体を表示するには小さすぎますが、心配はいりません。すべて入っています。

• では Send レスポンスに戻ります。

• Send Value Together の横のチェックボックスをオンにします

• 表示される数式ボックスで、次の数式を使用します:

• ```replace(BODY_TEMPLATE, "<<USER_QUERY>>", Input.text)`

表示される数式ボックスで、示された数式を使用します。

何をしたのでしょうか？

ProtoPie の replace() 関数（ドキュメントはこちら）を使って、BODY_TEMPLATE 変数に保存されているテキストを取り出し、正確な文字列 <<USER_QUERY>> を探して、入力欄に入っている内容に置き換えました。これは BODY_TEMPLATE 変数自体を変更するわけではありません。replace() 関数の出力は新しい Text です。私たちはその出力をそのままメッセージの値として渡しているだけです。

前の例と同様に、API のレスポンスを扱う Receive Trigger はすでに作成されています。必要なら見てみてください。前の例と非常によく似ていることが分かるはずです。Pie を保存しましょう — Studio での作業はこれで完了です!

完成した Pie を ProtoPie Connect にドラッグして実行してください。ChatGPT 体験が動作するはずです!

なんで科学者は原子を信用しないの？ だって、あらゆるものを作り上げるから！

完成済みの Pie

辞書検索 ChatGPT に質問

API plugin を使って実際のデータをデザインに取り込む

ProtoPie の API Plugin を使えば、実際の動的なデータをデザインに注入でき、プロトタイプをさらに現実的で機能的なレベルへ引き上げられます。あなたのビジョンを本物らしく体現する、インタラクティブでデータ駆動型のプロトタイプを作りましょう。