APIリファレンス
GDWebRequest
リクエストを処理する関数が受け取るHTTPリクエストです。JSONの解析、キャンセルの管理、大きな本文を少しずつ保存する機能を持ちます。
pathは区切られた各部分を一度だけ復号したパスで、targetはpercentエスケープとクエリを保った原文です。%2Fは区切りになりません。復号した結果が正しいUTF-8でない場合や制御文字を含む場合は400を返します。
文字列として読めないクエリの値はPackedByteArrayで保持します。queryは壊れた組を省きます。正常な組とErrの両方を受け取るにはGD.http.decode_query()を使います。
本文の大きさに既定の上限はありません。ヘッダーを受け取るとすぐハンドラーを呼び、本文はハンドラーが読んだ分だけ接続から読みます。read()が成功して空を返したら本文の終わりです。text()が扱えるのはStringに収まる大きさまでです。
プロパティ
context: GDAsyncContext処理のキャンセルや制限時間を管理するオブジェクトです。親から子へ、最初のキャンセル理由と期限を伝えます。
method: Stringpath: Stringip: Stringquery: Dictionaryquery_all: Dictionaryparams: Dictionarytarget: String
メソッド
header(name: String) -> Stringheaders() -> Dictionaryread(bytes: int = 32768) -> PackedByteArray, Errbytes() -> PackedByteArray, Errbody_size() -> intlimit(bytes: int) -> Errsave(path: String) -> int, Errtext() -> String, Errjson() -> Variant, Errread_async(bytes: int = 32768) -> await PackedByteArray, Errbytes_async() -> await PackedByteArray, Errsave_async(path: String) -> await int, Errtext_async() -> await String, Errjson_async() -> await Variant, Errkeep(name: String, value: Variant) -> voidkept(name: String, fallback: Variant = null) -> Variantvalid(name: String, fallback: Variant = null) -> Variant
header
header(name: String) -> String英語原文Return the named HTTP header.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
name | String | 省略不可 | 対象を登録・参照するための名前。 |
戻り値
String
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
headers
headers() -> Dictionary英語原文Return HTTP headers as a dictionary.
引数
引数はありません。
戻り値
Dictionary
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
read
read(bytes: int = 32768) -> PackedByteArray, Err英語原文Read up to bytes from the stream; an empty success value denotes EOF.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
bytes | int | 32768 | 文字数ではなく、バイト数で指定します。 |
戻り値
PackedByteArray, Err
この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
bytes
bytes() -> PackedByteArray, Errリクエスト本文全体をバイト列として読みます。 ストリーミング形式の本文は読み進めると元に戻せません。異なる読み取り方法で、同じ部分を繰り返し読もうとしないでください。
引数
引数はありません。
戻り値
PackedByteArray, Err
文字列に変換していない本文のバイト列。
この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
通信の失敗、キャンセル、設定したサイズの上限超過、データの変換失敗はErrで確認します。
関連文書
body_size
body_size() -> int英語原文Return the body length without reading a large body into memory.
引数
引数はありません。
戻り値
int
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
limit
limit(bytes: int) -> Errこのリクエストだけに適用する本文の上限をバイト数で設定します。
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
bytes | int | 省略不可 | 文字数ではなく、バイト数で指定します。 |
戻り値
Err
エラー
Errオブジェクトを直接返します。処理結果とErrの2つを返す形式ではありません。エラーが見つからない場合などはnullを返します。詳しい条件は、この関数の説明を参照してください。
0..9223372036854775807バイトを受け付けます。上限を超えると、本文を読んだ操作へ失敗として返ります。
save
save(path: String) -> int, Err英語原文Save the remaining body inside a mount without expanding it in memory.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
path | String | 省略不可 | ファイルシステム上のパス。相対パスは実行ディレクトリ基準で、アクセス権限の設定に従います。 |
戻り値
int, Err
この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
text
text() -> String, Errリクエスト本文を読み、UTF-8文字列としてデコードします。 ストリーミング形式の本文は読み進めると元に戻せません。異なる読み取り方法で、同じ部分を繰り返し読もうとしないでください。
引数
引数はありません。
戻り値
String, Err
デコードした本文。
この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
通信の失敗、キャンセル、設定したサイズの上限超過、データの変換失敗はErrで確認します。
関連文書
json
json() -> Variant, Errリクエスト本文を読み、厳密なJSONとして解析します。 ストリーミング形式の本文は読み進めると元に戻せません。異なる読み取り方法で、同じ部分を繰り返し読もうとしないでください。
引数
引数はありません。
戻り値
Variant, Err
オブジェクト、配列、スカラー、nullのいずれかのJSON値。
この関数は、呼び出した処理だけを待たせ、完了すると結果を返します。待っている間もほかの処理は進みます。awaitを書く必要はありません。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
通信の失敗、キャンセル、設定したサイズの上限超過、データの変換失敗はErrで確認します。
関連文書
read_async
read_async(bytes: int = 32768) -> await PackedByteArray, Err英語原文Always defer completion for explicit awaiting.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
bytes | int | 32768 | 文字数ではなく、バイト数で指定します。 |
戻り値
await PackedByteArray, Err
完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
bytes_async
bytes_async() -> await PackedByteArray, Errリクエスト本文全体をバイト列として読みます。 ストリーミング形式の本文は読み進めると元に戻せません。異なる読み取り方法で、同じ部分を繰り返し読もうとしないでください。
引数
引数はありません。
戻り値
await PackedByteArray, Err
文字列に変換していない本文のバイト列。
完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
通信の失敗、キャンセル、設定したサイズの上限超過、データの変換失敗はErrで確認します。
関連文書
save_async
save_async(path: String) -> await int, Err英語原文Save the remaining body inside a mount without expanding it in memory.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
path | String | 省略不可 | ファイルシステム上のパス。相対パスは実行ディレクトリ基準で、アクセス権限の設定に従います。 |
戻り値
await int, Err
完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
text_async
text_async() -> await String, Errリクエスト本文を読み、UTF-8文字列としてデコードします。 ストリーミング形式の本文は読み進めると元に戻せません。異なる読み取り方法で、同じ部分を繰り返し読もうとしないでください。
引数
引数はありません。
戻り値
await String, Err
デコードした本文。
完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
通信の失敗、キャンセル、設定したサイズの上限超過、データの変換失敗はErrで確認します。
関連文書
json_async
json_async() -> await Variant, Errリクエスト本文を読み、厳密なJSONとして解析します。 ストリーミング形式の本文は読み進めると元に戻せません。異なる読み取り方法で、同じ部分を繰り返し読もうとしないでください。
引数
引数はありません。
戻り値
await Variant, Err
オブジェクト、配列、スカラー、nullのいずれかのJSON値。
完了を知らせるSignalを返します。awaitで完了を待つと、上に示した型の結果を受け取れます。
エラー
処理結果とエラー情報(Err)を返します。Errがnullなら成功です。失敗時にも途中までの結果が残る場合があるため、値を使う前にErrを確認してください。結果とErrを返す関数の中では、?でエラーをそのまま呼び出し元へ返せます。!はエラー時にプログラムを終了します。gd serveでは、そのリクエストの処理だけが終了します。
通信の失敗、キャンセル、設定したサイズの上限超過、データの変換失敗はErrで確認します。
関連文書
keep
keep(name: String, value: Variant) -> void英語原文Share request-local values between middleware and later processing.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
name | String | 省略不可 | 対象を登録・参照するための名前。 |
value | Variant | 省略不可 | 保存、変換、検査など、この関数で処理する値。 |
戻り値
void
値を返しません。
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
kept
kept(name: String, fallback: Variant = null) -> Variant英語原文Return a request-local stored value.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
name | String | 省略不可 | 対象を登録・参照するための名前。 |
fallback | Variant | null | 対象の値が存在しないか省略された場合に使う値。 |
戻り値
Variant
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。
valid
valid(name: String, fallback: Variant = null) -> Variant英語原文Return a validated request value.
引数
| 名前 | 型 | 省略時の値 | 説明 |
|---|---|---|---|
name | String | 省略不可 | 対象を登録・参照するための名前。 |
fallback | Variant | null | 対象の値が存在しないか省略された場合に使う値。 |
戻り値
Variant
エラー
この関数は、結果とは別にErrを返す形式ではありません。結果の確認方法は、この関数の説明を参照してください。