旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。

Admin API

Kong Gateway API 仕様が利用可能になりました。

仕様	Insomniaのリンク
EnterpriseベータAPI仕様
オープンソースのベータ版API仕様

Kong Gatewayには、管理用の 内部 RESTful Admin APIが付属しています。 Admin APIへのリクエストはクラスタ内のどのノードにも送信でき、Kongはすべての ノード間で構成の一貫性を維持します。

• 8001は、Admin APIがリッスンするデフォルトのポートです。
• 8444 は、Admin API への HTTPS トラフィックのデフォルトポートです。

このAPIは内部使用向けに設計されており、Kongを完全に制御可能にします。そのためKong環境を設定する際には、このAPIが不当に公開されることがないよう、注意してください。Admin APIを保護する方法については、このドキュメントを参照してください。

DBレスモード

DB-lessモードでは、Admin APIを使用して新しい宣言型構成を読み込み、現在の構成を検査できます。DB-lessモードでは、各KongノードのAdmin APIは独立して機能し、特定のKongノードのメモリの状態を反映します。これは、Kongノード間のデータベース連携がないためです。

DB レスモードでは、Kong Gatewayを宣言的に構成します。したがって、Admin APIはほとんど読み取り専用です。実行できるタスクはすべて宣言型構成の処理に関連するものであり、次のものが含まれます。

• スキーマに照らした構成の検証
• スキーマに対するプラグイン構成の検証
• 宣言型構成の再読み込み
• ロードバランサー内でのターゲットのヘルスステータスの設定

宣言型構成

エンティティの宣言型構成をKong Gatewayに読み込むには、declarative_configプロパティを介して起動時に実行する方法と、/configエンドポイントを使用してAdmin APIを介して実行時に行う方法の2通りあります。

宣言型構成を使い始めるには、エンティティ定義を含むファイル（YAMLまたはJSON形式）が必要です。次のコマンドを使用して、サンプルの宣言型構成を生成できます。

kong config init

現在のディレクトリに、適切な構造と例が含まれたkong.ymlという名前のファイルが生成されます。

宣言型構成の再読み込み

このエンドポイントでは、DB-less Kong を新しい宣言型構成データファイルでリセットできます。以前の内容はすべてメモリから消去され、指定されたファイル内に記述したエンティティがそれに取って代わります。

ファイル形式の詳細については、宣言型構成ドキュメントを参照してください。

リクエストのクエリ文字列パラメータ

レスポンス

HTTP 200 OK

{
    {
        "services": [],
        "routes": []
    }
}

レスポンスには、入力ファイルから解析されたすべてのエンティティのリストが含まれます。

サポートされているコンテンツタイプ

Admin APIは、すべてのエンドポイントで3つのコンテンツタイプを受け入れます。

• application/json

ボディが複雑（複雑なプラグイン構成など）な場合に便利で、単に送信したいデータのJSON表現を送信します。例：

{
    "config": {
        "limit": 10,
        "period": "seconds"
    }
}

以下は、test-service という名前のサービスにルートを追加する例です。

curl -i -X POST http://localhost:8001/services/test-service/routes \
     -H "Content-Type: application/json" \
     -d '{"name": "test-route", "paths": [ "/path/one", "/path/two" ]}'

• application/x-www-form-urlencoded

基本的なリクエストボディとしては十分に単純であるため、ほとんどの場合はこれを使用します。 ネストされた値を送信する場合、Kongはネストされたオブジェクトがドット付きのキーを使って参照されることを想定しています。 以下に例を示します。

config.limit=10&config.period=seconds

配列を指定するときは、値を順番に送信するか、角括弧を使用します（角括弧内の番号付けはオプションですが、指定する場合は1インデックスで連続している必要があります）。以下は、test-service という名前のサービスに追加されたルートの例です。

curl -i -X POST http://localhost:8001/services/test-service/routes \
     -d "name=test-route" \
     -d "paths[1]=/path/one" \
     -d "paths[2]=/path/two"

次の2つの例は上記のものと同じですが、明示的ではありません。

curl -i -X POST http://localhost:8001/services/test-service/routes \
     -d "name=test-route" \
     -d "paths[]=/path/one" \
     -d "paths[]=/path/two"

curl -i -X POST http://localhost:8001/services/test-service/routes \
    -d "name=test-route" \
    -d "paths=/path/one" \
    -d "paths=/path/two"

• multipart/form-data

URLエンコードと同様に、このコンテンツタイプでは、ドットキーを使用してネストされたオブジェクトを参照します。以下は、LuaファイルをプリファンクションKongプラグインに送信する例です。

curl -i -X POST http://localhost:8001/services/plugin-testing/plugins \
     -F "name=pre-function" \
     -F "config.access=@custom-auth.lua"

このコンテンツタイプの配列を指定する場合は、配列インデックスを指定する必要があります。次は、test-service という名前のサービスに追加されたルートの例です。

curl -i -X POST http://localhost:8001/services/test-service/routes \
     -F "name=test-route" \
     -F "paths[1]=/path/one" \
     -F "paths[2]=/path/two"

ワークスペースでのAPIの使用

ワークスペースを指定しないリクエストは、defaultワークスペースを対象とします。

別のワークスペースをターゲットにするには、エンドポイントの前にワークスペース名または ID を付けます。

http://localhost:8001/<WORKSPACE_NAME|ID>/<endpoint id="sl-md0000000">

たとえば、ワークスペースを指定しない場合は、このリクエストは、default ワークスペースからサービスのリストを取得します。

curl -i -X GET http://localhost:8001/services

このリクエストはワークスペースSREからすべてのサービスを取得します。

curl -i -X GET http://localhost:8001/SRE/services

インフォメーションルート

ノード情報の取得

ノードについての一般的な詳細を取得します。

レスポンス

HTTP 200 OK

{
    "hostname": "",
    "node_id": "6a72192c-a3a1-4c8d-95c6-efabae9fb969",
    "lua_version": "LuaJIT 2.1.0-beta3",
    "plugins": {
        "available_on_server": [
            ...
        ],
        "enabled_in_cluster": [
            ...
        ]
    },
    "configuration": {
        ...
    },
    "tagline": "Welcome to Kong",
    "version": "0.14.0"
}

• node_id: 実行中の Kong ノードを表す UUID。この UUID は Kong が起動するとランダムに生成されるので、ノードは再起動するたびに異なる node_id を持つことになります。
• available_on_server: ノードにインストールされるプラグインの名前。
• enabled_in_cluster: 有効化されている、または設定されているプラグインの名前。つまり、すべての Kong ノードによってデータストアに現在共有されているプラグイン構成です。

エンドポイントまたはエンティティの有無の確認

HTTP GETと似ていますが、本文は返しません。エンドポイントが存在する場合はHTTP 200 を返し、存在しない場合はHTTP 404を返します。他のステータスコードも可能です。

レスポンス

HTTP 200 OK

Access-Control-Allow-Origin: *
Content-Length: 11389
Content-Type: application/json; charset=utf-8
X-Kong-Admin-Latency: 1

エンドポイント別HTTPメソッドの一覧表示

エンドポイントでサポートされているすべてのHTTPメソッドを一覧表示します。これは、CORSプリフライトリクエストでも使用できます。

レスポンス

HTTP 204 No Content

Access-Control-Allow-Headers: Content-Type
Access-Control-Allow-Methods: GET, HEAD, OPTIONS
Access-Control-Allow-Origin: *
Allow: GET, HEAD, OPTIONS

使用可能なエンドポイントの一覧化

Admin APIによって提供される使用可能なエンドポイントをすべて一覧表示します。

レスポンス

HTTP 200 OK

{
    "data": [
        "/",
        "/acls",
        "/acls/{acls}",
        "/acls/{acls}/consumer",
        "/basic-auths",
        "/basic-auths/{basicauth_credentials}",
        "/basic-auths/{basicauth_credentials}/consumer",
        "/ca_certificates",
        "/ca_certificates/{ca_certificates}",
        "/cache",
        "/cache/{key}",
        "..."
    ]
}

スキーマに対する構成の検証

エンティティスキーマに照らして構成の有効性を確認します。 これにより、Admin APIのエンティティエンドポイントにリクエストを送信する前に入力内容をテストできます。

これは、入力の構成が正しいことをチェックするスキーマ検証チェックのみを実行することに注意してください。指定された構成を使用するエンティティエンドポイントへのリクエストは、無効な外部キー関係や、データストアの内容に対する一意性チェックのエラーなど、他の理由で失敗する可能性があります。

レスポンス

HTTP 200 OK

{
    "message": "schema validation successful"
}

エンティティスキーマを取得する

エンティティのスキーマを取得します。これは、エンティティ受け入れるフィールドを理解するのに役立ち、Kongへのサードパーティ統合を構築するために使用できます。

レスポンス

HTTP 200 OK

{
    "fields": [
        {
            "id": {
                "auto": true,
                "type": "string",
                "uuid": true
            }
        },
        {
            "created_at": {
                "auto": true,
                "timestamp": true,
                "type": "integer"
            }
        },
        ...
    ]
}

プラグインスキーマを取得

プラグイン構成のスキーマを取得します。これは、プラグインが受け入れるフィールドを理解するのに役立ち、Kongのプラグインシステムにサードパーティ統合を構築するのに使用できます。

レスポンス

HTTP 200 OK

{
    "fields": {
        "hide_credentials": {
            "default": false,
            "type": "boolean"
        },
        "key_names": {
            "default": ["apikey"],
            "required": true,
            "type": "array"
        }
    }
}

スキーマに対するプラグイン構成の検証

プラグインエンティティスキーマに対してプラグイン構成の有効性を確認します。これにより、Admin APIのエンティティエンドポイントにリクエストを送信する前に入力内容をテストできます。

これは、入力の構成が正しいことをチェックするスキーマ検証チェックのみを実行することに注意してください。指定された構成を使用するエンティティエンドポイントへのリクエストは、無効な外部キー関係や、データストアの内容に対する一意性チェックのエラーなど、他の理由で失敗する可能性があります。

レスポンス

HTTP 200 OK

{
    "message": "schema validation successful"
}

Kongのタイマーのランタイムデバッグ情報の取得

lua-resty-timer-ngからランタイム統計データを取得します。

レスポンス

HTTP 200 OK

{   "worker": {
      "id": 0,
      "count": 4,
    },
    "stats": {
      "flamegraph": {
        "running": "@./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0\n",
        "elapsed_time": "@./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 17\n",
        "pending": "@./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0\n"
      },
      "sys": {
          "running": 0,
          "runs": 7,
          "pending": 0,
          "waiting": 7,
          "total": 7
      },
      "timers": {
          "healthcheck-localhost:8080": {
              "name": "healthcheck-localhost:8080",
              "meta": {
                  "name": "@/build/luarocks/share/lua/5.1/resty/counter.lua:71:new()",
                  "callstack": "@./kong/plugins/prometheus/prometheus.lua:673:init_worker();@/build/luarocks/share/lua/5.1/resty/counter.lua:71:new()"
              },
              "stats": {
                  "finish": 2,
                  "runs": 2,
                  "elapsed_time": {
                      "min": 0,
                      "max": 0,
                      "avg": 0,
                      "variance": 0
                  },
                  "last_err_msg": ""
              }
          }
      }
    }
}

• worker：
  • id: 現在のNginxワーカープロセスの序数（0から始まります）。
  • count: Nginxワーカープロセスの合計数。
• stats.flamegraph：文字列エンコードされたタイマー関連のフレームグラフデータ。 brendangregg/FlameGraphを使ってフレームグラフSVGを生成できます。
• stats.sys：さまざまなタイプのタイマーの数を一覧表示します。
  • running: 実行中のタイマーの数。
  • pending: 保留中のタイマーの数。
  • waiting: 有効期限が切れていないタイマーの数。
  • total：実行中 + 保留中 + 待機中。
• timers.meta: 作成されたタイマーのプログラム呼び出しスタック。
  • name： 作成タイマーが作成された場所を格納する、自動的に生成された文字列。
  • callstack：このタイマーが作成された場所を示すLuaコールスタック文字列。
• timers.stats.elapsed_time: タイマーの各実行にかかった時間（秒）の最大値、最小値、平均値、および分散を格納するオブジェクト。
• timers.stats.runs: 実行の合計数。
• timers.stats.finish：成功した実行の合計数。

注：flamegraph、timers.meta、timers.stats.elapsed_timeキーは、Kong のlog_level構成がdebugに設定されている場合にのみ使用できます。 詳細については、lua-resty-timer-ngのドキュメントをご覧ください。

ヘルスルート

ノードステータスの取得

ノードに関する使用状況情報とともに、基盤となる nginx プロセスによって処理されている接続、データベース接続のステータス、ノードのメモリ使用量に関する基本的な情報を取得します。

Kongのプロセスを監視する場合、Kongはnginxの上に構築されているため、既存のすべてのnginx監視ツールまたはエージェントを使用できます。

レスポンス

HTTP 200 OK

{
    "database": {
      "reachable": true
    },
    "memory": {
        "workers_lua_vms": [{
            "http_allocated_gc": "0.02 MiB",
            "pid": 18477
          }, {
            "http_allocated_gc": "0.02 MiB",
            "pid": 18478
        }],
        "lua_shared_dicts": {
            "kong": {
                "allocated_slabs": "0.04 MiB",
                "capacity": "5.00 MiB"
            },
            "kong_db_cache": {
                "allocated_slabs": "0.80 MiB",
                "capacity": "128.00 MiB"
            },
        }
    },
    "server": {
        "total_requests": 3,
        "connections_active": 1,
        "connections_accepted": 1,
        "connections_handled": 1,
        "connections_reading": 0,
        "connections_writing": 1,
        "connections_waiting": 0
    },
    "configuration_hash": "779742c3d7afee2e38f977044d2ed96b"
}

• memory：メモリ使用量に関するメトリクス。
  • workers_lua_vms：Kongノードのすべてのワーカーを含む配列で、各エントリには以下が含まれます。
  • http_allocated_gc: collectgarbage("count")によって報告された、HTTPサブモジュールのLua仮想マシンの、アクティブなワーカーごとのメモリ使用情報。つまり過去10秒以内にプロキシ呼び出しを受信したワーカーです。
  • pid：ワーカーのプロセス識別番号。
  • lua_shared_dicts：Kongノード内のすべてのワーカーと共有されるディクショナリに関する情報の配列で、各配列ノードには、特定の共有ディクショナリ専用のメモリ量（capacity）と、そのメモリの使用量（allocated_slabs）が含まれています。これらの共有ディクショナリには、最近使用されていない（LRU）エビクション機能があるため、完全なディクショナリ（ allocated_slabs == capacityの場合）は適切に機能します。ただし、一部のディクショナリ、たとえば、HIT/MISS共有ディクショナリをキャッシュし、サイズを大きくすると、Kongノードの全体的なパフォーマンスに有益です。
  • メモリ使用量の単位と精度は、クエリ文字列の引数unitとscaleを使用して変更できます。
    • unit: b/B、k/K、m/M、g/Gのいずれかで、それぞれ、byte、kibibyte、mebibyte、gibibyteで結果を返します。「byte」がリクエストされた場合、応答のメモリ値は文字列ではなく数値型になります。デフォルトはmです。
    • scale：値が、人間が読めるメモリ文字列（「byte」以外の単位）で指定されている場合の小数点の右側の桁数。デフォルトは2です。次の方法で、共有ディクショナリのメモリ使用量を4桁の精度（kibibyte単位）で取得します。GET /status?unit=k&scale=4
• server: nginx HTTP/Sサーバーについてのメトリクス。
  • total_requests: クライアントリクエストの合計数。
  • connections_active: 待機中の接続を含む 、現在アクティブなクライアントの接続数。
  • connections_accepted：受け入れられたクライアントの接続の合計数。
  • connections_handled：処理された接続の合計数。通常、リソース制限に達していないかぎり、パラメータ値は受け入れられる値と同じです。
  • connections_reading：Kongがリクエストヘッダーを読み取っている現在の接続数。
  • connections_writing：nginxがレスポンスをクライアントに 書き戻している現在の接続数。
  • connections_waiting：リクエストを待機しているアイドル状態のクライアント接続の現在の数。
• database：データベースに関するメトリクス。
  • reachable：データベース接続の状態を反映する ブール値。このフラグは、データベース自体の正常性を 反映して いない ことに注意してください。
• configuration_hash: 現在の構成のハッシュ。このフィールドは、Kong ノードが DB レスモードまたはデータプレーン（DP）で実行されている場合にのみ返されます。特別な戻り値「00000000000000000000000000000000」は、Kong に現在有効な構成が読み込まれていないことを意味します。

タグ

タグは、Kongのエンティティに関連付けられた文字列です。

タグには、ほぼすべてのUTF-8文字を含めることができますが、次の例外があります。

• ,および/は、「and」と「or」を含むタグをフィルタリングするために予約されているため、タグでは使用できません。
• 印刷不能なASCII文字（スペース文字など）は使用できません。

ほとんどのコアエンティティは、作成時または編集時にtags属性で タグ付け できます。

タグは、?tagsクエリ文字列パラメータを介して、コアエンティティをフィルタリングするのにも使用できます。

たとえば、通常は以下を実行してすべてのサービスのリストを取得します。

GET /services

exampleタグが付けられたすべてのサービスを一覧表示するには、次のようにします。

GET /services?tags=example

動揺に、タグされたexample および adminのみを取得するよう、サービスをフィルタリングする場合は、以下を実行します。

GET /services?tags=example,admin

最後に、example または adminとタグ付けされたサービスをフィルタリングする場合は、次を使用できます。

GET /services?tags=example/admin

注意点：

• 次を使用して、1 度のリクエストで最大 5 つのタグを同時にクエリできます: , または /
• 演算子の混在はサポートされていません。同じクエリ文字列で,と/を混在させようとすると、エラーが発生します。
• コマンドラインから使用する場合、一部の文字を引用符で囲んだり、エスケープする必要がある場合があります。
• tags によるフィルタリングは、外部キー関係エンドポイントではサポートされていません。例えば、 tags パラメータは、次のようなリクエストでは無視されます。GET /services/foo/routes?tags=a,b
• offsetパラメータは、tagsパラメータが変更または削除された場合、動作が保証されません

すべてのタグの一覧表示

システム内のすべてのタグのページ分割されたリストを返します。

エンティティの一覧は、単一のエンティティタイプに限定されません。タグでタグ付けされたすべてのエンティティがこの一覧に表示されます。

エンティティに複数のタグが付けられている場合、そのエンティティのentity_idが結果の一覧に複数回表示されます。同様に、複数のエンティティに同じタグが付けられている場合、そのタグはこの一覧の複数の項目に表示されます。

レスポンス

HTTP 200 OK

{
    {
      "data": [
        { "entity_name": "services",
          "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4",
          "tag": "s1",
        },
        { "entity_name": "services",
          "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4",
          "tag": "s2",
        },
        { "entity_name": "routes",
          "entity_id": "60631e85-ba6d-4c59-bd28-e36dd90f6000",
          "tag": "s1",
        },
        ...
      ],
      "offset": "c47139f3-d780-483d-8a97-17e9adc5a7ab",
      "next": "/tags?offset=c47139f3-d780-483d-8a97-17e9adc5a7ab",
    }
}

タグ別にエンティティIDを一覧表示

指定タグでタグ付けされているエンティティを返します。

エンティティの一覧は、単一のエンティティタイプに限定されません。タグでタグ付けされたすべてのエンティティがこの一覧に表示されます。

レスポンス

HTTP 200 OK

{
    {
      "data": [
        { "entity_name": "services",
          "entity_id": "c87440e1-0496-420b-b06f-dac59544bb6c",
          "tag": "example",
        },
        { "entity_name": "routes",
          "entity_id": "8a99e4b1-d268-446b-ab8b-cd25cff129b1",
          "tag": "example",
        },
        ...
      ],
      "offset": "1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9",
      "next": "/tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9",
    }
}

ルートのデバッグ

すべてのコントロールプレーン（CP）ノードのノードログレベルを設定する

注 : このAPIはDBレスモードでは利用できません。

ハイブリッド（CP/DP）クラスタにデプロイされているすべてのコントロールプレーン（CP）ノードのログレベルを変更します。

使用可能な値の一覧については、http://nginx.org/en/docs/ngx_core_module.html#error_log を参照してください。

本番環境でノードのログレベルを debug に変更する場合は、ディスクがすぐにいっぱいになる可能性があるため、注意が必要です。デバッグログが終了したら、すぐにnoticeなどの上位レベルに戻してください。

現在、DP および DB レスノードのログレベルを変更することはできません。

Kong Gateway Enterpriseを使用する場合、このエンドポイントはRBACで保護できます

Kong Gateway Enterpriseを使用する場合、ログレベルの変更は監査ログに反映されます。

ログレベルの変更は、新しく生成されたワーカーを含めて、ノードのすべてのNginxワーカーに伝達されます。

現在、ユーザーがクラスタ全体のログレベルを動的に変更する場合、新しいノードがクラスタに参加すると、新しいノードは以前クラスタ全体に対して動的に設定されたログレベルではなく、以前のログレベルで実行されます。これを回避するには、起動の kong.conf 設定を KONG_LOG_LEVEL に設定して、新しいノードが適切なレベルで開始することを確認します。

レスポンス

HTTP 200 OK

{
    "message": "log level changed"
}

すべてのノードのノードログレベルの設定

注 : このAPIはDBレスモードでは利用できません。

クラスタ内のすべてのノードのログレベルを変更します。

使用可能な値の一覧については、http://nginx.org/en/docs/ngx_core_module.html#error_log を参照してください。

本番環境でノードのログレベルを debug に変更する場合は、ディスクがすぐにいっぱいになる可能性があるため、注意が必要です。デバッグログの取得が終了したら、すぐに notice などの上位レベルに戻してください。

現在、DP および DB レスノードのログレベルを変更することはできません。

Kong Gateway Enterpriseを使用する場合、このエンドポイントはRBACで保護できます

Kong Gateway Enterpriseを使用する場合、ログレベルの変更は監査ログに反映されます。

ログレベルの変更は、新しく生成されたワーカーを含めて、ノードのすべてのNginxワーカーに伝達されます。

現在、ユーザーがクラスタ全体のログレベルを動的に変更する場合、新しいノードがクラスタに参加すると、新しいノードは以前クラスタ全体に対して動的に設定されたログレベルではなく、以前のログレベルで実行されます。これを回避するには、起動の kong.conf 設定を KONG_LOG_LEVEL に設定して、新しいノードが適切なレベルで開始することを確認します。

レスポンス

HTTP 200 OK

{
    "message": "log level changed"
}

ノードのノードログレベルの取得

ノードの現在のログレベルを取得します。

可能な戻り値のリストについては、http://nginx.org/en/docs/ngx_core_module.html#error_logを参照してください。

レスポンス

HTTP 200 OK

{
    "message": "log level: debug"
}

単一ノードのログレベルの設定

注 : このAPIはDBレスモードでは利用できません。

ノードのログレベルを変更します。

使用可能な値の一覧については、http://nginx.org/en/docs/ngx_core_module.html#error_log を参照してください。

本番環境でノードのログレベルを debug に変更する場合は、ディスクがすぐにいっぱいになる可能性があるため、注意が必要です。デバッグログが終了したら、すぐにnoticeなどの上位レベルに戻してください。

現在、DP および DB レスノードのログレベルを変更することはできません。

Kong Gateway Enterpriseを使用する場合、このエンドポイントはRBACで保護できます

Kong Gateway Enterpriseを使用する場合、ログレベルの変更は監査ログに反映されます。

ログレベルの変更は、新しく生成されたワーカーを含めて、ノードのすべてのNginxワーカーに伝達されます。

レスポンス

HTTP 200 OK

{
    "message": "log level changed"
}

サービスオブジェクト

サービスエンティティは、その名のとおり、独自のアップストリームサービスのそれぞれを抽象化したものです。サービスの例としては、データ変換マイクロサービス、課金 API などがあります。

サービスの主な属性はURL（Kongがトラフィックをプロキシする場所）で、 単一の文字列として設定することも、protocol、host、 port、およびpathを個別に指定することもできます。

サービスはルートに関連付けられます（1つのサービスに複数のルートが関連付けられる場合があります）。ルートはKongのエントリポイントであり、クライアントリクエストに一致するルールを定義します。ルートが一致すると、Kongは、リクエストを関連付けられたサービスにプロキシします。Kongがトラフィックをプロキシする方法の詳細については、プロキシリファレンスを参照してください。

サービスは、タグ付けすることも、タグでフィルタリングすることもできます。

{
    "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
    "tls_verify": true,
    "tls_verify_depth": null,
    "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
    "enabled": true
}

サービスの追加

注 : このAPIはDBレスモードでは利用できません。

サービスを作成する

特定の証明書に関連付けられたサービスの作成

属性 | 説明 ——————————-:| ——————————- certificate name or id
必須 | 新しく作成されたサービスに関連付ける証明書の一意の識別子または name 属性。

リクエストボディ

属性名｜説明 —:| — name
任意 | サービス名。 retries
任意 | プロキシに失敗したときに実行する再試行回数。デフォルト: 5 protocol：アップストリーム（アプリケーション）との通信に使用されるプロトコル。指定できる値は、grpc、grpcs、http、https、tcp、tls、tls_passthrough、udp、ws、wss。デフォルトは、http。 host | アップストリームサーバーのホスト。ホスト値では大文字と小文字が区別されることにご注意ください。 port | アップストリームサーバポート。デフォルト：80 path
任意 | アップストリームサーバーへのリクエストに使用されるパス。 connect_timeout
任意 | アップストリームサーバーとの接続を確立するためのタイムアウト (ミリ秒単位)。デフォルト: 60000。write_timeout
任意 | アップストリームサーバーにリクエストを送信するための、2つの連続した書き込み操作の間のタイムアウト（ミリ秒）。デフォルト: 60000。read_timeout
任意｜アップストリームサーバーにリクエストを送信し、返ってくるまでの待機時間（ミリ秒単位）。デフォルト: 60000。tags
任意｜グループ化とフィルタリングのためにサービスに関連付けられた文字列の任意セットです。 client_certificate
任意 | アップストリームサーバーとの TLS ハンドシェイク時にクライアント証明書として使用する証明書。form-encodedでは、client_certificate.id=。JSONでは、'"client_certificate":{"id":""}を使用します。 tls_verify
*任意* | アップストリームサーバーのTLS証明書の検証を有効にするかどうか。nullに設定すると、Nginxのデフォルトが遵守されます。 tls_verify_depth
*任意* | アップストリームサーバーのTLS証明書を確認する際のチェーンの最大深度。nullに設定すると、Nginx のデフォルトが尊重されます。デフォルト: null。 ca_certificates
*任意* | アップストリームサーバーのTLS証明書を検証しながらトラストストアを構築するために使用されるCA 証明書オブジェクト UUID の配列。Nginxのデフォルトが尊重されるときに「null」に設定するとします。NginxのデフォルトのCAリストが指定されておらず、TLS検証が有効になっている場合、アップストリームサーバーとのハンドシェイクは常に失敗します (信頼できるCAがないため)。 form-encodedでは、表記はca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515です。JSONでは、配列を使用します。 enabled | サービスがアクティブかどうか。falseに設定すると、プロキシは、アタッチされたルートが存在しないかのように動作します (404)。デフォルト: true。 url
*短縮形属性* | protocol、host、port、pathを一度に設定するための短縮形属性。この属性は書き込み専用です(Admin APIはURLを返しません)。

レスポンス

HTTP 201 Created

{
    "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
    "tls_verify": true,
    "tls_verify_depth": null,
    "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
    "enabled": true
}

サービスの一覧表示

すべてのサービスの一覧化

特定の証明書に関連付けられたサービスの一覧表示

属性 | 説明 ——————————-:| ——————————- certificate name or id
必須 | サービスを取得する証明書の一意の識別子またはname属性。 このエンドポイントを使用すると、指定された証明書に関連付けられたサービスのみがリストされます。

レスポンス

HTTP 200 OK

{

"data": [{
    "id": "a5fb8d9b-a99d-40e9-9d35-72d42a62d83a",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"},
    "tls_verify": true,
    "tls_verify_depth": null,
    "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
    "enabled": true
}, {
    "id": "fc73f2af-890d-4f9b-8363-af8945001f7f",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/another_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["admin", "high-priority", "critical"],
    "client_certificate": {"id":"4506673d-c825-444c-a25b-602e3c2ec16e"},
    "tls_verify": true,
    "tls_verify_depth": null,
    "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
    "enabled": true
}],

    "next": "http://localhost:8001/services?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

サービスの取得

サービスの取得

属性 | 説明 ——————————-:| ——————————- service name or id
必須 | 取得するサービスの一意の識別子 または 名前。

特定の証明書に関連付けられたサービスを取得

属性 | 説明 ——————————-:| ——————————- certificate id
必須 | 取得する証明書の一意の識別子。 service name or id
必須 | 取得するサービスの一意の識別子 または 名前。

特定のルートに関連付けられたサービスの取得

属性 | 説明 ——————————-:| ——————————- route name or id
必須 | 取得するサービスに関連付けられたルートの一意の識別子 または 名前。

特定のプラグインに関連付けられたサービスの取得

属性 | 説明 ——————————-:| ——————————- plugin id
必須 | 取得するサービスに関連付けられたプラグインの一意の識別子。

レスポンス

HTTP 200 OK

{
    "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
    "tls_verify": true,
    "tls_verify_depth": null,
    "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
    "enabled": true
}

サービスの更新

注 : このAPIはDBレスモードでは利用できません。

サービスの更新

属性 | 説明 ——————————-:| ——————————- service name or id
必須 | 更新するサービスの一意の識別子 または 名前。

特定の証明書に関連付けられたサービスを更新

属性 | 説明 ——————————-:| ——————————- certificate id
必須 | 更新する証明書の一意の識別子。 service name or id
必須 | 更新するサービスの一意の識別子 または 名前。

特定のルートに関連付けられたサービスの更新

属性 | 説明 ——————————-:| ——————————- route name or id
必須 | 更新するサービスに関連付けられたルートの一意の識別子 または 名前。

特定のプラグインに関連付けられたサービスの更新

属性 | 説明 ——————————-:| ——————————- plugin id
必須 | 更新するサービスに関連付けられたプラグインの一意の識別子。

リクエストボディ

属性名｜説明 —:| — name
任意 | サービス名。 retries
任意 | プロキシに失敗したときに実行する再試行回数。デフォルト: 5 protocol：アップストリーム（アプリケーション）との通信に使用されるプロトコル。指定できる値は、grpc、grpcs、http、https、tcp、tls、tls_passthrough、udp、ws、wss。デフォルトは、http。 host | アップストリームサーバーのホスト。ホスト値では大文字と小文字が区別されることにご注意ください。 port | アップストリームサーバポート。デフォルト：80 path
任意 | アップストリームサーバーへのリクエストに使用されるパス。 connect_timeout
任意 | アップストリームサーバーとの接続を確立するためのタイムアウト (ミリ秒単位)。デフォルト: 60000。write_timeout
任意 | アップストリームサーバーにリクエストを送信するための、2つの連続した書き込み操作の間のタイムアウト（ミリ秒）。デフォルト: 60000。read_timeout
任意｜アップストリームサーバーにリクエストを送信し、返ってくるまでの待機時間（ミリ秒単位）。デフォルト: 60000。tags
任意｜グループ化とフィルタリングのためにサービスに関連付けられた文字列の任意セットです。 client_certificate
任意 | アップストリームサーバーとの TLS ハンドシェイク時にクライアント証明書として使用する証明書。form-encodedでは、client_certificate.id=。JSONでは、'"client_certificate":{"id":""}を使用します。 tls_verify
*任意* | アップストリームサーバーのTLS証明書の検証を有効にするかどうか。nullに設定すると、Nginxのデフォルトが遵守されます。 tls_verify_depth
*任意* | アップストリームサーバーのTLS証明書を確認する際のチェーンの最大深度。nullに設定すると、Nginx のデフォルトが尊重されます。デフォルト: null。 ca_certificates
*任意* | アップストリームサーバーのTLS証明書を検証しながらトラストストアを構築するために使用されるCA 証明書オブジェクト UUID の配列。Nginxのデフォルトが尊重されるときに「null」に設定するとします。NginxのデフォルトのCAリストが指定されておらず、TLS検証が有効になっている場合、アップストリームサーバーとのハンドシェイクは常に失敗します (信頼できるCAがないため)。 form-encodedでは、表記はca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515です。JSONでは、配列を使用します。 enabled | サービスがアクティブかどうか。falseに設定すると、プロキシは、アタッチされたルートが存在しないかのように動作します (404)。デフォルト: true。 url
*短縮形属性* | protocol、host、port、pathを一度に設定するための短縮形属性。この属性は書き込み専用です(Admin APIはURLを返しません)。

レスポンス

HTTP 200 OK

{
    "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
    "tls_verify": true,
    "tls_verify_depth": null,
    "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
    "enabled": true
}

サービスを更新または作成

注 : このAPIはDBレスモードでは利用できません。

サービスを作成または更新

属性 | 説明 ——————————-:| ——————————- service name or id
必須 | 作成または更新するサービスの一意の識別子 または 名前。

特定の証明書に関連付けられたサービスの作成または更新

属性 | 説明 ——————————-:| ——————————- certificate id
必須 | 作成または更新する証明書の一意の識別子。 service name or id
必須 | 更新するサービスの一意の識別子 または 名前。

特定のルートに関連付けられたサービスの作成または更新

属性 | 説明 ——————————-:| ——————————- route name or id
必須 | 作成または更新するサービスに関連付けられたルートの一意の識別子 または 名前。

特定のプラグインに関連付けられたサービスの作成または更新

属性 | 説明 ——————————-:| ——————————- plugin id
必須 | 作成または更新するサービスに関連付けられたプラグインの一意の識別子。

リクエストボディ

属性名｜説明 —:| — name
任意 | サービス名。 retries
任意 | プロキシに失敗したときに実行する再試行回数。デフォルト: 5 protocol：アップストリーム（アプリケーション）との通信に使用されるプロトコル。指定できる値は、grpc、grpcs、http、https、tcp、tls、tls_passthrough、udp、ws、wss。デフォルトは、http。 host | アップストリームサーバーのホスト。ホスト値では大文字と小文字が区別されることにご注意ください。 port | アップストリームサーバポート。デフォルト：80 path
任意 | アップストリームサーバーへのリクエストに使用されるパス。 connect_timeout
任意 | アップストリームサーバーとの接続を確立するためのタイムアウト (ミリ秒単位)。デフォルト: 60000。write_timeout
任意 | アップストリームサーバーにリクエストを送信するための、2つの連続した書き込み操作の間のタイムアウト（ミリ秒）。デフォルト: 60000。read_timeout
任意｜アップストリームサーバーにリクエストを送信し、返ってくるまでの待機時間（ミリ秒単位）。デフォルト: 60000。tags
任意｜グループ化とフィルタリングのためにサービスに関連付けられた文字列の任意セットです。 client_certificate
任意 | アップストリームサーバーとの TLS ハンドシェイク時にクライアント証明書として使用する証明書。form-encodedでは、client_certificate.id=。JSONでは、'"client_certificate":{"id":""}を使用します。 tls_verify
*任意* | アップストリームサーバーのTLS証明書の検証を有効にするかどうか。nullに設定すると、Nginxのデフォルトが遵守されます。 tls_verify_depth
*任意* | アップストリームサーバーのTLS証明書を確認する際のチェーンの最大深度。nullに設定すると、Nginx のデフォルトが尊重されます。デフォルト: null。 ca_certificates
*任意* | アップストリームサーバーのTLS証明書を検証しながらトラストストアを構築するために使用されるCA 証明書オブジェクト UUID の配列。Nginxのデフォルトが尊重されるときに「null」に設定するとします。NginxのデフォルトのCAリストが指定されておらず、TLS検証が有効になっている場合、アップストリームサーバーとのハンドシェイクは常に失敗します (信頼できるCAがないため)。 form-encodedでは、表記はca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515です。JSONでは、配列を使用します。 enabled | サービスがアクティブかどうか。falseに設定すると、プロキシは、アタッチされたルートが存在しないかのように動作します (404)。デフォルト: true。 url
*短縮形属性* | protocol、host、port、pathを一度に設定するための短縮形属性。この属性は書き込み専用です(Admin APIはURLを返しません)。

リクエストされたリソースの下に、本文で指定された定義のサービスを挿入（または置換）します。サービスは、name or id属性によって識別されます。

name or id 属性が UUID の構造を持つ場合、挿入/置換されるサービスは、その id によって識別されます。それ以外の場合は、その name で識別されます。

idをURL内およびボディ内のどちらにも指定せずに新しいサービスを作成する場合、自動生成されます。

URLに name を指定して、リクエストボディに異なるものを指定することはできないことに注意してください

レスポンス

HTTP 200 OK

POST応答とPATCH応答を参照してください。

サービスの削除

注 : このAPIはDBレスモードでは利用できません。

サービスの削除

属性 | 説明 ——————————-:| ——————————- service name or id
必須 | 削除するサービスの一意の識別子 または 名前。

特定の証明書に関連付けられたサービスの削除

属性 | 説明 ——————————-:| ——————————- certificate id
必須 | 削除する証明書の一意の識別子。 service name or id
必須 |削除するサービスの一意の識別子 または 名前。

レスポンス

HTTP 204 No Content

ルートオブジェクト

ルートエンティティは、クライアントリクエストに一致するルールを定義します。各ルートはサービスに関連付けられており、1つのサービスには複数のルートが関連付けられている場合があります。特定のルートに一致するすべてのリクエストは、関連するサービスにプロキシされます。

ルートとサービスの組み合わせ（およびそれらの間の関係の分離）により、強力なルーティングメカニズムが確立されます。このメカニズムを使用すると、インフラストラクチャのさまざまなアップストリームサービスにつながるきめ細かいエントリポイントをKongで定義できます。

Route によって照合されるプロトコルに適用される照合ルールが少なくとも 1 つ必要です。ルートと一致するように構成されたプロトコル（protocols フィールドで定義）に応じて、次のアトリビュートのうち少なくとも1つを設定する必要があります。

• http の場合、少なくとも methods、hosts、headers または paths のいずれか 1 つ。
• https の場合、methods、hosts、headers、paths、または snis のいずれか 1 つ以上。
• tcpの場合、少なくともsourcesまたはdestinationsのいずれか1つ。
• tls の場合、少なくとも sources、destinations、または snis のいずれか 1 つ。
• tls_passthrough の場合は snis を設定します。
• grpc の場合、少なくとも hosts、headers、または paths のいずれか 1 つ。
• grpcs の場合、少なくとも hosts、headers、paths または snis のいずれか 1 つ。
• wsの場合、少なくともhosts 、 headers 、またはpathsのいずれか 1 つ。
• wssの場合、少なくともhosts、headers、paths、またはsnisのいずれか1つ。

ルートがtlsプロトコルとtls_passthroughプロトコルの両方を同時に持つことはできません。

3.0.x リリースでは、新しいルーター実装である atc-routerが導入されました。 ルーターは以下を追加します:

• Kongの構成変更時のルーター再構築時間の短縮
• リクエストをルーティングする際のランタイムパフォーマンスの向上
• 10,000ルートでP99レイテンシを1.5秒から0.1秒に短縮

ルーターの詳細については、以下を確認してください。

式を使用してルートを構成する 式言語リファレンス

パス処理アルゴリズム

注 : パス処理アルゴリズム v1 は Kong 3.0 で非推奨になりました。Kong3.0 以降、router_flavor が expressions に設定されると、route.path_handling は設定できず、パス処理の動作は "v0" になります。router_flavor が traditional_compatible に設定されると、パス処理の 動作は route.path_handling の値に関係なく "v0" になります。router_flavor = traditional のみ、 path_handling "v1' の動作をサポートします。

"v0"はKong 0.x、2.x、3.xで使われている動作です。service.path 、 route.path 、リクエストパスを次のように扱います。 URL の セグメント 。 常にスラッシュでそれらを結合します。 サービスパス /s、ルートパス /r が与えられました とリクエストパス /re、連結されたパスは /s/re になります。 結果のパスが単一のスラッシュの場合、 それ以上の変換は行われません。 それより長い場合は、末尾のスラッシュは削除されます。

"v1" は、Kong 1.x で使用される動作です。service.path は プレフィックス として扱われ、リクエストパスとルートパスの頭のスラッシュは無視されます。サービスパスが /s、ルートパスが /r、リクエストパスが /re である場合、連結されたパスは /sre となります。

どちらのバージョンのアルゴリズムも、パスを組み合わせるときに「二重スラッシュ」を検出し、それらをシングルスラッシュに置き換えます。

次の表は、パス処理バージョン、ストリップパス、およびリクエストの可能な組み合わせを示しています。

ルートはタグ付けすることも、タグでフィルタリングすることもできます。

{
    "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "path_handling": "v0",
    "preserve_host": false,
    "request_buffering": true,
    "response_buffering": true,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}

ルートの追加

注 : このAPIはDBレスモードでは利用できません。

ルートの作成

特定のサービスに関連付けられたルートの作成

属性 | 説明 ——————————-:| ——————————- service name or id
必須 | 新しく作成されたルートに関連付けるサービスの一意の識別子またはname属性。

リクエストボディ

属性名｜説明 —:| — name
ルート名。ルート名は一意である必要があり、大文字と小文字が区別されます。 たとえば、「test」と「Test」という名前の 2 つの異なるルートが存在する場合があります。 protocols | このルートが許可するプロトコルの配列受け入れられるプロトコルのリストについては、ルートオブジェクト セクションをご確認ください。httpsのみに設定すると、HTTP リクエストはアップグレードエラーで応答されます。http のみに設定されている場合、HTTP リクエストと HTTPS リクエストの両方が許可されるという点で、これは基本的に ["http", "https"] と同じです。デフォルト: [http、https] methods
セミオプション｜このRouteにマッチするHTTPメソッドのリスト。 hosts
セミオプション｜このRouteにマッチするドメイン名のリスト。ホストの値は大文字と小文字が区別されることにご注意ください。フォームエンコードの場合、表記は hosts[]=example.com&hosts[]=foo.test になります。JSON では、配列を使用します。paths
セミオプション｜このルートにマッチするパスのリスト。form-encodedの場合、paths[]=/foo&paths[]=/barとなります。JSONでは、配列を使用します。パスは正規表現またはプレーンテキストパターンにすることができます。 パスパターンは正規化されたパスと照合され、ほとんどのパーセントエンコードされた文字がデコード、パスフォールディングされ、セマンティクスが保持されます。詳細については、rfc3986をご参照ください。 headers
セミオプション* | リクエストにこのルートが存在する場合に一致させる、ヘッダー名で索引付けされた1つ以上の値のリスト。Hostヘッダーはこの属性では使用できません。ホストはhosts属性を使用して指定する必要があります。headersに値が 1 つだけ含まれており、その値が特殊なプレフィックス~で始まる場合、その値は正規表現として解釈されます。 https_redirect_status_code | プロトコルを除くルートのすべてのプロパティが一致する場合、つまり、リクエストのプロトコルが HTTPS ではなく HTTP である場合に Kong が応答するステータスコード。フィールドが 301、302、307、または 308 に設定されている場合、Kong によってLocationヘッダーが挿入されます。注: この設定は、ルートがHTTPSプロトコルのみを受け入れるように設定されている場合にのみ適用されます。 受け入れられる値は、426、301、302、307、308 です。デフォルト: 426。regex_priority
任意* | いくつかのルートが同時に正規表現を使ってマッチするとき、与えられたリクエストを解決するルートを選択するために使われる数値です。 2 つのルートがパスに一致し、同じregex_priorityを持つ場合、古い方 (created_atが最も低い) が使用されます。非正規表現ルートの優先順位は異なることにご注意ください（長い非正規表現のルートは短いルートよりも優先されます）。デフォルト: 0strip_path | paths のいずれかを介してルートを照合する場合、アップストリームリクエスト URL から一致するプレフィックスを削除します。デフォルト: true。path_handling
任意｜リクエストをアップストリームに送信するときに、サービスパス、ルートパス、リクエストパスをどのように組み合わせるかを制御します。それぞれの動作の詳細については、上記をご覧ください。 指定できる値は" v0 "、" v1 " です。デフォルト: "v0"。 preserve_host | hostsドメイン名の1つを介してルートを照合する場合は、アップストリームのリクエストヘッダーのHostリクエストヘッダーを使用してください。falseに設定すると、アップストリームのHostヘッダーはサービスのhostのヘッダーになります。request_buffering | リクエストボディのバッファリングを有効にするかどうか。HTTP 1.1では、チャンク転送エンコーディングでデータを受信するサービスではこれをオフにするのが理にかなっているかもしれません。 デフォルト: true。response_buffering | レスポンス本文のバッファリングを有効にするかどうか。HTTP 1.1では、チャンク転送エンコーディングでデータを送信するサービスではこれをオフにするのが理にかなっているかもしれません。 デフォルト: true。snis
セミオプション｜ストリームルーティングを使用するときに、このルートにマッチするSNIのリスト。 sources
セミオプション｜ストリームルーティングを使用しているときに、この Route にマッチする着信接続の IP ソースのリスト。各エントリは、「ip」（任意で CIDR 範囲表記）および/または「port」フィールドを持つオブジェクトです。 destinations
セミオプション｜ストリームルーティングを使用しているときに、この Route にマッチする着信接続の IP 宛先のリスト。各エントリは、「ip」（任意で CIDR 範囲表記）および/または「port」フィールドを持つオブジェクトです。 タグ
任意｜グループ化とフィルタリングのために Route に関連付けられた文字列の任意セット。 service
任意 | このルートが関連付けられるサービス。 ルートがトラフィックをプロキシする場所です。form-encodedでは、service.id=またはservice.name=です。JSONでは、"service":{"id":""}または"service":{"name":""}を使用します。

レスポンス

HTTP 201 Created

{
    "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "path_handling": "v0",
    "preserve_host": false,
    "request_buffering": true,
    "response_buffering": true,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}

ルートの一覧化

すべてのルートの一覧表示

特定のサービスに関連付けられたルートの一覧表示

属性 | 説明 ——————————-:| ——————————- service name or id
必須 | ルートを取得するサービスの一意の識別子またはname属性。このエンドポイントを使用すると、指定されたサービスに関連付けられたルートのみが一覧表示されます。

レスポンス

HTTP 200 OK

{

"data": [{
    "id": "a9daa3ba-8186-4a0d-96e8-00d80ce7240b",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "path_handling": "v0",
    "preserve_host": false,
    "request_buffering": true,
    "response_buffering": true,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"127dfc88-ed57-45bf-b77a-a9d3a152ad31"}
}, {
    "id": "9aa116fd-ef4a-4efa-89bf-a0b17c4be982",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["tcp", "tls"],
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "path_handling": "v0",
    "preserve_host": false,
    "request_buffering": true,
    "response_buffering": true,
    "snis": ["foo.test", ["example.com"],
    "sources": [{"ip":"10.1.0.0/16", "port":1234}, {"ip":"10.2.2.2"}, {"port":9123}],
    "destinations": [{"ip":"10.1.0.0/16", "port":1234}, {"ip":"10.2.2.2"}, {"port":9123}],
    "tags": ["admin", "high-priority", "critical"],
    "service": {"id":"ba641b07-e74a-430a-ab46-94b61e5ea66b"}
}],

    "next": "http://localhost:8001/routes?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

ルートの取得

ルートの取得

属性 | 説明 ——————————-:| ——————————- route name or id
必須 | 取得するルートの一意の識別子 または 名前。

特定のサービスに関連付けられたルートを取得

属性 | 説明 ——————————-:| ——————————- service name or id
必須 | 取得するサービスの一意の識別子 または 名前。route name or id
必須 | 取得するルートの一意の識別子 または 名前。

特定のプラグインに関連付けられたルートの取得

属性 | 説明 ---: |--- plugin id
必須 | 取得するルートに関連付けられたプラグインの一意の識別子。

レスポンス

HTTP 200 OK

{
    "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "path_handling": "v0",
    "preserve_host": false,
    "request_buffering": true,
    "response_buffering": true,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}

ルートの更新

注 : このAPIはDBレスモードでは利用できません。

ルートの更新

属性 | 説明 |—| —- | route name or id
必須 | 更新するルートの一意の識別子 または 名前。

特定のサービスに関連付けられたルートの更新

属性 | 説明 |—| —- | service name or id
必須 | 更新するサービスの一意の識別子 または 名前。 route name or id
必須 | 更新するルート一意の識別子 または 名前。

特定のプラグインに関連付けられたルートの更新

属性 | 説明 |—| —- | plugin id
必須 | 更新するルートに関連付けられたプラグインの一意の識別子。

リクエストボディ

属性名｜説明 —:| — name
ルート名。ルート名は一意である必要があり、大文字と小文字が区別されます。 たとえば、「test」と「Test」という名前の 2 つの異なるルートが存在する場合があります。 protocols | このルートが許可するプロトコルの配列受け入れられるプロトコルのリストについては、ルートオブジェクト セクションをご確認ください。httpsのみに設定すると、HTTP リクエストはアップグレードエラーで応答されます。http のみに設定されている場合、HTTP リクエストと HTTPS リクエストの両方が許可されるという点で、これは基本的に ["http", "https"] と同じです。デフォルト: [http、https] methods
セミオプション｜このRouteにマッチするHTTPメソッドのリスト。 hosts
セミオプション｜このRouteにマッチするドメイン名のリスト。ホストの値は大文字と小文字が区別されることにご注意ください。フォームエンコードの場合、表記は hosts[]=example.com&hosts[]=foo.test になります。JSON では、配列を使用します。paths
セミオプション｜このルートにマッチするパスのリスト。form-encodedの場合、paths[]=/foo&paths[]=/barとなります。JSONでは、配列を使用します。パスは正規表現またはプレーンテキストパターンにすることができます。 パスパターンは正規化されたパスと照合され、ほとんどのパーセントエンコードされた文字がデコード、パスフォールディングされ、セマンティクスが保持されます。詳細については、rfc3986をご参照ください。 headers
セミオプション* | リクエストにこのルートが存在する場合に一致させる、ヘッダー名で索引付けされた1つ以上の値のリスト。Hostヘッダーはこの属性では使用できません。ホストはhosts属性を使用して指定する必要があります。headersに値が 1 つだけ含まれており、その値が特殊なプレフィックス~で始まる場合、その値は正規表現として解釈されます。 https_redirect_status_code | プロトコルを除くルートのすべてのプロパティが一致する場合、つまり、リクエストのプロトコルが HTTPS ではなく HTTP である場合に Kong が応答するステータスコード。フィールドが 301、302、307、または 308 に設定されている場合、Kong によってLocationヘッダーが挿入されます。注: この設定は、ルートがHTTPSプロトコルのみを受け入れるように設定されている場合にのみ適用されます。 受け入れられる値は、426、301、302、307、308 です。デフォルト: 426。regex_priority
任意* | いくつかのルートが同時に正規表現を使ってマッチするとき、与えられたリクエストを解決するルートを選択するために使われる数値です。 2 つのルートがパスに一致し、同じregex_priorityを持つ場合、古い方 (created_atが最も低い) が使用されます。非正規表現ルートの優先順位は異なることにご注意ください（長い非正規表現のルートは短いルートよりも優先されます）。デフォルト: 0strip_path | paths のいずれかを介してルートを照合する場合、アップストリームリクエスト URL から一致するプレフィックスを削除します。デフォルト: true。path_handling
任意｜リクエストをアップストリームに送信するときに、サービスパス、ルートパス、リクエストパスをどのように組み合わせるかを制御します。それぞれの動作の詳細については、上記をご覧ください。 指定できる値は" v0 "、" v1 " です。デフォルト: "v0"。 preserve_host | hostsドメイン名の1つを介してルートを照合する場合は、アップストリームのリクエストヘッダーのHostリクエストヘッダーを使用してください。falseに設定すると、アップストリームのHostヘッダーはサービスのhostのヘッダーになります。request_buffering | リクエストボディのバッファリングを有効にするかどうか。HTTP 1.1では、チャンク転送エンコーディングでデータを受信するサービスではこれをオフにするのが理にかなっているかもしれません。 デフォルト: true。response_buffering | レスポンス本文のバッファリングを有効にするかどうか。HTTP 1.1では、チャンク転送エンコーディングでデータを送信するサービスではこれをオフにするのが理にかなっているかもしれません。 デフォルト: true。snis
セミオプション｜ストリームルーティングを使用するときに、このルートにマッチするSNIのリスト。 sources
セミオプション｜ストリームルーティングを使用しているときに、この Route にマッチする着信接続の IP ソースのリスト。各エントリは、「ip」（任意で CIDR 範囲表記）および/または「port」フィールドを持つオブジェクトです。 destinations
セミオプション｜ストリームルーティングを使用しているときに、この Route にマッチする着信接続の IP 宛先のリスト。各エントリは、「ip」（任意で CIDR 範囲表記）および/または「port」フィールドを持つオブジェクトです。 タグ
任意｜グループ化とフィルタリングのために Route に関連付けられた文字列の任意セット。 service
任意 | このルートが関連付けられるサービス。 ルートがトラフィックをプロキシする場所です。form-encodedでは、service.id=またはservice.name=です。JSONでは、"service":{"id":""}または"service":{"name":""}を使用します。

レスポンス

HTTP 200 OK

{
    "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "path_handling": "v0",
    "preserve_host": false,
    "request_buffering": true,
    "response_buffering": true,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}

ルートの更新または作成

注 : このAPIはDBレスモードでは利用できません。

ルートの作成または更新

属性 | 説明 |—| —- | route name or id
必須 | 作成または更新するルートの一意の識別子 または 名前。

特定のサービスに関連付けられたルートを作成または更新

属性 | 説明 |—| —- | service name or id
必須 | 作成または更新するサービスの一意の識別子 または 名前。 route name or id
必須 | 作成または更新するルートの一意の識別子 または 名前。

特定のプラグインに関連付けられたルートの作成または更新

属性 | 説明 |—| —- | plugin id
必須 | 作成または更新するルートに関連付けられたプラグインの一意の識別子。

リクエストボディ

属性名｜説明 —:| — name
ルート名。ルート名は一意である必要があり、大文字と小文字が区別されます。 たとえば、「test」と「Test」という名前の 2 つの異なるルートが存在する場合があります。 protocols | このルートが許可するプロトコルの配列受け入れられるプロトコルのリストについては、ルートオブジェクト セクションをご確認ください。httpsのみに設定すると、HTTP リクエストはアップグレードエラーで応答されます。http のみに設定されている場合、HTTP リクエストと HTTPS リクエストの両方が許可されるという点で、これは基本的に ["http", "https"] と同じです。デフォルト: [http、https] methods
セミオプション｜このRouteにマッチするHTTPメソッドのリスト。 hosts
セミオプション｜このRouteにマッチするドメイン名のリスト。ホストの値は大文字と小文字が区別されることにご注意ください。フォームエンコードの場合、表記は hosts[]=example.com&hosts[]=foo.test になります。JSON では、配列を使用します。paths
セミオプション｜このルートにマッチするパスのリスト。form-encodedの場合、paths[]=/foo&paths[]=/barとなります。JSONでは、配列を使用します。パスは正規表現またはプレーンテキストパターンにすることができます。 パスパターンは正規化されたパスと照合され、ほとんどのパーセントエンコードされた文字がデコード、パスフォールディングされ、セマンティクスが保持されます。詳細については、rfc3986をご参照ください。 headers
セミオプション* | リクエストにこのルートが存在する場合に一致させる、ヘッダー名で索引付けされた1つ以上の値のリスト。Hostヘッダーはこの属性では使用できません。ホストはhosts属性を使用して指定する必要があります。headersに値が 1 つだけ含まれており、その値が特殊なプレフィックス~で始まる場合、その値は正規表現として解釈されます。 https_redirect_status_code | プロトコルを除くルートのすべてのプロパティが一致する場合、つまり、リクエストのプロトコルが HTTPS ではなく HTTP である場合に Kong が応答するステータスコード。フィールドが 301、302、307、または 308 に設定されている場合、Kong によってLocationヘッダーが挿入されます。注: この設定は、ルートがHTTPSプロトコルのみを受け入れるように設定されている場合にのみ適用されます。 受け入れられる値は、426、301、302、307、308 です。デフォルト: 426。regex_priority
任意* | いくつかのルートが同時に正規表現を使ってマッチするとき、与えられたリクエストを解決するルートを選択するために使われる数値です。 2 つのルートがパスに一致し、同じregex_priorityを持つ場合、古い方 (created_atが最も低い) が使用されます。非正規表現ルートの優先順位は異なることにご注意ください（長い非正規表現のルートは短いルートよりも優先されます）。デフォルト: 0strip_path | paths のいずれかを介してルートを照合する場合、アップストリームリクエスト URL から一致するプレフィックスを削除します。デフォルト: true。path_handling
任意｜リクエストをアップストリームに送信するときに、サービスパス、ルートパス、リクエストパスをどのように組み合わせるかを制御します。それぞれの動作の詳細については、上記をご覧ください。 指定できる値は" v0 "、" v1 " です。デフォルト: "v0"。 preserve_host | hostsドメイン名の1つを介してルートを照合する場合は、アップストリームのリクエストヘッダーのHostリクエストヘッダーを使用してください。falseに設定すると、アップストリームのHostヘッダーはサービスのhostのヘッダーになります。request_buffering | リクエストボディのバッファリングを有効にするかどうか。HTTP 1.1では、チャンク転送エンコーディングでデータを受信するサービスではこれをオフにするのが理にかなっているかもしれません。 デフォルト: true。response_buffering | レスポンス本文のバッファリングを有効にするかどうか。HTTP 1.1では、チャンク転送エンコーディングでデータを送信するサービスではこれをオフにするのが理にかなっているかもしれません。 デフォルト: true。snis
セミオプション｜ストリームルーティングを使用するときに、このルートにマッチするSNIのリスト。 sources
セミオプション｜ストリームルーティングを使用しているときに、この Route にマッチする着信接続の IP ソースのリスト。各エントリは、「ip」（任意で CIDR 範囲表記）および/または「port」フィールドを持つオブジェクトです。 destinations
セミオプション｜ストリームルーティングを使用しているときに、この Route にマッチする着信接続の IP 宛先のリスト。各エントリは、「ip」（任意で CIDR 範囲表記）および/または「port」フィールドを持つオブジェクトです。 タグ
任意｜グループ化とフィルタリングのために Route に関連付けられた文字列の任意セット。 service
任意 | このルートが関連付けられるサービス。 ルートがトラフィックをプロキシする場所です。form-encodedでは、service.id=またはservice.name=です。JSONでは、"service":{"id":""}または"service":{"name":""}を使用します。

リクエストされたリソースの下に、本文で指定された定義のルートを 挿入（または置換）します。ルートは name or id 属性によって識別されます。

name or id 属性が UUID の構造を持つ場合、挿入または置換されるルートは、その id によって識別されます。それ以外の場合は、その name で識別されます。

idを指定せずに（URLでも本文でも）新しいルートを作成すると、自動生成されます。

URLに name を指定して、リクエストボディに異なるものを指定することはできないことに注意してください

レスポンス

HTTP 200 OK

POST応答とPATCH応答を参照してください。

ルートの削除

注 : このAPIはDBレスモードでは利用できません。

ルートの削除

属性 | 説明 ——————————-:| ——————————- route name or id
必須 | 削除するルートの一意の識別子 または 名前。

特定のサービスに関連付けられたルートの削除

属性 | 説明 |—| —- | service name or id
必須 | 削除するサービスの一意の識別子 または 名前。route name or id
必須 | 削除するルートの一意の識別子 または 名前。

レスポンス

HTTP 204 No Content

コンシューマオブジェクト

コンシューマオブジェクトは、サービスのコンシューマ、つまりユーザーを表します。Kongをプライマリデータストアとして利用するか、コンシューマリストをデータベースとマッピングして、Kongと既存のプライマリデータストア間の一貫性を保つことができます。

コンシューマは、タグ付けすることも、タグでフィルタリングすることもできます。

{
    "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}

コンシューマを追加

注 : このAPIはDBレスモードでは利用できません。

コンシューマの作成

リクエストボディ

属性名 | 説明 —: |— username
セミオプション | コンシューマ固有のユーザー名。このフィールドまたはcustom_idのいずれかをリクエストとともに送信する必要があります。 custom_id
セミオプション｜コンシューマの既存の一意なIDを格納するフィールド - 既存のデータベースのユーザーとKongをマッピングする上で便利です。このフィールドまたはusernameのいずれかをリクエストとともに送信する必要があります。 tags
任意｜グループ化とフィルタリングのためにコンシューマに関連付けられた文字列の任意セット。

レスポンス

HTTP 201 Created

{
    "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}

コンシューマの一覧表示

すべてのコンシューマの一覧表示

レスポンス

HTTP 200 OK

{

"data": [{
    "id": "a4407883-c166-43fd-80ca-3ca035b0cdb7",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}, {
    "id": "01c23299-839c-49a5-a6d5-8864c09184af",
    "created_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["admin", "high-priority", "critical"]
}],

    "next": "http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

コンシューマの取得

コンシューマの取得

属性 | 説明 |—| —- | consumer username or id
必須 | 取得するコンシューマの一意の識別子 または ユーザー名。

特定のプラグインに関連付けられたコンシューマを取得

属性 | 説明 ---: |--- plugin id
必須 | 取得するコンシューマに関連付けられているプラグインの一意の識別子。

レスポンス

HTTP 200 OK

{
    "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}

コンシューマの更新

注 : このAPIはDBレスモードでは利用できません。

コンシューマの更新

属性 | 説明 |—| —- | consumer username or id
必須 | 更新するコンシューマの一意の識別子 または ユーザー名。

特定のプラグインに関連付けられたコンシューマを更新する

属性 | 説明 |—| —- | plugin id
必須 | 更新するコンシューマに関連付けられたプラグインの一意の識別子。

リクエストボディ

属性名 | 説明 —: |— username
セミオプション | コンシューマ固有のユーザー名。このフィールドまたはcustom_idのいずれかをリクエストとともに送信する必要があります。 custom_id
セミオプション｜コンシューマの既存の一意なIDを格納するフィールド - 既存のデータベースのユーザーとKongをマッピングする上で便利です。このフィールドまたはusernameのいずれかをリクエストとともに送信する必要があります。 tags
任意｜グループ化とフィルタリングのためにコンシューマに関連付けられた文字列の任意セット。

レスポンス

HTTP 200 OK

{
    "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}

コンシューマの更新または作成

注 : このAPIはDBレスモードでは利用できません。

コンシューマの作成または更新

属性 | 説明 |—| —- | consumer username or id
必須 | 作成または更新するコンシューマの一意の識別子 または ユーザー名。

特定のプラグインに関連付けられたコンシューマの作成または更新

属性 | 説明 |—| —- | plugin id
必須 | 作成または更新するコンシューマに関連付けられたプラグインの一意の識別子。

リクエストボディ

属性名 | 説明 —: |— username
セミオプション | コンシューマ固有のユーザー名。このフィールドまたはcustom_idのいずれかをリクエストとともに送信する必要があります。 custom_id
セミオプション｜コンシューマの既存の一意なIDを格納するフィールド - 既存のデータベースのユーザーとKongをマッピングする上で便利です。このフィールドまたはusernameのいずれかをリクエストとともに送信する必要があります。 tags
任意｜グループ化とフィルタリングのためにコンシューマに関連付けられた文字列の任意セット。

要求されたリソースの下のコンシューマを、本文で指定された定義に挿入（または置換）します。コンシューマはusername or id属性で識別されます。

username or id 属性が UUID の構造を持つ場合、挿入/置換されるコンシューマは、その id によって識別されます。それ以外の場合は、その username で識別されます。

idを指定せずに（URLでも本文でも）新しいコンシューマを作成すると、自動生成されます。

URLに username を指定して、リクエストボディに異なるものを指定することはできないことに注意してください

レスポンス

HTTP 200 OK

POST応答とPATCH応答を参照してください。

コンシューマの削除

注 : このAPIはDBレスモードでは利用できません。

コンシューマの削除

属性 | 説明 |—| —- | consumer username or id
必須 | 削除するコンシューマの一意の識別子 または ユーザー名。

レスポンス

HTTP 204 No Content

プラグインオブジェクト

プラグインエンティティは、HTTP リクエスト/レスポンスのライフサイクル中に実行されるプラグイン構成を表します。これは、認証や Rate Limiting など、Kong の背後で実行されるサービスに機能を追加する方法です。インストール方法と各プラグインが受け取る値の詳細については、Kong Hub を参照してください。

プラグイン構成をサービスに追加すると、サービスに対してクライアントがリクエストをするごとに、そのプラグインが実行されます。特定のコンシューマに対してプラグインを異なる値に調整する必要がある場合、service と consumer のフィールドでサービスとコンシューマの両方を指定した別のプラグインインスタンスを作成することによって、それが可能となります。

プラグインはタグ付けすることも、タグでフィルタリングすることもできます。

{
    "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "instance_name": rate-limiting-foo,
    "config": {"hour":500, "minute":20},
    "protocols": ["http", "https"],
    "enabled": true,
    "tags": ["user-level", "low-priority"],
    "ordering": {"before":["plugin-name"]}
}

詳細については、以下の優先順位セクションを参照してください。

優先順位

プラグインは常に1回だけ、リクエストごとに1回だけ実行されます。ただし、 実行される際の構成は、プラグインが構成されているエンティティによって 異なります。

プラグインは、さまざまなエンティティ、エンティティの組み合わせ、またはグローバルにも構成できます。これは、たとえばほとんどのリクエストに対しては特定の方法でプラグインを設定したいけれど、 認証されたリクエスト に対しては多少異なる動作にしたい場合に役立ちます。

したがって、プラグインが異なる構成の異なるエンティティに適用された場合は、プラグインを実行する優先順位があります。特定のプラグインに構成されたエンティティの数は、そのプラグインの優先度に直接相関します。プラグインに構成されたエンティティの数が多いほど、優先順位が高くなります。複数のエンティティに構成されたプラグインの完全な優先順位は以下のとおりです。

1. コンシューマ、ルート、サービスの組み合わせで構成されたプラグイン。 （コンシューマは、リクエストが認証される必要があることを意味します）。
2. ConsumerGroup、サービス、およびルートの組み合わせで構成されたプラグイン。 (ConsumerGroup は、リクエストが認証される必要があることを意味します)。
3. コンシューマとルートの組み合わせで構成されたプラグイン。 （コンシューマは、リクエストが認証される必要があることを意味します）。
4. コンシューマとサービスの組み合わせで構成されたプラグイン。
5. コンシューマグループとルートで構成されたプラグイン。
6. コンシューマグループとサービスで構成されたプラグイン。
7. ルートとサービスに設定されたプラグイン。
8. コンシューマ上に構成されるプラグイン。
9. ConsumerGroupに構成されたプラグイン。
10. ルートに設定されたプラグイン。
11. サービス上に構成されるプラグイン。
12. グローバルに構成されたプラグイン。

例 : rate-limiting プラグインが、サービス（プラグイン構成A）、およびコンシューマ（プラグイン構成B）に対して（異なる構成で）2回適用された場合、このコンシューマを認証するリクエストは、プラグイン構成Bを実行しAを無視します。ただし、このコンシューマを認証しないリクエストは、プラグイン構成Aを実行するようフォールバックします。構成Bが無効になっている場合（その enabled フラグが false に設定されている場合）、構成Aは構成Bに一致するリクエストに適用されることに注意してください。

プラグインを追加

注 : このAPIはDBレスモードでは利用できません。

プラグインの作成

特定のルートに関連付けられたプラグインを作成

属性 | 説明 |—| —- | route name or id
必須 | 新しく作成されたプラグインに関連付けるルートの一意の識別子またはname属性。

特定のサービスに関連付けられたプラグインの作成

属性 | 説明 |—| —- | service name or id
必須 | 新しく作成されたプラグインに関連付けるサービスの一意の識別子またはname属性。

特定のコンシューマに関連付けられたプラグインの作成

属性 | 説明 |—| —- | consumer name or id
必須 | 新しく作成されたプラグインに関連付けるコンシューマの一意の識別子またはname属性。

リクエストボディ

レスポンス

HTTP 201 Created

{
    "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "instance_name": rate-limiting-foo,
    "config": {"hour":500, "minute":20},
    "protocols": ["http", "https"],
    "enabled": true,
    "tags": ["user-level", "low-priority"],
    "ordering": {"before":["plugin-name"]}
}

プラグインの一覧表示

すべてのプラグインの一覧

特定のルートに関連付けられたプラグインの一覧表示

属性 | 説明 |—| —- | route name or id
必須 | プラグインを取得するルートの一意の識別子またはname属性。このエンドポイントを使用すると、指定されたルートに関連付けられたプラグインのみが一覧表示されます。

特定のサービスに関連付けられたプラグインの一覧化

属性 | 説明 |—| —- | service name or id
必須 | プラグインを取得するサービスの一意の識別子またはname属性。このエンドポイントを使用すると、指定されたサービスに関連付けられたプラグインのみが一覧表示されます。

特定のコンシューマに関連付けられたプラグインの一覧化

属性 | 説明 |—| —- | consumer name or id
必須 | プラグインを取得するコンシューマの一意の識別子または name 属性。このエンドポイントを使用すると、指定されたコンシューマに関連付けられたプラグインのみが一覧化されます。

レスポンス

HTTP 200 OK

{

"data": [{
    "id": "02621eee-8309-4bf6-b36b-a82017a5393e",
    "name": "rate-limiting",
    "instance_name": "rate-limiting-foo",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "config": {"hour":500, "minute":20},
    "protocols": ["http", "https"],
    "enabled": true,
    "tags": ["user-level", "low-priority"],
    "ordering": {"before":["plugin-name"]}
}, {
    "id": "66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "config": {"hour":500, "minute":20},
    "protocols": ["tcp", "tls"],
    "enabled": true,
    "tags": ["admin", "high-priority", "critical"],
    "ordering": {"after":["plugin-name"]}
}],

    "next": "http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

プラグインの取得

プラグインの取得

属性 | 説明 |—| —- | plugin id
必須 | 取得するプラグインの一意の識別子。

特定のルートに関連付けられたプラグインの取得

属性 | 説明 |—| —- | route name or id
必須 | 取得するルートの一意の識別子 または 名前。plugin id
必須 | 取得するプラグインの一意の識別子。

特定のサービスに関連付けられたプラグインを取得

属性 | 説明 |—| —- | service name or id
必須 | 取得するサービスの一意の識別子 または 名前。 plugin id
必須 | 取得するプラグインの一意の識別子。

特定のコンシューマに関連付けられたプラグインの取得

属性 | 説明 |—| —- | consumer username or id
必須 | 取得するコンシューマの一意の識別子 または ユーザー名。 plugin id
必須 | 取得するプラグインの一意の識別子。

レスポンス

HTTP 200 OK

{
    "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "instance_name": rate-limiting-foo,
    "config": {"hour":500, "minute":20},
    "protocols": ["http", "https"],
    "enabled": true,
    "tags": ["user-level", "low-priority"],
    "ordering": {"before":["plugin-name"]}
}

プラグインの更新

注 : このAPIはDBレスモードでは利用できません。

プラグインの更新

属性 | 説明 |—| —- | plugin id
必須 | 更新するプラグインの一意の識別子。

特定のプラグインに関連付けられたサービスを更新

属性 | 説明 |—| —- | route name or id
必須 | 更新するルートの一意の識別子 または 名前。plugin id
必須 | 更新するプラグインの一意の識別子。

特定のサービスに関連付けられたプラグインの更新

属性 | 説明 |—| —- | service name or id
必須 | 更新するサービスの一意の識別子 または 名前。 plugin id
必須 | 更新するプラグインの一意の識別子。

特定のコンシューマに関連付けられたプラグインの更新

属性 | 説明 |—| —- | consumer username or id
必須 | 更新するコンシューマの一意の識別子 または ユーザー名。 plugin id
必須 | 更新するプラグインの一意の識別子。

リクエストボディ

レスポンス

HTTP 200 OK

{
    "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "instance_name": rate-limiting-foo,
    "config": {"hour":500, "minute":20},
    "protocols": ["http", "https"],
    "enabled": true,
    "tags": ["user-level", "low-priority"],
    "ordering": {"before":["plugin-name"]}
}

プラグインを更新または作成

注 : このAPIはDBレスモードでは利用できません。

プラグインの作成または更新

属性 | 説明 |—| —- | plugin id
必須 | 作成または更新するプラグインの一意の識別子。

特定のルートに関連付けられたプラグインを作成または更新

属性 | 説明 |—| —- | route name or id
必須 | 作成または更新するルートの一意の識別子 または 名前。 plugin id
必須 | 作成または更新するプラグインの一意の識別子。

特定のサービスに関連付けられたプラグインの作成または更新

属性 | 説明 |—| —- | service name or id
必須 | 作成または更新するサービスの一意の識別子 または 名前。 plugin id
必須 | 作成または更新するプラグインの一意の識別子。

特定のコンシューマに関連付けられたプラグインの作成または更新

属性 | 説明 |—| —- | consumer username or id
必須 | 作成または更新するコンシューマの一意の識別子 または ユーザー名。 plugin id
必須 | 作成または更新するプラグインの一意の識別子。

リクエストボディ

ボディで指定された定義を使って、指定されたリソースの下にプラグインを挿入（または置換）します。プラグインは name or id 属性によって識別されます。

name or id 属性が UUID の構造を持つ場合、挿入または置換されるプラグインは、その id によって識別されます。それ以外の場合は、その name で識別されます。

idを指定せずに（URLでも本文でも）新しいプラグインを作成すると、自動生成されます。

URLに name を指定して、リクエストボディに異なるものを指定することはできないことに注意してください

レスポンス

HTTP 200 OK

POST応答とPATCH応答を参照してください。

プラグインの削除

注 : このAPIはDBレスモードでは利用できません。

プラグインの削除

属性 | 説明 |—| —- | plugin id
必須 | 削除するプラグインの一意の識別子。

特定のルートに関連付けられたプラグインの削除

属性 | 説明 ——————————-:| ——————————- route name or id
必須 | 削除するルートの一意の識別子 または 名前。plugin id
必須 | 削除するプラグインの一意の識別子。

特定のサービスに関連付けられたプラグインの削除

属性 | 説明 |—| —- | service name or id
必須 | 削除するサービスの一意の識別子 または 名前。 plugin id
必須 | 削除するプラグインの一意の識別子。

特定のコンシューマに関連付けられたプラグインの削除

属性 | 説明 |—| —- | consumer username or id
必須 | 削除するコンシューマの一意の識別子 または ユーザー名。 plugin id
必須 | 削除するプラグインの一意の識別子。

レスポンス

HTTP 204 No Content

有効なプラグインの取得

Kongノードにインストールされたすべてのプラグインのリストを取得します。

レスポンス

HTTP 200 OK

{
    "enabled_plugins": [
        "jwt",
        "acl",
        "cors",
        "oauth2",
        "tcp-log",
        "udp-log",
        "file-log",
        "http-log",
        "key-auth",
        "hmac-auth",
        "basic-auth",
        "ip-restriction",
        "request-transformer",
        "response-transformer",
        "request-size-limiting",
        "rate-limiting",
        "response-ratelimiting",
        "aws-lambda",
        "bot-detection",
        "correlation-id",
        "datadog",
        "galileo",
        "ldap-auth",
        "loggly",
        "statsd",
        "syslog"
    ]
}

証明書オブジェクト

証明書オブジェクトは公開証明書を表し、オプションで対応する秘密鍵と組み合わせることができます 。これらのオブジェクトはKongが暗号化されたリクエストのSSL/TLSの終了を処理するために使用されるか、クライアント/サービスのピア証明書を検証する際の信頼できるCAストアとして使用されます。証明書はオプションでSNIオブジェクトに関連付けて、証明書/キーペアを1つ以上のホスト名に結びつけます。

メインの証明書に加えて中間証明書が必要な場合は、次の順序に従って1つの文字列になるように連結する必要があります。メインの証明書が一番上、その後に中間証明書が続きます。

証明書は、タグ付けすることも、タグでフィルタリングすることもできます。

{
    "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "cert_alt": "-----BEGIN CERTIFICATE-----...",
    "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
    "tags": ["user-level", "low-priority"]
}

証明書の追加

注 : このAPIはDBレスモードでは利用できません。

証明書の作成

リクエストボディ

属性名 | 説明 —:| — cert | SSL キーペアのPEMエンコードされた公開証明書チェーン。 このフィールドは「参照可能」です。つまり、[シークレット] (/gateway/latest/plan-and-deploy/security/secrets-management/getting-started/) としてvaultに安全に保存できます。リファレンスは [特定の形式]（/gateway/latest/plan-and-deploy/security/secrets-management/reference-format/）に従う必要があります。 key | SSL キーペアの PEM エンコードされた秘密鍵。このフィールドは「参照可能」です。つまり、[シークレット] (/gateway/latest/plan-and-deploy/security/secrets-management/getting-started/) としてvaultに安全に保存できます。リファレンスは [特定の形式]（/gateway/latest/plan-and-deploy/security/secrets-management/reference-format/）に従う必要があります。 cert_alt
任意 | 代替 SSL 鍵ペアの PEM エンコードされた公開証明書チェーン。 これは、RSA と ECDSA の両方のタイプの証明書が利用可能であり、クライアントが ECDSA 証明書のサポートをアドバタイズするときに Kong が ECDSA 証明書を使用してサービスを優先する場合にのみ設定する必要があります。このフィールドは「参照可能」です。つまり、[シークレット] (/gateway/latest/plan-and-deploy/security/secrets-management/getting-started/) としてvaultに安全に保存できます。リファレンスは [特定の形式]（/gateway/latest/plan-and-deploy/security/secrets-management/reference-format/）に従う必要があります。 key_alt
任意 | 代替 SSL 鍵ペアの PEM エンコードされた秘密鍵。 これは、RSA と ECDSA の両方のタイプの証明書が利用可能であり、クライアントが ECDSA 証明書のサポートをアドバタイズするときに Kong が ECDSA 証明書を使用してサービスを優先する場合にのみ設定する必要があります。このフィールドは「参照可能」です。つまり、[シークレット] (/gateway/latest/plan-and-deploy/security/secrets-management/getting-started/) としてvaultに安全に保存できます。リファレンスは [特定の形式]（/gateway/latest/plan-and-deploy/security/secrets-management/reference-format/）に従う必要があります。 タグ
任意 | グループ化とフィルタリングのための証明書に関連付けられた文字列の任意セット。 SNI
省略形属性 | SNI としてこの証明書に関連付ける 0 個以上のホスト名の配列。 これは便利なパラメータです。内部的には SNI オブジェクトを作成し、それをこの証明書に関連付けます。 この属性を設定するには、この証明書に有効な秘密キーが関連付けられている必要があります。 passphrase
任意（Enterpriseのみ）｜暗号化された秘密鍵をKongにロードするには、この属性を使ってパスフレーズを指定します。Kongが秘密鍵を復号化し、データベースに保存します。Kong のデータベース内の秘密鍵やその他の機密情報を暗号化するには、DB 暗号化の使用を検討してください。

レスポンス

HTTP 201 Created

{
    "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "cert_alt": "-----BEGIN CERTIFICATE-----...",
    "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
    "tags": ["user-level", "low-priority"]
}

証明書を一覧表示

すべての証明書の一覧表示

レスポンス

HTTP 200 OK

{

"data": [{
    "id": "d044b7d4-3dc2-4bbc-8e9f-6b7a69416df6",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "cert_alt": "-----BEGIN CERTIFICATE-----...",
    "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
    "tags": ["user-level", "low-priority"]
}, {
    "id": "a9b2107f-a214-47b3-add4-46b942187924",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "cert_alt": "-----BEGIN CERTIFICATE-----...",
    "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
    "tags": ["admin", "high-priority", "critical"]
}],

    "next": "http://localhost:8001/certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

証明書の取得

証明書の取得

属性 | 説明 |—| —- | certificate id
必須 | 取得する証明書の一意の識別子。

特定のアップストリームに関連付けられた証明書の取得

属性 | 説明 |—| —- | upstream name or id
必須 | 取得する証明書に関連付けられたアップストリームの一意の識別子 または 名前。

レスポンス

HTTP 200 OK

{
    "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "cert_alt": "-----BEGIN CERTIFICATE-----...",
    "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
    "tags": ["user-level", "low-priority"]
}

証明書を更新

注 : このAPIはDBレスモードでは利用できません。

証明書を更新

属性 | 説明 |—| —- | certificate id
必須 | 更新する証明書の一意の識別子。

特定のアップストリームに関連付けられた証明書の更新

属性 | 説明 |—| —- | upstream name or id
必須 | 更新する証明書に関連付けられたアップストリームの一意の識別子 または 名前。

リクエストボディ

属性名 | 説明 —:| — cert | SSL キーペアのPEMエンコードされた公開証明書チェーン。 このフィールドは「参照可能」です。つまり、[シークレット] (/gateway/latest/plan-and-deploy/security/secrets-management/getting-started/) としてvaultに安全に保存できます。リファレンスは [特定の形式]（/gateway/latest/plan-and-deploy/security/secrets-management/reference-format/）に従う必要があります。 key | SSL キーペアの PEM エンコードされた秘密鍵。このフィールドは「参照可能」です。つまり、[シークレット] (/gateway/latest/plan-and-deploy/security/secrets-management/getting-started/) としてvaultに安全に保存できます。リファレンスは [特定の形式]（/gateway/latest/plan-and-deploy/security/secrets-management/reference-format/）に従う必要があります。 cert_alt
任意 | 代替 SSL 鍵ペアの PEM エンコードされた公開証明書チェーン。 これは、RSA と ECDSA の両方のタイプの証明書が利用可能であり、クライアントが ECDSA 証明書のサポートをアドバタイズするときに Kong が ECDSA 証明書を使用してサービスを優先する場合にのみ設定する必要があります。このフィールドは「参照可能」です。つまり、[シークレット] (/gateway/latest/plan-and-deploy/security/secrets-management/getting-started/) としてvaultに安全に保存できます。リファレンスは [特定の形式]（/gateway/latest/plan-and-deploy/security/secrets-management/reference-format/）に従う必要があります。 key_alt
任意 | 代替 SSL 鍵ペアの PEM エンコードされた秘密鍵。 これは、RSA と ECDSA の両方のタイプの証明書が利用可能であり、クライアントが ECDSA 証明書のサポートをアドバタイズするときに Kong が ECDSA 証明書を使用してサービスを優先する場合にのみ設定する必要があります。このフィールドは「参照可能」です。つまり、[シークレット] (/gateway/latest/plan-and-deploy/security/secrets-management/getting-started/) としてvaultに安全に保存できます。リファレンスは [特定の形式]（/gateway/latest/plan-and-deploy/security/secrets-management/reference-format/）に従う必要があります。 タグ
任意 | グループ化とフィルタリングのための証明書に関連付けられた文字列の任意セット。 SNI
省略形属性 | SNI としてこの証明書に関連付ける 0 個以上のホスト名の配列。 これは便利なパラメータです。内部的には SNI オブジェクトを作成し、それをこの証明書に関連付けます。 この属性を設定するには、この証明書に有効な秘密キーが関連付けられている必要があります。 passphrase
任意（Enterpriseのみ）｜暗号化された秘密鍵をKongにロードするには、この属性を使ってパスフレーズを指定します。Kongが秘密鍵を復号化し、データベースに保存します。Kong のデータベース内の秘密鍵やその他の機密情報を暗号化するには、DB 暗号化の使用を検討してください。

レスポンス

HTTP 200 OK

{
    "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "cert_alt": "-----BEGIN CERTIFICATE-----...",
    "key_alt": "-----BEGIN EC PRIVATE KEY-----...",
    "tags": ["user-level", "low-priority"]
}

証明書の更新または作成

注 : このAPIはDBレスモードでは利用できません。

証明書の作成または更新

属性 | 説明 |—| —- | certificate id
必須 | 作成または更新する証明書の一意の識別子。

特定のアップストリームに関連付けられた証明書の作成または更新

属性 | 説明 |—| —- | upstream name or id
必須 | 作成または更新する証明書に関連付けられたアップストリームの一意の識別子 または 名前。

リクエストボディ

属性名 | 説明 —:| — cert | SSL キーペアのPEMエンコードされた公開証明書チェーン。 このフィールドは「参照可能」です。つまり、[シークレット] (/gateway/latest/plan-and-deploy/security/secrets-management/getting-started/) としてvaultに安全に保存できます。リファレンスは [特定の形式]（/gateway/latest/plan-and-deploy/security/secrets-management/reference-format/）に従う必要があります。 key | SSL キーペアの PEM エンコードされた秘密鍵。このフィールドは「参照可能」です。つまり、[シークレット] (/gateway/latest/plan-and-deploy/security/secrets-management/getting-started/) としてvaultに安全に保存できます。リファレンスは [特定の形式]（/gateway/latest/plan-and-deploy/security/secrets-management/reference-format/）に従う必要があります。 cert_alt
任意 | 代替 SSL 鍵ペアの PEM エンコードされた公開証明書チェーン。 これは、RSA と ECDSA の両方のタイプの証明書が利用可能であり、クライアントが ECDSA 証明書のサポートをアドバタイズするときに Kong が ECDSA 証明書を使用してサービスを優先する場合にのみ設定する必要があります。このフィールドは「参照可能」です。つまり、[シークレット] (/gateway/latest/plan-and-deploy/security/secrets-management/getting-started/) としてvaultに安全に保存できます。リファレンスは [特定の形式]（/gateway/latest/plan-and-deploy/security/secrets-management/reference-format/）に従う必要があります。 key_alt
任意 | 代替 SSL 鍵ペアの PEM エンコードされた秘密鍵。 これは、RSA と ECDSA の両方のタイプの証明書が利用可能であり、クライアントが ECDSA 証明書のサポートをアドバタイズするときに Kong が ECDSA 証明書を使用してサービスを優先する場合にのみ設定する必要があります。このフィールドは「参照可能」です。つまり、[シークレット] (/gateway/latest/plan-and-deploy/security/secrets-management/getting-started/) としてvaultに安全に保存できます。リファレンスは [特定の形式]（/gateway/latest/plan-and-deploy/security/secrets-management/reference-format/）に従う必要があります。 タグ
任意 | グループ化とフィルタリングのための証明書に関連付けられた文字列の任意セット。 SNI
省略形属性 | SNI としてこの証明書に関連付ける 0 個以上のホスト名の配列。 これは便利なパラメータです。内部的には SNI オブジェクトを作成し、それをこの証明書に関連付けます。 この属性を設定するには、この証明書に有効な秘密キーが関連付けられている必要があります。 passphrase
任意（Enterpriseのみ）｜暗号化された秘密鍵をKongにロードするには、この属性を使ってパスフレーズを指定します。Kongが秘密鍵を復号化し、データベースに保存します。Kong のデータベース内の秘密鍵やその他の機密情報を暗号化するには、DB 暗号化の使用を検討してください。

要求されたリソースの下の証明書を、本文で指定された定義に挿入（または置換）します。証明書は、name or id属性によって識別されます。

name or id 属性が UUID の構造を持つ場合、挿入/置換される証明書は、その id によって識別されます。それ以外の場合は、その name で識別されます。

idは、新しい証明書の作成時に（URLにもボディにも）指定されない場合は、自動生成されます。

URLに name を指定して、リクエストボディに異なるものを指定することはできないことに注意してください

レスポンス

HTTP 200 OK

POST応答とPATCH応答を参照してください。

証明書の削除

注 : このAPIはDBレスモードでは利用できません。

証明書の削除

属性 | 説明 |—| —- | certificate id
必須 | 削除する証明書の一意の識別子。

特定のアップストリームに関連付けられた証明書の削除

属性 | 説明 |—| —- | upstream name or id
必須 | 削除する証明書に関連付けられたアップストリームの一意の識別子 または 名前。

レスポンス

HTTP 204 No Content

CA証明書オブジェクト

CA 証明書オブジェクトは、信頼された CA を表します。これらのオブジェクトは、クライアントまたはサーバー証明書の有効性を検証するために Kong によって使用されます。

CA 証明書はタグ付けすることも、タグでフィルタリングすることもできます。

{
    "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
    "tags": ["user-level", "low-priority"]
}

CA証明書の追加

注 : このAPIはDBレスモードでは利用できません。

CA証明書を作成する

リクエストボディ

レスポンス

HTTP 201 Created

{
    "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
    "tags": ["user-level", "low-priority"]
}

CA証明書の一覧表示

すべてのCA証明書の一覧表示

レスポンス

HTTP 200 OK

{

"data": [{
    "id": "43429efd-b3a5-4048-94cb-5cc4029909bb",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
    "tags": ["user-level", "low-priority"]
}, {
    "id": "d26761d5-83a4-4f24-ac6c-cff276f2b79c",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
    "tags": ["admin", "high-priority", "critical"]
}],

    "next": "http://localhost:8001/ca_certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

CA証明書を取得する

CA証明書を取得する

属性 | 説明 |—| —- | ca_certificate id
必須 | 取得するCA証明書の一意の識別子。

レスポンス

HTTP 200 OK

{
    "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
    "tags": ["user-level", "low-priority"]
}

CA証明書を更新

注 : このAPIはDBレスモードでは利用できません。

CA証明書を更新

属性 | 説明 |—| —- | ca_certificate id
必須 | 更新する CA 証明書の一意の識別子。

リクエストボディ

レスポンス

HTTP 200 OK

{
    "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...",
    "tags": ["user-level", "low-priority"]
}

CA 証明書の更新または作成

注 : このAPIはDBレスモードでは利用できません。

CA証明書の作成または更新

属性 | 説明 |—| —- | ca_certificate id
必須 | 作成または更新するCA証明書の一意の識別子。

リクエストボディ

ボディで指定された定義を使用して、CA証明書をリクエストされたリソースに挿入（または置換）します。CA 証明書は、name or id属性を介して識別されます。

name or id属性がUUIDの構造を持つ場合、挿入/置換されるCA証明書は、そのidによって識別されます。それ以外の場合は、そのnameで識別されます。

idをURL内およびボディ内のどちらにも指定せずに新しいCA証明書を作成する場合、自動生成されます。

URLに name を指定して、リクエストボディに異なるものを指定することはできないことに注意してください

レスポンス

HTTP 200 OK

POST応答とPATCH応答を参照してください。

CA証明書を削除

注 : このAPIはDBレスモードでは利用できません。

CA証明書を削除

属性 | 説明 |—| —- | ca_certificate id
必須 | 削除するCA証明書の一意の識別子。

レスポンス

HTTP 204 No Content

SNIオブジェクト

SNIオブジェクトは、ホスト名と証明書を多対1でマッピングします。 つまり、1つの証明書オブジェクトに複数のホスト名を関連付けることができます。Kongは、SSLリクエストを受信すると、Client HelloのSNIフィールドを使用して、証明書に関連付けられたSNIに基づいて証明書オブジェクトを検索します。

SNIはタグ付けすることも、タグでフィルタリングすることもできます。

{
    "id": "91020192-062d-416f-a275-9addeeaffaf2",
    "name": "my-sni",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "tags": ["user-level", "low-priority"],
    "certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"}
}

SNIの追加

注 : このAPIはDBレスモードでは利用できません。

SNIの作成

特定の証明書に関連付けられた SNI の作成

属性 | 説明 |—| —- | certificate name or id
必須 | 新しく作成された SNI に関連付ける証明書の一意の識別子またはname属性。

リクエストボディ

属性 | 説明 —:| — name | 指定された証明書に関連付ける SNI 名。 タグ
任意｜グループ化とフィルタリングのためにSNIに関連付けられた文字列の任意セット。 certificate | SNI ホスト名を関連付ける証明書の ID (UUID)。SNI オブジェクトで使用するには、証明書に有効な秘密鍵が関連付けられている必要があります。フォームがエンコードされている場合、表記はcertificate.id=となります。JSONでは、"certificate":{"id":""}を使用してください。

レスポンス

HTTP 201 Created

{
    "id": "91020192-062d-416f-a275-9addeeaffaf2",
    "name": "my-sni",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "tags": ["user-level", "low-priority"],
    "certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"}
}

SNIの一覧表示

すべてのSNIの一覧表示

特定の証明書に関連付けられたSNIの一覧表示

属性 | 説明 |—| —- | certificate name or id
必須 | SNIを取得する証明書の一意の識別子またはname属性。このエンドポイントを使用すると、指定された証明書に関連付けられたSNIのみがリストされます。

レスポンス

HTTP 200 OK

{

"data": [{
    "id": "147f5ef0-1ed6-4711-b77f-489262f8bff7",
    "name": "my-sni",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "tags": ["user-level", "low-priority"],
    "certificate": {"id":"a3ad71a8-6685-4b03-a101-980a953544f6"}
}, {
    "id": "b87eb55d-69a1-41d2-8653-8d706eecefc0",
    "name": "my-sni",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "tags": ["admin", "high-priority", "critical"],
    "certificate": {"id":"4e8d95d4-40f2-4818-adcb-30e00c349618"}
}],

    "next": "http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

SNIの取得

SNIの取得

属性 | 説明 |—| —- | sni name or id
必須 | 取得する SNI の一意の識別子 または 名前。

特定の証明書に関連付けられたSNIの取得

属性 | 説明 |—| —- | certificate id
必須 | 取得する証明書の一意の識別子。 sni name or id
必須 | 取得するSNIの一意の識別子 または 名前。

レスポンス

HTTP 200 OK

{
    "id": "91020192-062d-416f-a275-9addeeaffaf2",
    "name": "my-sni",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "tags": ["user-level", "low-priority"],
    "certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"}
}

SNIの更新

注 : このAPIはDBレスモードでは利用できません。

SNIの更新

属性 | 説明 ——————————-:| ——————————- sni name or id
必須 | 更新するSNIの一意の識別子 または 名前。

特定の証明書に関連付けられたSNIを更新

属性 | 説明 |—| —- | certificate id
必須 | 更新する証明書の一意の識別子。 sni name or id
必須 | 更新する SNI の一意の識別子 または 名前。

リクエストボディ

属性 | 説明 —:| — name | 指定された証明書に関連付ける SNI 名。 タグ
任意｜グループ化とフィルタリングのためにSNIに関連付けられた文字列の任意セット。 certificate | SNI ホスト名を関連付ける証明書の ID (UUID)。SNI オブジェクトで使用するには、証明書に有効な秘密鍵が関連付けられている必要があります。フォームがエンコードされている場合、表記はcertificate.id=となります。JSONでは、"certificate":{"id":""}を使用してください。

レスポンス

HTTP 200 OK

{
    "id": "91020192-062d-416f-a275-9addeeaffaf2",
    "name": "my-sni",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "tags": ["user-level", "low-priority"],
    "certificate": {"id":"a2e013e8-7623-4494-a347-6d29108ff68b"}
}

SNIの更新または作成

注 : このAPIはDBレスモードでは利用できません。

SNIの作成または更新

属性 | 説明 ——————————-:| ——————————- sni name or id
必須 | 作成または更新する SNI の一意の識別子 または 名前。

特定の証明書に関連付けられたSNIを作成または更新する

属性 | 説明 ---：|--- certificate id
必須 | 作成または更新する証明書の一意の識別子。 sni name or id
必須 | 作成または更新するSNIの一意の識別子 または 名前。

リクエストボディ

属性 | 説明 —:| — name | 指定された証明書に関連付ける SNI 名。 タグ
任意｜グループ化とフィルタリングのためにSNIに関連付けられた文字列の任意セット。 certificate | SNI ホスト名を関連付ける証明書の ID (UUID)。SNI オブジェクトで使用するには、証明書に有効な秘密鍵が関連付けられている必要があります。フォームがエンコードされている場合、表記はcertificate.id=となります。JSONでは、"certificate":{"id":""}を使用してください。

リクエストされたリソースの下に、本文で指定された定義のSNIを挿入（または置換）します。SNIは、name or id属性によって識別されます。

name or id属性がUUID構造をとる場合、挿入されるまたは置き換えられるSNIは、そのidによって識別されます。それ以外の場合は、そのnameで識別されます。

id を URL 内およびボディ内のどちらにも指定せずに新しいSNIを作成する場合、自動生成されます。

URLに name を指定して、リクエストボディに異なるものを指定することはできないことに注意してください

レスポンス

HTTP 200 OK

POST応答とPATCH応答を参照してください。

SNIの削除

注 : このAPIはDBレスモードでは利用できません。

SNIの削除

属性 | 説明 ——————————-:| ——————————- sni name or id
必須 |削除するSNIの一意の識別子 または 名前。

特定の証明書に関連付けられた SNI の削除

属性 | 説明 |—| —- | certificate id
必須 | 削除する証明書の一意の識別子。 sni name or id
必須 | 削除する SNI の一意の識別子 または 名前。

レスポンス

HTTP 204 No Content

アップストリームオブジェクト

アップストリームオブジェクトは仮想ホスト名を表し、複数のサービス（ターゲット）にわたる受信リクエストのロードバランシングに使用できます。たとえば、host が service.v1.xyz であるサービスオブジェクトの service.v1.xyz という名前のアップストリームなどです。このサービスに対するリクエストは、アップストリーム内で定義されたターゲットにプロキシされます。

アップストリームにはヘルスチェッカーも含まれており、それを使うとリクエストを処理できるかどうかに基づいてターゲットを有効または無効にすることができます。ヘルスチェッカーの構成は、アップストリームオブジェクトに格納され、そのすべてのターゲットに適用されます。

アップストリームはタグ付けすることも、タグでフィルタリングすることもできます。

{
    "id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-upstream",
    "algorithm": "round-robin",
    "hash_on": "none",
    "hash_fallback": "none",
    "hash_on_cookie_path": "/",
    "slots": 10000,
    "healthchecks": {
        "passive": {
            "type": "http",
            "healthy": {
                "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308],
                "successes": 0
            },
            "unhealthy": {
                "http_statuses": [429, 500, 503],
                "timeouts": 0,
                "http_failures": 0,
                "tcp_failures": 0
            }
        },
        "active": {
            "https_verify_certificate": true,
            "healthy": {
                "http_statuses": [200, 302],
                "successes": 0,
                "interval": 0
            },
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
                "timeouts": 0,
                "tcp_failures": 0,
                "interval": 0
            },
            "type": "http",
            "concurrency": 10,
            "headers": [{"x-my-header":["foo", "bar"], "x-another-header":["bla"]}],
            "timeout": 1,
            "http_path": "/",
            "https_sni": "example.com"
        },
        "threshold": 0
    },
    "tags": ["user-level", "low-priority"],
    "host_header": "example.com",
    "client_certificate": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"},
    "use_srv_name": false
}

アップストリームの追加

注 : このAPIはDBレスモードでは利用できません。

アップストリームの作成

特定の証明書に関連付けられたアップストリームの作成

属性 | 説明 |—| —- | certificate name or id
必須 | 新しく作成されたアップストリームに関連付ける証明書の一意の識別子またはname属性。

リクエストボディ

属性名 | 説明 —: |— name | これはホスト名です。サービスの「ホスト」と同じでなければなりません。 algorithm
任意 | 使用するロードバランシングアルゴリズム。受け入れられる値は、"consistent-hashing"、"least-connections"、 "round-robin"、"latency"です。デフォルト："latency"。 hash_on
任意 | 使用するハッシュ入力。none を使用すると、ハッシュなしの加重ラウンドロビン方式になります。受け入れられる値は："none"、"consumer"、"ip"、 " header " 、 "cookie"、"path"、"query_arg"、"uri_capture"。デフォルト: "none"。 hash_fallback
任意 | hash_on がハッシュを返さない場合にハッシュの入力として使用するもの (例.ヘッダーが欠落しているか、コンシューマが識別されていません)。hash_on が cookie に設定されている場合は使用できません。受け入れられる値は："none"、"consumer"、"ip"、 " header " 、 "cookie"、"path"、"query_arg"、"uri_capture"。デフォルト: "none"。 hash_on_header
セミオプション｜ハッシュの入力として値を受け取るヘッダー名。hash_on が header に設定されている場合にのみ必要です。 hash_fallback_header
セミオプション | ハッシュの入力として値を受け取るヘッダー名。hash_fallback が header に設定されている場合にのみ必要です。 hash_on_cookie 。
セミオプション｜ハッシュの入力として値を取得するcookieの名前。hash_on または hash_fallback が cookie に設定されている場合にのみ必要です。指定された Cookie がリクエストにない場合、Kong は値を生成し、応答に Cookie を設定します。 hash_on_cookie_path：
セミオプション｜レスポンスヘッダーに設定するクッキーのパス。hash_on または hash_fallback が cookie に設定されている場合にのみ必要です。デフォルト: ‘"/"‘。hash_on_query_arg：
ハッシュの入力として値を受け取るクエリ文字列の名前。hash_on が query_arg に設定されている場合にのみ必要です。 hash_fallback_query_arg：
セミオプション* | ハッシュの入力として値を受け取るクエリ文字列の名前。hash_fallback が query_arg に設定されている場合にのみ必要です。 hash_on_uri_capture
セミオプション | ハッシュの入力として値を受け取るルート URI キャプチャの名前。hash_on が uri_capture に設定されている場合にのみ必要です。 hash_fallback_uri_capture を指定します。
セミオプション | ハッシュの入力として値を受け取るルート URI キャプチャの名前。 hash_fallback が uri_capture に設定されている場合にのみ必要です。 slots
任意 | ロードバランサーアルゴリズムのスロット数。 algorithmが round-robin に設定されている場合、この設定によってスロットの最大数が決まります。algorithm が consistent-hashingに設定されている場合、この設定によってアルゴリズムの実際のスロット数が決まります。10から65536までの整数を指定します。デフォルト: ‘10000’。 healthchecks.passive. type
任意 | HTTP/HTTPS ステータスを解釈するパッシブヘルスチェックを行うか、TCP 接続の成功だけをチェックするかを示しています。パッシブチェックでは、 httpとHTTPSオプションは同等です。受け入れられる値は、 "tcp" 、http、 "https" 、 "grpc" 、 "grpcs" です。デフォルトは、http。 healthchecks.passive. healthy.http_statuses
任意 | パッシブヘルスチェックによって観測された、プロキシされたトラフィックによって生成されたときの健全性を表す HTTP ステータスの配列。デフォルト: [200、201、202、203、204、205、206、207、208、226、300、301、302、303、304、305、306、307、308] 。form-encodedの場合、http_statuses[]=200&http_statuses[]=201となります。JSONでは、配列を使用します。 healthchecks.passive. healthy.successes
任意 | プロキシされたトラフィックの成功数（ healthchecks.passive.healthy.http_statusesで定義）パッシブヘルスチェックによって観察されたターゲットが正常であると見なします。デフォルト: 0 healthchecks.passive. unhealthy.http_statuses
任意 | パッシブヘルスチェックによって観測された、プロキシされたトラフィックによって生成されたときの 不健全性を表す HTTP ステータスの配列。 デフォルト: ‘[429, 500, 503]’。 form-encodedの場合、http_statuses[]=429&http_statuses[]=500となります。JSONでは、配列を使用します。 healthchecks.passive. ‘unhealthy.timeouts’
任意 | パッシブヘルスチェックで確認された、ターゲットが正常でないと見なされるプロキシトラフィックのタイムアウト回数。デフォルト: 0 healthchecks.passive. unhealthy.http_failures
任意 | パッシブヘルスチェックによって観測され、ターゲットが正常でないと判断される、プロキシされたトラフィック内の HTTP 失敗の数 (healthchecks.passive.unhealthy.http_statusesで定義)。デフォルト: 0 healthchecks.passive. unhealthy.tcp_failures
任意 | パッシブヘルスチェックによって観測され、ターゲットが正常でないと判断されるプロキシトラフィック内の TCP 失敗数。デフォルト: 0healthchecks.active.https_verify_certificate | HTTPS を使用してアクティブヘルスチェックを実行するときに、リモートホストの SSL 証明書の有効性をチェックするかどうか。デフォルト: true。 healthchecks.active. healthy.http_statuses
任意 | アクティブヘルスチェックのプローブから返されたときに、健全性を示す 成功とみなす HTTP ステータスの配列。 デフォルト: ‘[200, 302]’。form-encodedの場合、http_statuses[]=200&http_statuses[]=302となります。JSONでは、配列を使用します。 healthchecks.active. healthy.successes
任意 | ターゲットを正常と見なすため、アクティブプローブの成功数（healthchecks.active.healthy.http_statusesで定義）デフォルト: 0healthchecks.active.healthy.interval
任意 | 正常なターゲットのアクティブなヘルスチェックの間隔 (秒単位)。値がゼロの場合、正常なターゲットに対してアクティブなプローブを実行しないことを示します。デフォルト: 0 healthchecks.active.unhealthy.http_failures
任意 | ターゲットが異常であると判断されるアクティブプローブ内の HTTP 失敗の数 ( healthchecks.active.unhealthy.http_statuses で定義)。デフォルト: 0 healthchecks.active. unhealthy.http_statuses
任意 | アクティブヘルスチェックのプローブから返されたときに、不健全を示す失敗とみなす HTTP ステータスの配列。デフォルト: [429、404、500、501、502、503、 504、505]。form-encodedの場合、表記はhttp_statuses[]=429&http_statuses[]=404となります。JSONでは、配列を使用します。healthchecks.active.’unhealthy.timeouts’
任意 | ターゲットが正常でないと見なされるアクティブプローブのタイムアウト回数。デフォルト: 0healthchecks.active.unhealthy.tcp_failures
任意 | ターゲットが異常であると判断されるアクティブ プローブでの TCP 失敗の数。デフォルト: 0 healthchecks.active. unhealthy.interval
任意 | 正常でないターゲットのアクティブなヘルスチェックの間隔 (秒単位)。値がゼロの場合、正常でないターゲットに対してアクティブ プローブを実行しないことを示します。デフォルト: 0healthchecks.active.type
任意 | HTTP または HTTPS を使用してアクティブヘルスチェックを実行するか、単に TCP 接続を試行するか。 受け入れられる値は、 "tcp" 、http、 "https" 、 "grpc" 、 "grpcs" です。デフォルトは、http。 healthchecks.active. concurrency
任意 | アクティブなヘルスチェックで同時にチェックするターゲットの数。デフォルト: ‘10’。 healthchecks.active. headers
任意 | アクティブなヘルスチェックのプローブとして実行するGET HTTPリクエストで使用する、ヘッダー名で索引付けされた1つ以上の値のリスト。 値は事前にフォーマットしておく必要があります。 healthchecks.active. timeout
任意 | アクティブなヘルスチェックのソケットタイムアウト (秒単位)。デフォルト: ‘1’ healthchecks.active. http_path
任意 | アクティブなヘルスチェックのプローブとして実行する GET HTTP リクエストで使用するパス。 デフォルト: ‘"/"‘。 healthchecks.active. https_sni
任意 | HTTPS を使用してアクティブヘルスチェックを実行するときに SNI (Server Name Identification) として使用するホスト名。これは、ターゲットが IP を使用して構成されている場合に特に役立ち、ターゲットホストの証明書を適切な SNI で検証できます。 ‘healthchecks.threshold’
任意 | 上流全体が健康であると見なされるためには、上流のターゲットの重量の最小パーセンテージです。デフォルト: 0tags
任意｜グループ化とフィルタリングのためにUpstreamに関連付けられた文字列の任意セット。 host_header
任意 | Kong 経由でリクエストをプロキシするときに Host ヘッダとして使われるホスト名。 client_certificate
任意 | 設定されている場合、上流サーバとのTLSハンドシェイク時にクライアント証明書として使用する証明書。form-encodedの場合、 client_certificate.id= という表記になります。JSONの場合は、"client_certificate":{"id":""} を使用します。 use_srv_name
*任意* | 設定すると、バランサは上流の Host プロキシとして SRV ホスト名 (DNS アンサーに SRV レコードがある場合) を使います。

レスポンス

HTTP 201 Created

{
    "id": "58c8ccbb-eafb-4566-991f-2ed4f678fa70",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-upstream",
    "algorithm": "round-robin",
    "hash_on": "none",
    "hash_fallback": "none",
    "hash_on_cookie_path": "/",
    "slots": 10000,
    "healthchecks": {
        "passive": {
            "type": "http",
            "healthy": {
                "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308],
                "successes": 0
            },
            "unhealthy": {
                "http_statuses": [429, 500, 503],
                "timeouts": 0,
                "http_failures": 0,
                "tcp_failures": 0
            }
        },
        "active": {
            "https_verify_certificate": true,
            "healthy": {
                "http_statuses": [200, 302],
                "successes": 0,
                "interval": 0
            },
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
                "timeouts": 0,
                "tcp_failures": 0,
                "interval": 0
            },
            "type": "http",
            "concurrency": 10,
            "headers": [{"x-my-header":["foo", "bar"], "x-another-header":["bla"]}],
            "timeout": 1,
            "http_path": "/",
            "https_sni": "example.com"
        },
        "threshold": 0
    },
    "tags": ["user-level", "low-priority"],
    "host_header": "example.com",
    "client_certificate": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"},
    "use_srv_name": false
}