クライアントからAPIをコールする方法が2つあります:

• 1つ目の方法は、cmd_functionパラメータに関数名を、その他のすべてのパラメータに引数を格納してapiにPOSTする方法です。例えば、cmd_function=vector_length&x=1&y=2&z=3です。

  requestsライブラリを使用したPythonクライアントコード

  import requests
  
  resp = requests.post("http://127.0.0.1:8008/api", {
      "cmd_function": "geo.vector_length",
      "x": "1", "y": "2", "z": "3"    
  })
  print(resp.text)
  

  この手法の方がクライアントの実装が簡単ですが、ハンドラーがすべての引数値を文字列として受け取るので、さらに型チェック/型変換のコードをハンドラーに追加するか、または、関数デコレータ内にarg_types辞書(上記参照)を指定する必要があります。

  Note

  型変換を追加しなかった場合、このサンプルは動作しません。 型変換を用意したサンプルは、以下のデフォルト値と引数の型を参照してください。

• 推奨される2つ目の方法は、jsonパラメータに(関数名の文字列、位置指定引数のリスト、キーワード引数オブジェクトが含まれた)JSONオブジェクトの文字列エンコードを格納してapiにPOSTする方法です。例えば、["geo.vector_length", (1, 2, 3), {}]です。

  この手法では、暗黙的に型情報がエンコードされ、より複雑な引数の型に対応することができます。

  追加のmultipart/form-data引数には、追加キーワード引数が含まれていると解釈されます。 これらの引数を使用することで、base64エンコードをする必要なくバイナリデータを渡すことができます(jsonという名前のバイナリデータ引数を持つことはできません)。 webapiclient.pyを使用したPythonクライアントは、この詳細を意識する必要がありません。

  requestsライブラリを使用した最小限のPythonクライアントコード

  import json
  import requests
  
  def call_api(endpoint_url, function_name, *args, **kwargs):
      return requests.post(endpoint_url,
          data={"json": json.dumps([function_name, args, kwargs])}).json()
  })
  

  Houdiniに同梱されているwebapiclient.pyモジュールは、API関数をコール可能な完全なPythonクライアントを実装します。 このモジュールはHoudiniに依存せず、あなた独自のプロジェクトにコピーして使用可能です。 このモジュールを使用すれば、もっと自然な構文でAPI関数をコールすることができます。

  service = webapiclient.Service("http://127.0.0.1:8008/api")
  print(service.geo.vector_length(1, 2, 3))
  

  最小限のJavaScriptクライアントコード

  function call_api(function_name, kwargs)
  {
      var formdata = new FormData();
      formdata.append("json", JSON.stringify(
          [function_name, [], kwargs]));
  
      return fetch("/api", {
          method: "POST",
          body: formdata
      });
  }
  

  バイナリデータを扱うフルJavaScriptクライアントは、下記で載せています。

• API関数にデフォルト値を用意することができ、コールする側は、JSONエンコードされた[name, args, kwargs]のコール手法を使用する時に、位置指定引数とキーワード引数を混在させて使用することができます。

  デフォルト値を使用したサーバーとPythonクライアントのサンプル。

  # サーバーコード:
  @hwebserver.apiFunction("test")
  def foo(a, b=2, c=3):
      return (a, b, c)
  
  
  # クライアントコード:
  service = webapiclient.Service("http://127.0.0.1:8008/api")
  
  # 以下のコールはどれも同じで[1, 2, 3]を返します:
  service.test(1, 2, 3)
  service.test(1, 2, c=3)
  service.test(a=1, c=3, b=2)
  

• URLエンコードのコール手法を使用する時は、すべての引数を文字列として渡しますが、API関数を定義する時に型を指定することができます。

  Python2とPython3での引数の型の指定方法

  @hwebserver.apiFunction("test", arg_types={"value": int})
  def double_int(value):
      return value * 2
  
  # "value=3"のPOSTボディでコールすると、その文字列の"3"が整数の3に変換されます。
  

  Python3では、引数の型も型ヒントを使って指定することができます。

  @hwebserver.apiFunction("test")
  def double_int(value: int):
      return value * 2
  

• API関数は、bytearrayオブジェクト(Python3ではbytesオブジェクト)を返すことで、または、Content-Typeがapplication/octet-streamのレスポンスを返すことでバイナリデータを返すことができ、hwebserver.fileResponseを使用してapplication/octet-streamによってファイルの内容をストリームしたり、 関数がバイナリを返すものと示してbytesを返すことができます。

• webapiclient.pyがバイナリデータの戻り値を受信すると、クライアント側でそのバイナリデータすべてをメモリを読み込むことなくストリームできるようにファイルライクなオブジェクトを返します。クライアント側では、バイナリデータをすべて読み込まないようにする場合にリクエストが必ず閉じるようにするために、その結果に対してwithステートメントを使用してください。

  バイナリデータを返すサーバーとそのバイナリデータを受信するPythonクライアント

  # サーバーは、以下のようにしてバイナリデータを返すことができます:
  
  @hwebserver.apiFunction("test")
  def binary_data(request):
      return bytearray([0, 0, 65, 66, 0])
  
  
  # クライアントは、他の関数と同じように関数をコールして、アンパックされたJSONの代わりに
  # `bytes`オブジェクトを受信することができます:
  
  with service.test.binary_data() as result_stream:
      binary_data = result_stream.read()
  

  API関数がバイナリを返すように示したサーバー

  @hwebserver.apiFunction("test", return_binary=True)
  def binary_data(request):
      return b'\x00\x00AB\x00'
  

• webapiclient.pyを使用すると、bytearrayオブジェクトを使って引数にバイナリデータを渡したり、webapiclient.Fileオブジェクトを使ってディスク上のファイルからバイナリデータをストリームさせることができます。

  Note

  バイナリデータ引数はキーワード引数を使用して渡す必要があり、位置指定引数で渡すことはできません。

  バイナリデータを送信するPythonクライアントとバイナリデータを受信するサーバー

  # クライアントは、以下のようにしてバイナリデータを送信することができます:
  service.test.use_binary_data(
      small_data=bytearray([0, 0, 65, 66, 0]),
      big_data=webapiclient.File("/path/to/binary/file"))
  
  
  # サーバーは、バイナリデータをUploadedFileオブジェクトとして受信して、
  # そのオブジェクトからバイナリデータを読み込みます:
  import shutil
  import hwebserver
  
  @hwebserver.apiFunction("test")
  def use_binary_data(request, small_data, big_data):
      small_data_as_bytes = small_data.read()
      with open("uploaded_file.bin", "wb") as open_file:
          shutil.copyfileobj(big_data, open_file)
  

• API関数でhwebserver.APIErrorが引き起こされると422ステータスが返されます。

• webapiclient.pyを使用した場合、200以外のステータスコードを持つレスポンスは、クライアントに対してwebapiclient.APIError例外を引き起こします。

• API関数でAPIError以外の例外が発生した場合、サーバーは500ステータスコードを返します。 サーバーがデバッグモードの場合、そのレスポンスにはスタックトレースが格納されます。

  エラーについて説明したServerコードとPythonクライアントコード

  # サーバー:
  
  @hwebserver.apiFunction("test")
  def illustrate_errors(request, value):
      if value == 0:
          return ["successful", "result"]
      if value == 1:
          raise hwebserver.APIError("an error occurred")
      if value == 2:
          raise hwebserver.APIError({"any": "json-encodable"})
      if value == 3:
          raise hwebserver.OperationFailed("an unhandled exception")
  
  
  # クライアント:
  
  print(service.test.illustrate_errors(0)) # ["successful", "result"]がプリントされます。
  
  try:
      service.test.illustrate_errors(1)
  except webapiclient.APIError as e:
      print(str(e)) # "an error ocurred"がプリントされます。
      print(e.status_code) # 422がプリントされます。
  
  try:
      service.test.illustrate_errors(2)
  except webapiclient.APIError as e:
      print(e.args[0]["any"]) # "json-encodable"がプリントされます。
      print(e.status_code) # 422がプリントされます。
  
  try:
      service.test.illustrate_errors(3)
  except webapiclient.APIError as e:
      print(e.status_code) # 500がプリントされます。
  

以下の情報は、新しい言語でクライアントを実装する時に役に立ちます。 リファレンスとしてwebapiclient.pyを参照してください。

• testネームスペース内にあるaとbの引数を受け取るfunc1関数をコールすると仮定します。 位置指定引数でaの値に1を、キーワード引数でbの値に“two”を渡すとします。

  • '["test.func1", [1], {"b": "two"}]'を取得するJSONエンコードは["test1.func", [1], {"b": "two"}]です。

  • そのJSONエンコード値をURLエンコードしたものをjsonという名前に入れます:json=%5B%22test.func1%22%2C+%5B1%5D%2C+%7B%22b%22%3A+%22two%22%7D%5D

  • これをサーバーの/api URLパスにPOSTします。

• POSTは、技術的に何にでも対応できるので推奨されるリクエストメソッドです。HTTPは結果をキャッシュ可能と定義するので、副作用があったり、または、引数以外のデータに依存するような関数にはGETを使用しないでください。

• URIエンコーディングとmultipart/form-dataエンコーディングの両方に対応しています。

• バイナリ引数を送信する場合、そうでなくても膨大な数の引数をストリームする場合、JSONエンコードされたデータにはそれらの引数を含めないでください。 代わりに、引数名を使ってボディ内にそれらの引数をmultipart/form-dataとしてエンコードし、application/octet-streamのContent-Typeを使用してください。バイナリ引数の名前にjsonを使用することはできません。

• "application/json, */*"のAcceptヘッダを送信すると、サーバーはエラーメッセージをJSONとして返します。

• サーバーがapplication/octet-streamのContent-Typeを返すと、API関数からのレスポンスはバイナリデータになり、JSONにはなりません。

• サーバーは、成功すると200、APIError例外を引き起こすと422、未処理の例外があると500で応答します。

• API関数は、リクエストにフルアクセスできるので、ヘッダを見ることができます。 この機能は、認証を実装する時に役立ちます。

• API関数からのレスポンスにHTTPステータスコード、Content-Type、さらにヘッダを加えて返すことができます。このプロトコルを確認することを推奨しますが、認証以外の独自のカスタム動作を追加しないでください。