APIFunction[{"name1"type1,"name2"type2,},fun]

呼ばれるたびに関数 fun を評価する,パラメータ nameiを持つAPIを表す.関数 fun"name1"val1,"name2"val2,に適用される.ただし,valitypei型であると解釈されるパラメータの設定である

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がサポートする任意の形式
    fbody に適用される任意の関数
  • 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 NoneAPIにどのような追加的パラメータを許可するか
    AllowedCloudParameterExtensions Automaticパラメータにどのような拡張子を許可するか
    ImageFormattingWidthAutomatic出力のフォーマットのためのラッピング幅
    ImageSizeAutomatic出力の全体的な画像サイズ
  • APIFunction[params,fun,{"fmt","rform"}]は,配備される場合はAPIFunction[params,ResponseForm[ExportForm[fun[#],"fmt"],"rform"]&]に等しい.ノートブックでAPIFunctionを評価する際はResponseFormExportFormも現れない点に注意のこと.
  • パラメータの解釈に失敗した場合,fun は適用されず,代りに返された結果がFailure["src",<|fname1->Failure[],fname2->Failure[]|>]になる.ただし,fnameiは解釈が失敗したパラメータ名である.
  • デフォルト値を持たないパラメータがない場合は,Failure["MissingParameter",]が生成される.
  • rform が指定されている場合は,fmt が指定されていようといなかろうと,Failure[]式が応答フォームに直接渡される.
  • Webを通してAPIFunction[]によって定義されるAPIが呼ばれると,パラメータの解釈に成功した場合には200というHTTP状態コードが返され,fun を適用した結果はFailure[]ではなくなる.それ以外の場合,状態コード400が返される.
  • APIFunction[params,]では,paramsFormObject,あるいはFormFunctionにおけるフォーム指定に使われている他のフォームでよい.APIに関係しないフォーム指定の特徴は無視される.APIFunctionにはFormFunctionと同じオプションが使えるが,適用されないものは無視される.
  • APIFunction[,fmt]あるいはAPIFunction[{fmt1,}]の中では,任意の fmt 式を文字列形式であるいいは{"fmt",optname1optvalue1,}の形のリストとして与えることができる.ただし,optnamei"fmt"形式のオプションである.

例題

すべて開くすべて閉じる

  (4)

xという名前のパラメータがAssociationに適用されたAPI関数:

1つの選択的パラメータがデフォルト値を持つ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)

JSON符号化の行列を取るAPIFunctionを配備する:

Wolfram言語のデータとして与えられたパラメータを取るAPIFunctionを配備する:

アプリケーション  (7)

任意の国の地図を得る:

指定されたシンボルの最新株価を求める:

CellularAutomatonをプロットする:

BarChart APIを配備する:

新たなFormFunctionにリダイレクトするAPIを作成し,配備する:

任意の国の指定された年の人口を与えるAPIを配備する:

テンプレートから完全なWebページを返す:

特性と関係  (9)

配備されたAPIには,(必要な場合は適切な認証を与えられた)任意のHTTPクライアントからアクセスすることができる:

APIFunctionFormFunctionと互換になるように設計されている:

逆もまた真である:

APIFunctionFormFunctionと同じオプションを取るが,そのほとんどを無視する:

APIFunctionの単独のフィールドは,Interpreterを使ってWolfram言語の式の入力を変換する:

これは,事実上,以下と同じことである:

また,Interpreterを直接適用することとも同じである:

APIFunction$EvaluationEnvironment"WebAPI"に設定し$CloudEvaluationTrueにして実行される:

これをデスクトップセッションの結果と比較する:

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年に更新).

テキスト

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

BibTeX

@misc{reference.wolfram_2024_apifunction, author="Wolfram Research", title="{APIFunction}", year="2017", howpublished="\url{https://reference.wolfram.com/language/ref/APIFunction.html}", note=[Accessed: 14-November-2024 ]}

BibLaTeX

@online{reference.wolfram_2024_apifunction, organization={Wolfram Research}, title={APIFunction}, year={2017}, url={https://reference.wolfram.com/language/ref/APIFunction.html}, note=[Accessed: 14-November-2024 ]}