コンテンツにスキップ
|
Kong Gateway
3.4.x LTS
report-issue問題を報告する
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。

kong.service.request

サービスに送信されたリクエストを操作するモジュールです。

kong.service.request.enable_buffering()

バッファリングされたプロキシを有効にして、プラグインがサービス本体と応答ヘッダーに同時にアクセスできるようにします。

フェーズ

  • rewrite, access

    Returns

  • 何も起こりません。

使用状況

kong.service.request.enable_buffering()

kong.service.request.set_scheme（スキーム）

リクエストをサービスにプロキシするときに使用するプロトコルを設定します。

フェーズ

  • access

    Parameters

  • スキーム （string）: 使用するスキーム。サポートされている値は"http"または "https"です。

戻り値

  • 何も起こりません。無効な入力に対してはエラーがスローされます。

使用状況

kong.service.request.set_scheme("https")

kong.service.request.set_path(path)

サービスに対するリクエストのパスコンポーネントを設定します。

入力は、 正規化された 任意のURI（UTF-8文字を含む）を受け付けます。 このAPIはリクエストを有効化するため、RFCに従って 必要なエスケープを行います。

入力にはクエリー文字列を 含めないで ください。

フェーズ

  • access

    Parameters

  • パス ( string ): パス文字列。特殊文字とUTF-8 文字は許可されます。例: "/v2/movies"または"/foo/😀" 。

戻り値

  • 何も起こりません。無効な入力に対してはエラーがスローされます。

使用状況

kong.service.request.set_path("/v2/movies")

kong.service.request.set_raw_query(query)

要求のクエリ文字列をサービスに設定します。query引数は 文字列（先頭の?文字を除く）であり、いかなる方法でも 処理されません。

引数のLuaテーブルからクエリ文字列を設定する高レベルの関数については、 kong.service.request.set_query()を参照してください。

フェーズ

  • rewrite, access

パラメータ

  • クエリ （string）：生のクエリ文字列。例： "foo=bar&bla&baz=hello%20world"。

戻り値

  • 何も起こりません。無効な入力に対してはエラーがスローされます。

使用状況

kong.service.request.set_raw_query("zzz&bar=baz&bar=bla&bar&blo=&foo=hello%20world")

kong.service.request.set_method（メソッド）

サービスに対するリクエストの HTTP メソッドを設定します。

フェーズ

  • rewrite, access

パラメータ

  • メソッド （string）: メソッドの文字列で、 すべて大文字である必要があります。サポートされている値は次のとおりです: "GET"、"HEAD"、"PUT"、"POST"、 "DELETE"、"OPTIONS"、"MKCOL"、"COPY"、"MOVE"、"PROPFIND"、 "PROPPATCH"、"LOCK"、"UNLOCK"、"PATCH"、または"TRACE"。

戻り値

  • 何も起こりません。無効な入力に対してはエラーがスローされます。

使用状況

kong.service.request.set_method("DELETE")

kong.service.request.set_query(args)

リクエストのクエリ文字列をサービスに設定します。

kong.service.request.set_raw_query() とは異なり、query 引数は、各キーが文字列（引数の名前に対応）で、各値がブール値、文字列、または文字列またはブール値の配列で構成されたテーブルである必要があります。さらに、すべての文字列値は URL エンコードされます。

結果のクエリ文字列には、辞書順のキーが含まれます。同じキー内のエントリの順序（値が配列として指定されている場合）は 保持されます。

クエリ文字列の生成をさらに制御する必要がある場合は、生のクエリ 文字列は kong.service.request.set_raw_query() の文字列として指定できます。

フェーズ

  • rewrite, access

パラメータ

  • args （table）： 各キーは文字列（引数の名前に対応）で、各値はブール値、文字列、または文字列かブール値の配列のいずれかです。 指定された文字列値はすべてURLエンコード形式に変換されます。

戻り値

  • 何も起こりません。無効な入力に対してはエラーがスローされます。

使用状況

kong.service.request.set_query({
  foo = "hello world",
  bar = {"baz", "bla", true},
  zzz = true,
  blo = ""
})
-- Produces the following query string:
-- bar=baz&bar=bla&bar&blo=&foo=hello%20world&zzz

kong.service.request.set_header(header, value)

指定された値を使用して、サービスへのリクエストのヘッダーを設定します。既存のヘッダーに同じ名前があれば上書きされます。

header引数が"host"（大文字と小文字を区別しない）である場合は、サービスに対するリクエストのSNIも設定されます。

フェーズ

  • rewrite, access,balancer

パラメータ

  • header (string): ヘッダー名。例: “X-Foo”。
    • value （string|boolean|number）：ヘッダーの値。例：”hello world”。

    戻り値

  • 何も起こりません。無効な入力に対してはエラーがスローされます。

使用状況

kong.service.request.set_header("X-Foo", "value")

kong.service.request.add_header（ヘッダー、値）

指定された値を持つリクエストヘッダーをサービスへのリクエストに追加します。kong.service.request.set_header() とは異なり、この関数は既存の同名のヘッダーを 削除しません。代わりに、リクエストに存在するヘッダーが 複数回出現します。ヘッダーが追加される順序は保持されます。

フェーズ

  • rewrite, access

パラメータ

  • ヘッダー ( string ): ヘッダー名。例：”Cache-Control”.
    • value ( string|number|boolean ): ヘッダーの値。例: “no-cache”。

    Returns

  • 何も起こりません。無効な入力に対してはエラーがスローされます。

使用状況

kong.service.request.add_header("Cache-Control", "no-cache")
kong.service.request.add_header("Cache-Control", "no-store")

kong.service.request.clear_header(header)

サービスへのリクエストから指定されたヘッダーのすべての出現を削除します。

フェーズ

  • rewrite, access

パラメータ

  • ヘッダー （string）：ヘッダー名。例：” X-Foo”。

戻り値

  • 何も起こりません。無効な入力に対してはエラーがスローされます。ヘッダーが削除されなかった場合、関数はエラーをスローしません。

使用状況

kong.service.request.set_header("X-Foo", "foo")
kong.service.request.add_header("X-Foo", "bar")
kong.service.request.clear_header("X-Foo")
-- from here onwards, no X-Foo headers will exist in the request

kong.service.request.set_headers(headers)

リクエストのヘッダーをサービスに設定します。kong.service.request.set_header()とは異なり、headers引数は、各キーが文字列（ヘッダーの名前に対応）で、各値が文字列または文字列の配列であるテーブルである必要があります。

結果のヘッダーは辞書順に生成されます。同じ名前のエントリの順序（値が配列として指定されている場合）は保持されます。

この関数は、headers引数で指定されたものと同じ名前を持つ既存のヘッダーを上書きします。その他のヘッダーは変更されません。

"Host"ヘッダーが設定されている場合（大文字と小文字を区別しない）、サービスに対するリクエストのSNIも設定されます。

フェーズ

  • rewrite, access

パラメータ

  • ヘッダー (table): 各キーがヘッダー名を含む文字列で、各値は文字列または文字列の配列であるテーブル。

戻り値

  • 何も起こりません。無効な入力に対してはエラーがスローされます。

使用状況

kong.service.request.set_header("X-Foo", "foo1")
kong.service.request.add_header("X-Foo", "foo2")
kong.service.request.set_header("X-Bar", "bar1")
kong.service.request.set_headers({
  ["X-Foo"] = "foo3",
  ["Cache-Control"] = { "no-store", "no-cache" },
  ["Bla"] = "boo"
})

-- Will add the following headers to the request, in this order:
-- X-Bar: bar1
-- Bla: boo
-- Cache-Control: no-store
-- Cache-Control: no-cache
-- X-Foo: foo3

kong.service.request.set_raw_body(body)

サービスに対するリクエストのボディを設定します。

body 引数は文字列である必要があり、処理されることはありません。この関数は、 Content-Length ヘッダーも適切に設定します。空のボディを設定するには、この関数に空の文字列（""）を指定します。

リクエストコンテンツタイプに基づいて本文を設定する上位レベルの機能については、kong.service.request.set_body() を参照してください。

フェーズ

  • access, rewrite

    Parameters

  • body (string): 生のボディ部。

戻り値

  • 何も起こりません。無効な入力に対してはエラーがスローされます。

使用状況

kong.service.request.set_raw_body("Hello, world!")

kong.service.request.set_body(args[, mimetype])

サービスに対するリクエストボディを設定します。kong.service.request.set_raw_body()と異なり、args引数は必ずテーブル形式で、MIMEタイプでエンコードされます。エンコードに使用するMIMEタイプは、オプションのmimetype引数で指定でき、指定しない場合は、クライアントリクエストのContent-Typeヘッダーに基づき選択されます。

Content-TypeヘッダーのMIMEタイプに基づき、次の動作が行われます。

  • application/x-www-form-urlencoded: 引数をフォームエンコード形式に 変換します。キーは辞書 順で作成されます。同じキー内のエントリの順序（値が 配列として指定されている場合）は保持されます。指定された文字列値はすべて URL エンコード形式に変換されます。

  • multipart/form-data：引数をmultipart form dataとしてエンコードします。

  • application/json: 引数をJSONとしてエンコードします （kong.service.request.set_raw_body(json.encode(args))と同様に）。Luaの型は 一致するJSONの型に変換されます。

MIMEタイプが上記のいずれでもない場合は、この関数はnilと、本文をエンコードできなかったことを示すエラーメッセージを返します。

mimetype引数が指定されている場合、Content-Typeヘッダーはサービスへのリクエストに応じて設定されます。

ボディ生成のさらなる制御が必要な場合は、生のボディを kong.service.request.set_raw_body()を含む文字列として指定できます。

フェーズ

  • access, rewrite

    Parameters

  • args (table): 適切な形式に変換すされるデータ表で ボディに保管されます。

  • mimetype （string、 オプション ）：次のいずれかになります。

戻り値

  1. boolean|nil: 成功の場合は true、それ以外は nil です。

  2. string|nil：成功した場合はnil、エラーの場合はエラーメッセージ。無効な入力に対してエラーをスローします。

使用状況

kong.service.set_header("application/json")
local ok, err = kong.service.request.set_body({
  name = "John Doe",
  age = 42,
  numbers = {1, 2, 3}
})

-- Produces the following JSON body:
-- { "name": "John Doe", "age": 42, "numbers":[1, 2, 3] }

local ok, err = kong.service.request.set_body({
  foo = "hello world",
  bar = {"baz", "bla", true},
  zzz = true,
  blo = ""
}, "application/x-www-form-urlencoded")

-- Produces the following body:
-- bar=baz&bar=bla&bar&blo=&foo=hello%20world&zzz

kong.service.request.disable_tls()

ngx_stream_proxy_module のアップストリームへの TLS ハンドシェイクを無効にします。 これは proxy_ssl ディレクティブを上書きし、現在のストリームセッションでは効果的に off に設定します。

この関数が呼び出されると、現在のセッションで TLS ハンドシェイクを再度有効にすることはできません。

フェーズ

  • preread, balancer

戻り値

  1. boolean|nil: 操作が成功した場合は true、エラーが発生した場合は nil。

  2. string|nil: エラーがあった場合、その内容を説明するエラーメッセージ。

使用状況

local ok, err = kong.service.request.disable_tls()
if not ok then
  -- do something with error
end