APIFunction
パラメータ型のリスト »APIFunction[{"name1"type1,"name2"type2,…},fun]
呼ばれるたびに関数 fun を評価する,パラメータ nameiを持つAPIを表す.関数 fun は"name1"val1,"name2"val2,…に適用される.ただし,valiは typei型であると解釈されるパラメータの設定である
APIFunction[{"name1"type1default1,…},fun]
APIが呼ばれたときにパラメータ nameiの値が指定されていない場合は,これが defaultiであると解釈する.
APIFunction[params,fun,fmt]
fun を適用した結果が形式 fmt で返されるように指定する.
APIFunction[params,fun,{fmt,rform}]
結果が,フォーム rform からの応答として返されるように指定する.
APIFunction[params,fun,{fmt,rform,failfmt}]
失敗した場合は結果を failfmt 形式で返すように指定する.
詳細とオプション
- CloudDeploy[APIFunction[…]]は,WebブラウザからのようにWebのGet(あるいはPost)リクエストを使ってクラウド中で外部から呼び出せるように,API関数を配備する.
- APIFunctionは,Webクエリ文字列中あるいはPOSTリクエストでパラメータ設定 namei=striを取り,これを fun が適用された連想中の,要素"namei"->Interpreter[typei]["stri"]に変換する.
- Wolfram言語内では,APIFunction[…][assoc]を使って,assoc 中で与えられるパラメータ設定でAPI関数を呼び出す効果を再現することができる.この場合,設定値のいずれかが文字列ではないと,その値は型の解釈なしに直接使われる.
- typei指定の可能な形式
-
"form" Interpreterがサポートする任意のフォーム Restricted[…] 等 Interpreterがサポートする任意の制約条件付きフォーム等 Interpreter[…] 任意のInterpreterオブジェクト assoc パラメータの扱いについての詳細を与える連想 tfun 文字列に適用される任意の関数 - 連想中で使用可能な要素
-
"Interpreter" このパラメータについて使われるインタープリタ "Required" このパラメータはが必要かどうか "Default" このパラメータのデフォルト値(もしあれば) "AllowedExtensions" このパラメータに許可する拡張子 "Help" パラメータに関連付けるヘルプ - "AllowedExtensions"のデフォルトはInheritedで,APIFunctionのオプションAllowedCloudParameterExtensionsについての設定中で指定された拡張子を許可することに相当する.
- クラウド中で呼ばれると,APIFunction[params,fun]は,デフォルトで,Wolfram言語による結果のテキスト形式を返す.
- APIFunction[params,fun,fmt]における可能な結果の形式 fmt
-
"fmt" ExportFormがサポートする任意の形式 f body に適用される任意の関数 - APIFunction[params,fun,"fmt"]はAPIFunction[params,ExportForm[fun[#],"fmt"]&]と等価である.ノートブックでAPIFunctionを評価している間はExportFormは現れない点に注意のこと.
- よく見られる可能な結果形式
-
None 純粋なWolfram言語のテキスト(デフォルト) "GIF","JPEG","PNG",… 結果の画像 "String" 生の文字列としての結果の文字列 "HTML" 結果の純粋な静的HTMLバージョン "HTMLThemed" 組込みのテーマを持つ静的HTML "HTMLPaneled" パネル内のHTMLコンテンツ - APIFunctionは次のオプションをサポートする.
-
AllowedCloudExtraParameters None APIにどのような追加的パラメータを許可するか AllowedCloudParameterExtensions Automatic パラメータにどのような拡張子を許可するか ImageFormattingWidth Automatic 出力のフォーマットのためのラッピング幅 ImageSize Automatic 出力の全体的な画像サイズ - APIFunction[params,fun,{"fmt","rform"}]は,配備される場合はAPIFunction[params,ResponseForm[ExportForm[fun[#],"fmt"],"rform"]&]に等しい.ノートブックでAPIFunctionを評価する際はResponseFormもExportFormも現れない点に注意のこと.
- パラメータの解釈に失敗した場合,fun は適用されず,代りに返された結果がFailure["src",<fname1->Failure[…],fname2->Failure[…] >]になる.ただし,fnameiは解釈が失敗したパラメータ名である.
- デフォルト値を持たないパラメータがない場合は,Failure["MissingParameter",…]が生成される.
- rform が指定されている場合は,fmt が指定されていようといなかろうと,Failure[…]式が応答フォームに直接渡される.
- Webを通してAPIFunction[…]によって定義されるAPIが呼ばれると,パラメータの解釈に成功した場合には200というHTTP状態コードが返され,fun を適用した結果はFailure[…]ではなくなる.それ以外の場合,状態コード400が返される.
- APIFunction[params,…]では,params はFormObject,あるいはFormFunctionにおけるフォーム指定に使われている他のフォームでよい.APIに関係しないフォーム指定の特徴は無視される.APIFunctionにはFormFunctionと同じオプションが使えるが,適用されないものは無視される.
- APIFunction[…,fmt]あるいはAPIFunction[…{fmt1,…}]の中では,任意の fmt 式を文字列形式であるいいは{"fmt",optname1optvalue1,…}の形のリストとして与えることができる.ただし,optnameiは"fmt"形式のオプションである.
例題
すべて開くすべて閉じる例 (4)
xという名前のパラメータがAssociationに適用されたAPI関数:
CloudDeployを使ってAPI関数をWolfram Cloudに配備する:
配備されたAPI関数は,Webブラウザでクラウドオブジェクトにアクセスし,そのURLに?x=value を追加することで呼び出すことができる:
不十分な入力データでAPIFunctionを呼び出すとFailureが返される:
スコープ (6)
計算についてのメタ情報を持つJasonコンテナの中の,計算結果をWolfram言語のテキストとして返すAPI関数:
インタープリタの指定 (1)
Interpreterのさまざまな指定方法を使う:
デフォルト (4)
フィールドのデフォルトを設定する.デフォルトのあるフィールドは必須項目ではなくなる:
RuleDelayedを使って新たなデフォルトを毎回評価する:
オプション (3)
AllowedCloudExtraParameters (1)
APIFunctionの呼出し元が結果のエキスポートに使用するフォーマットを設定することを許可する:
"_exportform"パラメータが呼出しの中で指定されていなければ,APIFunctionは結果をエキスポートしない:
AllowedCloudParameterExtensions (2)
アプリケーション (7)
特性と関係 (9)
配備されたAPIには,(必要な場合は適切な認証を与えられた)任意のHTTPクライアントからアクセスすることができる:
APIFunctionはFormFunctionと互換になるように設計されている:
APIFunctionはFormFunctionと同じオプションを取るが,そのほとんどを無視する:
APIFunctionの単独のフィールドは,Interpreterを使ってWolfram言語の式の入力を変換する:
また,Interpreterを直接適用することとも同じである:
APIFunctionは$EvaluationEnvironmentを"WebAPI"に設定し$CloudEvaluationをTrueにして実行される:
CloudEvaluateの評価環境は"WebEvaluation"である:
APIFunctionは入力パラメータに基づいて計算をオンデマンドで実行する際に役に立つ.入力パラメータに依存しない計算については,Delayedも使うことができる:
APIFunctionを使う同等のコード:
API関数を実行した場合もCloudEvaluateを使った場合も,$CloudEvaluationに結果はTrueである:
デフォルト設定のIncludeDefinitionsTrueのとき,API関数の配備には関数が依存するすべての定義が含まれる:
考えられる問題 (3)
エキスポートおよび応答のフォーマットは,APIがWebで実行された場合にのみ適用される:
APIFunctionへのクエリを手動で構築する場合は,URLEncodeを適用することが重要である:
規則のリストでURLExecuteを呼び出すとクエリのパラメータが自動的に符号化される:
同じAPIFunctionに複数のリクエストを送っても,同じWolfram Engineでは評価されないことが多い.したがって,定義はリクエスト間で保持されない:
テキスト
Wolfram Research (2014), APIFunction, Wolfram言語関数, https://reference.wolfram.com/language/ref/APIFunction.html (2017年に更新).
CMS
Wolfram Language. 2014. "APIFunction." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2017. https://reference.wolfram.com/language/ref/APIFunction.html.
APA
Wolfram Language. (2014). APIFunction. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/APIFunction.html