NarraLeaf

ネットワーク

ゲームの実行中に HTTP リクエストを送信し、返ってきた内容を読み取ります

実行時にゲームの外にある何かを読み取るための3つのノードです。オンラインの掲示板、パッチノート、ランキングなどが該当します。Fetch はリクエストを送信して Response を返し、Read Response Text と Read Response JSON はその Response を値へ変換します。

これらはアセットのためのものではありません。画像、音声、動画はプロジェクトのコンテンツとしてゲームに同梱されるものであり、実行時に取得する形にすると、正しく表示されるかどうかがサーバーに依存してしまいます。

規約

  • プロジェクト側で許可されている必要があります。 Network access はすべての新規プロジェクトで既定が Off（オフ）で、オフの間はこれらのノードを実行できません。残る2つの位置——Allowlist か Any host——のいずれかであれば実行でき、Allowlist の場合は到達できるアドレスも指定します。詳細は下記のプロジェクトが HTTP を許可していない場合を参照してください。
  • Fetch は latent で、2つの読み取りノードはそうではありません。 Fetch はリクエストの完了を待つため event と macro を宣言し、function グラフに置くことも Blueprint Value のバックエンドにすることもできません。読み取りノードはホストがすでに保持している Response を扱うため即座に戻りますが、これらも exec ノードであることに変わりはなく、同じく Blueprint Value のバックエンドにはなれません。
  • 許可されるのは http と https のみです。 それ以外のスキームはリクエストが送られる前に拒否されます。これにより file: が締め出され、このノードでプレイヤーのディスクを読み取れてしまう可能性もなくなります。
  • リクエストはゲームのメインプロセスが送信し、ページが送信するわけではありません。 そのため、通常のサードパーティ API はここでは CORS ヘッダーを送らなくても機能します。Web 書き出しは例外で、他の任意のページと同様に CORS の制約を受けます。
  • Cookie は送信されません。 ゲームは誰ともセッションを持たないため、暗黙の認証情報が付いてくることは作者が求めていない予期しない事態になります。
  • レスポンスは 8 MiB を上限とし、それを超えると切り詰められるのではなく拒否されます。リクエストは 10 秒でタイムアウトし、Timeout (s) ピンで別途指定しない限り、上限は 60 秒です。
  • エディターのキャンバス上では実行できません。 作者時のキャンバスにはホストが存在しないため、Fetch はそこでは何にも到達せず、ネットワークエラーを報告します。

プロジェクトが HTTP を許可していない場合

Network access が Off に設定されていると、書き出したゲームは自分自身のプロトコルに閉じ込められ、すべての HTTP リクエストがキャンセルされます。そのため、グラフ内のネットワークノードは実行できないコードになります。作者に近い順に、次の3か所がそのことを伝えます。

場所起きること
ブループリントエディターnetwork/fetch-disallowed プロジェクトチェックがそのノードをエラーとして報告します。
プロダクションビルドビルドが拒否され、該当のブループリントが名指しされます。この拒否はプロジェクトチェックの一括実行の一部ではなく、その設定の影響も受けません。
実行時リクエストは発行される前に拒否され、Fetch は networkError から抜けます。

対処はどちらか一方です。Network access を Off から Allowlist（アドレスを指定）または Any host に切り替えるか、ノード自体を取り除くかです。

この設定は Web 書き出し（Web export）では強制されません。これはコンテンツセキュリティポリシーとリクエストフィルターによって実現されており、この2つはデスクトップシェルにしか存在しません。また、HTTP(S) 越しに配信されるゲームは、その性質上すでにネットワーク上にあります。ネットワークノードは Web ビルドでも動作します。上記のビルド拒否は Web 向けのターゲットにも同様に適用されるため、この設定をオフにしたプロジェクトはいずれにせよ Web ビルドを作成できません。

Fetch

blueprint.network.fetch · Latent

リクエストを送信し、完了を待ちます。どの実行ピンから抜けるかは、何が起きたかによって決まります。

ピン方向型備考
inin · exec—
urlin · datastringURL というラベルが付きます。http または https である必要があります。
headersin · datajson省略可能。Headers というラベルが付きます。
bodyin · datastring省略可能。Request Body というラベルが付きます。
timeoutSecondsin · datafloat省略可能。Timeout (s) というラベルが付きます。
successout · exec—サーバーが 2xx ステータスで応答しました。
httpErrorout · exec—サーバーは応答したが、2xx 以外でした。
networkErrorout · exec—まったく応答が返りませんでした。
timeoutout · exec—リクエストがタイムアウト時間を超えました。
responseout · dataResponseBodyResponse というラベルが付きます。
statusout · dataintegerStatus というラベルが付きます。応答が返らなかった場合は 0 です。
errorout · datastringError というラベルが付きます。成功時は空です。

カード上のフィールド

フィールド内容
MethodGET、POST、PUT、PATCH、DELETE、HEAD のいずれかです。既定は GET です。

Request Body は POST、PUT、PATCH でのみ送信され、他のメソッドではこのピンは無視されます。

networkError は「HTTP 応答がまったく発生しなかった」ことをまとめて示すピンです。DNS 失敗、接続拒否、http(s) 以外のスキーム、サイズ上限を超えた応答、Network access が Off のプロジェクト、Allowlist に名前のないアドレスなどが該当します。これらが同じピンを共有しているのは、作者側の対応がどれも同じ——データはないのでプレイヤーに別の何かを見せる——だからで、どれが起きたかは Error ピンが示します。

Response は httpError でも生成されます。 REST API の 404 には、何が見つからなかったかを示す JSON が含まれていることが多く、そこで分岐するグラフはそれを読み取れる必要があります。

Headers は JSON オブジェクトで、Make Object で組み立てるのが最も簡単です。数値や真偽値はテキストとして送信され、ネストしたオブジェクトや配列は、正しく変換できるヘッダーが存在しないため破棄されます。

Response 型

Fetch はレスポンス本文をデータピンには乗せません。代わりに ResponseBody——2つの読み取りノードが受け取るハンドル——を生成します。

読み取りを切り離すことで2つの利点が得られます。誰にも読まれなかった応答は、決して解析されません。そして JSON.parse の失敗には専用の実行ピンが用意されます。出力値としてはこれが null としてしか報告できず、本当に null だった本文と区別が付かなくなってしまうからです。

Response はそれを取得した実行の間しか読み取れません。 その実行が終了すると解放され、他のどの実行からも到達できなくなります。イベントをまたいで Response を運ぶ手段はなく、ハンドルを変数に保存しても意味がありません——次にどこかのグラフがそれを読もうとした時点で、そのハンドルはすでに無効になっています。データを残しておきたい場合は、先に読み取ってから、その読み取った値の方を保存してください。

利用できなくなったハンドルを読み取ると、そのノードを名指しした実行エラーになります。

1つの実行は同時に最大 32 個の Response を保持できます。ループの中でこの上限を超えて取得したグラフは、静かに追い出されるのではなく networkError を受け取ります。古い本文を破棄すると、作者がまだ保持しているハンドルを壊してしまうためです。

Read Response Text

blueprint.network.readResponseText

Response を文字列として読み取ります。サーバーが指定した文字セットでデコードし、指定がない場合は UTF-8 でデコードします。

ピン方向型備考
inin · exec—
responsein · dataResponseBodyResponse というラベルが付きます。
nextout · exec—
textout · datastringText というラベルが付きます。

失敗ピンはありません。本文はこのノードに届いた時点ですでにデコードされており、デコードできなかったバイトは、作者が対処できるエラーではなく置換文字になります。

Read Response JSON

blueprint.network.readResponseJson

Response を JSON として解析します。

ピン方向型備考
inin · exec—
responsein · dataResponseBodyResponse というラベルが付きます。
nextout · exec—解析に成功しました。
failedout · exec—本文が JSON ではありませんでした。
valueout · datajsonValue というラベルが付きます。
errorout · datastringError というラベルが付きます。成功時は空です。

failed は配線ミスではなく、実際に起こり得る実行時の状況です。よくある原因は、サーバーが JSON を期待している場面で HTML のエラーページを返してくることです。そこで分岐し、プレイヤーに何かを表示してください。

このページの目次

規約プロジェクトが HTTP を許可していない場合FetchResponse 型Read Response TextRead Response JSON