kong.request

クライアントリクエストモジュール。

このモジュールにはクライアントが行う受信リクエストに関する情報を取得するための関数一式が揃っています。

kong.request.get_scheme()

リクエストのURLのスキーマコンポーネントを返します。戻り値は小文字形式に正規化されます。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• string："http"や"https"のような文字列。

使用法

-- Given a request to https://example.com:1234/v1/movies

kong.request.get_scheme() -- "https"

kong.request.get_host()

リクエストのURLのホストコンポーネント、または「ホスト」ヘッダーの値を返します。戻り値は小文字の形式に正規化されます。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• string：ホスト名。

使用法

-- Given a request to https://example.com:1234/v1/movies

kong.request.get_host() -- "example.com"

kong.request.get_port()

リクエストのURLのポートコンポーネントを返します。値が返されます Lua番号として。

フェーズ

• certificate, rewrite, access, header_filter, response, body_filter, log, admin_api

戻り値

• number：ポート。

使用法

-- Given a request to https://example.com:1234/v1/movies

kong.request.get_port() -- 1234

kong.request.get_forwarded_scheme()

リクエストの URL のスキームコンポーネントを返しますが、信頼できるソースからの場合は X-Forwarded-Proto も考慮します。戻り値は小文字に正規化されます。

以下のいくつかのKong構成パラメータに応じて、この関数がX-Forwarded-Protoを考慮するかどうかが決まります。

• trusted_ips
• real_ip_header
• real_ip_recursive

注意 ：Kongは、ngx_http_realip_moduleによってサポートされていないForwarded HTTP Extension（RFC 7239）のサポートを提供していません。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• string：転送されたスキーム。

使用法

kong.request.get_forwarded_scheme() -- "https"

kong.request.get_forwarded_host()

リクエストのURLのホストコンポーネント、または「ホスト」ヘッダーの値を返します。kong.request.get_host() とは異なり、この関数は、信頼できるソースからのものであるかどうかもX-Forwarded-Hostを考慮します。戻り値は小文字に正規化されます。

以下のいくつかのKong構成パラメータに応じて、この関数がX-Forwarded-Hostを考慮するかどうかが決まります。

• trusted_ips
• real_ip_header
• real_ip_recursive

注意 ：Kongは、ngx_http_realip_moduleによってサポートされていないForwarded HTTP Extension（RFC 7239）のサポートを提供していません。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• string: 転送されたホスト。

使用法

kong.request.get_forwarded_host() -- "example.com"

kong.request.get_forwarded_port()

リクエストのURLのポートコンポーネントを返しますが、信頼できるソースからの場合は、X-Forwarded-Hostも考慮します。値 はLua番号として返されます。

以下のいくつかのKong構成パラメータに応じて、この関数がX-Forwarded-Protoを考慮するかどうかが決まります。

• trusted_ips
• real_ip_header
• real_ip_recursive

注意 ：Kongは、ngx_http_realip_moduleによってサポートされていないForwarded HTTP Extension（RFC 7239）のサポートを提供していません。

L4 ポートマッピング（またはフォワーディング）の背後でKongを実行する場合は、次の構成もできます。

• port_maps

port_maps構成パラメータを使用すると、この関数でKongがリッスンしているポートにマッピングされるポートを返すことができます（両者が異なる場合）。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• number：転送されたポート。

使用法

kong.request.get_forwarded_port() -- 1234

kong.request.get_forwarded_path()

リクエストのURLのパスコンポーネントを返しますが、信頼できるソースからの場合は、X-Forwarded-Path も考慮します。値 は Lua 文字列として返されます。

以下のいくつかのKong構成パラメータに応じて、この関数がX-Forwarded-Pathを考慮するかどうかが決まります。

• trusted_ips
• real_ip_header
• real_ip_recursive

注意 ：Kongはリクエストパスの正規化を行いません。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• string: 転送されたパス。

使用法

kong.request.get_forwarded_path() -- /path

kong.request.get_forwarded_prefix()

アップストリームにプロキシする前にKongが除外するリクエストURLのプレフィックスパスコンポーネントを返します。 また、X-Forwarded-Prefixの提供元が信頼できるかどうかをチェックし、提供された場合、そのまま使用します。 値はLua文字列として返されます。

信頼できるX-Forwarded-Prefixがパスされない場合、Kongルーターがリクエストパスの接頭辞を削除する可能性があるため、この関数はKongがそのルーター（accessフェーズ）を実行した後に呼び出される必要があります。削除されたパスは、信頼できるX-Forwarded-Prefixヘッダーがすでにリクエストに存在しない限り、この関数の戻り値になります。

以下のいくつかのKong構成パラメータに応じて、この関数がX-Forwarded-Prefixを考慮するかどうかが決まります。

• trusted_ips
• real_ip_header
• real_ip_recursive

注意 ：Kongはリクエストパスの接頭辞を正規化しません。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• string|nil：転送されたパスプレフィックス、またはプレフィックスが削除されていない場合はnil。

使用法

kong.request.get_forwarded_prefix() -- /prefix

kong.request.get_http_version()

リクエストでクライアントが使用したHTTPバージョンをLuaの数値として返します。1、1.1、2.0、あるいはnilなどの値は、認識できない値として返します。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• number|nil: Lua 番号としての HTTP バージョン。

使用法

kong.request.get_http_version() -- 1.1

kong.request.get_method()

リクエストのHTTPメソッドを返します。値は大文字に正規化されます。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• string: リクエストメソッド。

使用法

kong.request.get_method() -- "GET"

kong.request.get_path()

リクエストの URL の正規化されたパス コンポーネントを返します。戻り値は kong.request.get_raw_path() と同じですが、RFC 3986 のセクション 6 に従って正規化されます。

• 非予約文字のパーセントエンコーディングされた値はデコードされます（%20 は となります）。
• 予約されている文字をパーセントでエンコードした値は、大文字の16進値となります。（%2fは%2Fになります）。
• 相対パス要素（/.と/..）は逆参照されます。
• 重複するスラッシュは統合されます（//は/になります）。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• string：パス

使用法

-- Given a request to https://example.com/t/Abc%20123%C3%B8%2f/parent/..//test/./

kong.request.get_path() -- "/t/Abc 123ø%2F/test/"

kong.request.get_raw_path()

リクエストのURLのパスコンポーネントを返します。これは正規化されて おらず、クエリ文字列を含みません。

注: リクエスト処理中に文字列比較を実行するために生のパスを使用すること（ルーティング、ACL/認可チェック、流量制限キーの設定など）は、プラグインのコードがパストラバーサル攻撃に対して脆弱になるため、安全でないと広く考えられています。このようなユースケースでは、kong.request.get_path() を推奨します。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• string: パス。

使用法

-- Given a request to https://example.com/t/Abc%20123%C3%B8%2f/parent/..//test/./?movie=foo

kong.request.get_raw_path() -- "/t/Abc%20123%C3%B8%2f/parent/..//test/./"

kong.request.get_path_with_query()

ある場合は、クエリ文字列とパスを返します。変換や正規化は行われません。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• string: クエリ文字列を含むパス。

使用法

-- Given a request to https://example.com:1234/v1/movies?movie=foo

kong.request.get_path_with_query() -- "/v1/movies?movie=foo"

kong.request.get_raw_query()

リクエストのURLのクエリコンポーネントを返します。これはいかなる方法でも正規化されておらず（特殊文字のURL暗号解読を含む）、?の先行文字を含みません。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• string: リクエストの URL のクエリコンポーネント。

使用法

-- Given a request to https://example.com/foo?msg=hello%20world&bla=&bar

kong.request.get_raw_query() -- "msg=hello%20world&bla=&bar"

kong.request.get_query_arg()

現在のリクエストのクエリ引数から取得した、指定された引数の値を返します。

戻り値は、string、ブール値true（引数に値が指定されない場合）、またはnil（name 付きの引数が見つからなかった場合）のいずれかです。

クエリ文字列に同じ名前の引数が複数回存在する場合、この関数は最初に発生した値を返します。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• string|boolean|nil: 引数の値。

使用法

-- Given a request GET /test?foo=hello%20world&bar=baz&zzz&blo=&bar=bla&bar

kong.request.get_query_arg("foo") -- "hello world"
kong.request.get_query_arg("bar") -- "baz"
kong.request.get_query_arg("zzz") -- true
kong.request.get_query_arg("blo") -- ""

kong.request.get_query([max_args])

クエリ文字列から取得したクエリ引数のテーブルを返します。キーは、 クエリ引数名です。値は、引数付きの文字列か、 引数に値が指定されていない場合はブーリアン true、 またはクエリ文字列に引数が複数回指定された場合は配列のいずれかです。キーと 値は URL エンコードされたエスケープ ルールに従ってエスケープ解除されます。

クエリ文字列 ?foo&bar は 2 つのブーリアンtrue 引数に変換されることに注意してください。 また ?foo=&bar= は、空の文字列を含む2つの文字列引数に変換されます。

デフォルトでは、この関数は最大 100個 の引数（または lua_max_uri_argsを使用して構成されたもの)を返します。オプションの max_args 引数は、 この制限をカスタマイズするために指定できますが、 1 より大きく、 1000 以下でなければなりません。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

パラメータ

• max_args （number、 オプション ）：解析される引数の最大数に制限を 設定します。

戻り値

• table: クエリ文字列のテーブル表現。

使用法

-- Given a request GET /test?foo=hello%20world&bar=baz&zzz&blo=&bar=bla&bar

for k, v in pairs(kong.request.get_query()) do
  kong.log.inspect(k, v)
end

-- Will print
-- "foo" "hello world"
-- "bar" {"baz", "bla", true}
-- "zzz" true
-- "blo" ""

kong.request.get_header(name)

指定したリクエストヘッダーの値を返します。

戻り値はstring、またはnil（name 付きのヘッダーがリクエストに見つからなかった場合）のいずれかです。同じ名前のヘッダーがリクエストに複数回存在する場合、この関数はこのヘッダーで最初に登場する値を返します。

ヘッダー名は大文字と小文字を区別せず、小文字に正規化されています。また、ダッシュ（-）はアンダースコア（_）を使って書くことができます。つまり、ヘッダー X-Custom-Header は x_custom_header として取得することもできます。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

パラメータ

• name ( string ): 返されるヘッダーの名前

戻り値

• string|nil: ヘッダーの値、または存在しない場合は nil

使用法

-- Given a request with the following headers:

-- Host: foo.com
-- X-Custom-Header: bla
-- X-Another: foo bar
-- X-Another: baz

kong.request.get_header("Host")            -- "foo.com"
kong.request.get_header("x-custom-header") -- "bla"
kong.request.get_header("X-Another")       -- "foo bar"

kong.request.get_headers([max_headers])

リクエストヘッダーを保持する Lua テーブルを返します。キーはヘッダー名です。 値はヘッダー値を含む文字列か、ヘッダーが複数回送信された場合は文字列の配列になります。このテーブルのヘッダー名は大文字と小文字を区別せず、小文字に正規化されています。また、ダッシュ（-）はアンダースコア（_）を使って書くことができます。つまり、ヘッダー X-Custom-Header は x_custom_header として取得することもできます。

デフォルトでは、この関数は最大 100個 のヘッダーを返します。オプションの max_headers引数を指定してこの制限をカスタマイズできますが、 1 より大きく、 1000 以下である必要があります。

デフォルトでは、この関数は最大 100 個のヘッダー（または lua_max_req_headersを使用して設定されたもの）を返します。オプションの max_headers引数を指定してこの制限をカスタマイズできますが、 1 より大きく、 1000 以下である必要があります。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

パラメータ

• max_headers （number、 オプション ）：解析されるヘッダーの最大数に制限を設定します。

戻り値

• table：テーブル形式の要求ヘッダー。

使用法

-- Given a request with the following headers:

-- Host: foo.com
-- X-Custom-Header: bla
-- X-Another: foo bar
-- X-Another: baz
local headers = kong.request.get_headers()

headers.host            -- "foo.com"
headers.x_custom_header -- "bla"
headers.x_another[1]    -- "foo bar"
headers["X-Another"][2] -- "baz"

kong.request.get_raw_body()

本体にサイズ(空)がない場合、この関数は空文字列を返します。 ボディのサイズが Nginx のバッファサイズ ( client_body_buffer_size によって設定される) より大きい場合、この関数は失敗し、この制限を説明するエラー メッセージを返します。ただし、max_allowed_file_size が設定され、0 に等しいか、ディスクにバッファリングされるボディのサイズより大きい場合を除きます。

フェーズ

• rewrite、access、response、admin_api

戻り値

1. string|nil: プレーンなリクエストボディ、またはNGINXの一時的なバッファに収まらない場合はnil。
2. nil|string：エラーメッセージ。

使用法

-- Given a body with payload "Hello, Earth!":

kong.request.get_raw_body():gsub("Earth", "Mars") -- "Hello, Mars!"

kong.request.get_body（[mimetype[, max_args]])

リクエストデータをキー/値テーブルとして返します。ハイレベルな利便性機能。

ボディは最も適切な形式で解析されます。

• mimetype が指定されている場合、リクエストされたコンテンツタイプを持つボディをデコードします（サポートされている場合）。このタイプはリクエストにあるどのコンテンツよりも優先されます。

  オプションの引数mimetypeには、次のいずれかの文字列を指定できます。

  • application/x-www-form-urlencoded
  • application/json
  • multipart/form-data

mimetypeが指定されているか、あるいはリクエストコンテンツタイプがリクエスト内に存在するかどうかにかかわらず、各コンテンツタイプは次のように動作します。

• リクエストコンテンツタイプが application/x-www-form-urlencodedの場合：
  • 本文をフォームエンコードされた状態で返します。
• リクエストコンテンツタイプが multipart/form-dataの場合：
  • ボディをmultipart-form-dataとして暗号解読します（multipart(kong.request.get_raw_body(), kong.request.get_header("Content-Type")):get_all()と同じ）。
• リクエストコンテンツタイプが application/jsonの場合：
  • ボディをJSONとしてデコードします（json.decode(kong.request.get_raw_body())と同じ）。
  • JSONの型は、一致するLuaの型に変換されます。
• リクエストに上記のいずれも含まれておらず、mimetype引数が設定されていない場合、nilが返され、ボディが解析できないことを示すエラーメッセージが表示されます。

オプションの引数 max_args を使用して、application/x-www-form-urlencoded のペイロードに対して解析されるフォーム引数の数に制限を設定できます。デフォルトは 100 （または lua_max_post_args を使用して設定されたもの）です。

3番目の戻り値は、本文を（mimetype引数のように） 解析に使用し、呼び出し元がどのMIMEタイプとして本文が解析されたかを 特定できるMIMEタイプを含む文字列です。

フェーズ

• rewrite、access、response、admin_api

パラメータ

• mimetype （string、 オプション ）：MIMEタイプ。
• max_args （number、 オプション ）：解析される引数の最大数に制限を 設定します。

戻り値

1. table|nil: ボディのテーブル表現。

2. string|nil：エラーメッセージ。

3. string|nil: 使用される MIME タイプ mimetype。

使用法

local body, err, mimetype = kong.request.get_body()
body.name -- "John Doe"
body.age  -- "42"

kong.request.get_start_time()

リクエストの開始時刻をUnixエポックミリ秒単位で返します。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• number：タイムスタンプ

使用法

kong.request.get_start_time() -- 1649960273000

kong.request.get_uri_captures()

ルーターによって一致されるURIキャプチャを返します。

フェーズ

• rewrite、access、header_filter、response、body_filter、log、admin_api

戻り値

• table：名前のないキャプチャと名前の付いたキャプチャを含むテーブル。

使用法

local captures = kong.request.get_uri_captures()
for idx, value in ipairs(captures.unnamed) do
  -- do what you want to captures
end
for name, value in pairs(captures.named) do
  -- do what you want to captures
end