コンテンツにスキップ
Kong Logo | Kong Docs Logo
  • ドキュメント
    • API仕様を確認する
      View all API Specs すべてのAPI仕様を表示 View all API Specs arrow image
    • ドキュメンテーション
      API Specs
      Kong Gateway
      軽量、高速、柔軟なクラウドネイティブAPIゲートウェイ
      Kong Konnect
      SaaSのエンドツーエンド接続のための単一プラットフォーム
      Kong AI Gateway
      GenAI インフラストラクチャ向けマルチ LLM AI Gateway
      Kong Mesh
      Kuma と Envoy をベースにしたエンタープライズサービスメッシュ
      decK
      Kongの構成を宣言型で管理する上で役立ちます
      Kong Ingress Controller
      Kubernetesクラスタ内で動作し、Kongをプロキシトラフィックに設定する
      Kong Gateway Operator
      YAMLマニフェストを使用してKubernetes上のKongデプロイメントを管理する
      Insomnia
      コラボレーティブAPI開発プラットフォーム
  • Plugin Hub
    • Plugin Hubを探索する
      View all plugins すべてのプラグインを表示 View all plugins arrow image
    • 機能性 すべて表示 View all arrow image
      すべてのプラグインを表示
      AI's icon
      AI
      マルチ LLM AI Gatewayプラグインを使用してAIトラフィックを管理、保護、制御する
      認証's icon
      認証
      認証レイヤーでサービスを保護する
      セキュリティ's icon
      セキュリティ
      追加のセキュリティレイヤーでサービスを保護する
      トラフィック制御's icon
      トラフィック制御
      インバウンドおよびアウトバウンドAPIトラフィックの管理、スロットル、制限
      サーバーレス's icon
      サーバーレス
      他のプラグインと組み合わせてサーバーレス関数を呼び出します
      分析と監視's icon
      分析と監視
      APIとマイクロサービストラフィックを視覚化、検査、監視
      変革's icon
      変革
      Kongでリクエストとレスポンスをその場で変換
      ログ記録's icon
      ログ記録
      インフラストラクチャに最適なトランスポートを使用して、リクエストと応答データをログに記録します
  • サポート
  • コミュニティ
  • Kongアカデミー
デモを見る 無料トライアルを開始
Kong Gateway
3.8.x
  • Home icon
  • Kong Gateway
  • Plugin Development
  • カスタムエンティティの保存
report-issue問題を報告する
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Kong AI Gateway
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • ドキュメント投稿ガイドライン
  • 3.10.x (latest)
  • 3.9.x
  • 3.8.x
  • 3.7.x
  • 3.6.x
  • 3.5.x
  • 3.4.x (LTS)
  • 3.3.x
  • 2.8.x (LTS)
  • アーカイブ (2.6より前)
  • はじめに
    • Kong Gatewayの概要
    • サポート
      • バージョンサポートポリシー
      • サードパーティの依存関係
      • ブラウザサポート
      • 脆弱性パッチ適用プロセス
      • ソフトウェア部品表
    • 安定性
    • リリースノート
    • 破壊的な変更
      • Kong Gateway 3.8.x
      • Kong Gateway 3.7.x
      • Kong Gateway 3.6.x
      • Kong Gateway 3.5.x
      • Kong Gateway 3.4.x
      • Kong Gateway 3.3.x
      • Kong Gateway 3.2.x
      • Kong Gateway 3.1.x
      • Kong Gateway 3.0.x
      • Kong Gateway 2.8.x 以前
    • キーコンセプト
      • サービス
      • ルート
      • コンシューマ
      • アップストリーム
      • プラグイン
      • コンシューマグループ
    • How Kong Works
      • ルーティングトラフィック
      • ロードバランシング
      • ヘルスチェックとサーキットブレーカ
    • 用語集
  • Kong を始めよう
    • Kong をゲットする
    • サービスとルート
    • レート制限
    • プロキシキャッシュ
    • キー認証
    • ロードバランシング
  • コングをインストールする
    • 概要
    • Kubernetes
      • 概要
      • Kong Gatewayをインストール
      • Admin API
      • Kong Manager をインストールする
    • Docker
      • docker run を使用する
      • 独自の Docker イメージをビルドする
    • Linux
      • Amazon Linux
      • Debian
      • Red Hat
      • Ubuntu
    • インストール後
      • データストアを設定
      • エンタープライズライセンスを適用
      • Kong Managerを有効にする
  • Kong in production
    • 展開のトポロジーズ
      • 概要
      • ハイブリッドモード
        • 概要
        • ハイブリッドモードでKong Gatewayをデプロイする
      • DB-lessデプロイ
      • 繁体字版
    • Running Kong
      • non-rootユーザーとしてKongを実行しています
      • 管理者 API の保護
      • systemdの使用
    • アクセスコントロール
      • コングゲートウェイを安全に開始
      • プログラムによる管理者の作成
      • RBAC を有効にする
    • ライセンス
      • 概要
      • ライセンスをダウンロード
      • エンタープライズライセンスのデプロイ
      • ライセンスAPIの使用
      • ライセンス使用状況をモニターする
    • ネットワーク
      • デフォルトのポート
      • DNSに関する考察
      • ネットワークとファイアウォール
      • CP/DP Communication through a Forward Proxy
      • PostgreSQL TLS
        • PostgreSQL TLS の設定
        • PostgreSQL TLS のトラブルシューティング
    • Kongの設定ファイル
    • 環境変数
    • KongからウェブサイトとAPIを提供する
    • モニタリング
      • 概要
      • Prometheus
      • StatsD
      • Datadog
      • ヘルスチェックプローブ
      • AIメトリクスを公開してグラフ
    • トレース
      • 概要
      • カスタム・トレース・エクスポーターの作成
      • トレースAPIリファレンス
    • リソースサイズのガイドライン
    • セキュリティアップデートプロセス
    • ブルー・グリーンの展開
    • カナリアのデプロイ
    • クラスタリングリファレンス
    • パフォーマンス
      • パフォーマンステストのベンチマーク
      • パフォーマンスのベンチマークを作成
      • Brotli圧縮によるパフォーマンスの向上
    • ロギングとデバッグ
      • ログの参照
      • ダイナミックログレベルの更新
      • ゲートウェイログをカスタマイズ
      • デバッグリクエスト
      • AIゲートウェイ分析
    • gRPCサービスの設定
    • 式ルータを使用
    • アップグレードと移行
      • 香港ゲートウェイ3.x.xをアップグレードする
      • バックアップと復元
      • アップグレードの戦略
        • デュアルクラスターのアップグレード
        • インプレイスアップグレード
        • 青緑色のアップグレード
        • ローリングアップグレード
      • 2.8 LTSから3.4 LTSにアップグレード
      • OSSからエンタープライズへ移行
      • 移行ガイドライン Cassandra から PostgreSQL
      • 新しい DNS クライアントに移行
      • 破壊的な変更
  • Kong Gateway Enterprise
    • 概要
    • シークレット管理
      • 概要
      • はじめに
      • ローテーション
      • 高度な使い方
      • バックエンドの設定
        • 概要
        • 環境変数
        • AWS シークレットマネージャー
        • Azure Key Vault
        • Google Cloud Secret Manager
        • HashiCorp Vault
      • How-To
        • AWS シークレットマネージャでデータベースを保護する
      • 参照フォーマット
    • 動的なプラグインの順序
      • 概要
      • 動的なプラグインの順序を始めましょう
    • 監査ログ
    • キーリングとデータ暗号化
    • ワークスペース
    • コンシューマグループ
    • イベントフック
    • データ プレーンレジリエンスの設定
    • 制御機の停止管理について
    • FIPS 140-2
      • 概要
      • FIPS 準拠パッケージをインストール
      • FIPS 140-2 準拠プラグイン
    • AWS IAMでKong Gateway Amazon RDSデータベースを認証する
    • 署名された香港の画像の署名を確認します
    • 署名された香港画像のビルド証明書を確認する
  • Kong AI Gateway
    • 概要
    • AI ゲートウェイを始めよう
    • LLM プロバイダー統合ガイド
      • OpenAI
      • Cohere
      • Azure
      • Anthropic
      • ミストラル
      • Llama2
    • AIプラットフォーム統合ガイド
      • Gemini
      • Amazon Bedrock
    • AIゲートウェイ分析
    • AI指標を公開・グラフ
    • AI Gateway plugins
  • Kong Manager
    • 概要
    • Kong Managerを有効にする
    • Kong Manager を始めましょう
      • サービスとルート
      • レート制限
      • プロキシキャッシュ
      • コンシューマーとの認証
      • 負荷バランス
    • 認証と承認
      • 概要
      • スーパー管理者を作成
      • ワークスペースとチーム
      • パスワードとRBACトークンをリセット
      • ベーシック認証
      • LDAP
        • LDAP の設定
        • LDAP サービス ディレクトリ マッピング
      • OIDC
        • OIDCの設定
        • OIDC 認証済みグループマッピング
        • 以前の設定から移行
      • セッション
      • RBAC
        • 概要
        • RBACを有効にする
        • ロールと権限を追加
        • ユーザーを作成
        • 管理者を作成
    • ネットワーク設定
    • ワークスペース
    • 顧客グループを作成
    • メールを送信中
    • トラブルシューティング
  • カスタムプラグインを開発
    • 概要
    • はじめに
      • はじめに
      • プラグインプロジェクトの設定
      • プラグインテストを追加
      • プラグイン設定を追加
      • 外部サービスを消費する
      • プラグインをデプロイ
    • ファイル構造
    • カスタムロジックの実装
    • プラグインの設定
    • データストアへのアクセス
    • カスタムエンティティの保存
    • カスタムエンティティをキャッシュ中
    • 管理者 API の拡張
    • テストを書く
    • 設置と配布
    • プロキシ-ワズムフィルター
      • プロキシワズムフィルタを作成
      • プロキシ-ワズムフィルタの設定
    • プラグイン開発キット
      • 概要
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.jwe
      • kong.log
      • kong.nginx
      • kong.node
      • kong.plugin
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.telemetry.log
      • kong.tracing
      • kong.vault
      • kong.websocket.client
      • kong.websocket.upstream
    • 他の言語でのプラグイン
      • 移動
      • Javascript
      • Python
      • コンテナでのプラグインの実行
      • 外部プラグインのパフォーマンス
  • Kong Plugins
    • 概要
    • 認証リファレンス
    • 複数の認証プラグインを許可
    • プラグインのキュー
      • 概要
      • プラグインキューイングリファレンス
  • Admin API
    • 概要
    • 宣言設定
    • Enterprise API
      • 情報ルート
      • 健康ルート
      • タグ
      • デバッグルート
      • サービス
      • ルート
      • コンシューマ
      • プラグイン
      • 証明書
      • CA 証明書
      • SNI
      • アップストリーム
      • ターゲット
      • ヴォールト
      • キー
      • チェーンをフィルター
      • ライセンス
      • ワークスペース
      • RBAC
      • 管理者
      • コンシューマグループ
      • イベントフック
      • キーリングとデータ暗号化
      • 監査ログ
      • Status API
    • オープンソースAPI
  • 参照
    • kong.conf
    • Nginx ディレクティブの注入中
    • CLI
    • キー管理
    • 表現の言語
      • 概要
      • 言語リファレンス
      • パフォーマンスの最適化
    • ライブラリのレート制限
    • WebAssembly
    • FAQ
enterprise-switcher-icon 次に切り替える: OSS
On this pageOn this page
  • モジュール
  • 移行フォルダの作成
  • 既存のプラグインに新しい移行を追加
  • 移行ファイルの構文
  • スキーマを定義する
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。

カスタムエンティティの保存

すべてのプラグインがそれを必要とするわけではありませんが、プラグインは、データベースでの構成以上のものを保存する必要があるかもしれません 。その場合、Kongは プライマリデータストアに加えて、抽象化したものを提供し、カスタムエンティティを保存できるようにします。

前の章で説明したように、Kongは “DAO”と呼ばれ、”DAOファクトリー”と呼ばれるシングルトンで利用できるクラスをとおして モデルレイヤーと相互作用します。この章では、 独自のエンティティの抽象化を提供する方法を説明します。

モジュール

kong.plugins.<plugin_name id="sl-md0000000">.daos
kong.plugins.<plugin_name id="sl-md0000000">.migrations.init
kong.plugins.<plugin_name id="sl-md0000000">.migrations.000_base_<plugin_name id="sl-md0000000">
kong.plugins.<plugin_name id="sl-md0000000">.migrations.001_<from-version id="sl-md0000000">_to_<to_version id="sl-md0000000">
kong.plugins.<plugin_name id="sl-md0000000">.migrations.002_<from-version id="sl-md0000000">_to_<to_version id="sl-md0000000">

移行フォルダの作成

モデルの定義を終えたら、Kongにより実行されエンティティの記録が 保存されるテーブルを作成する、移行モジュールを作成する必要が あります。

プラグインにまだない場合は、<plugin_name id="sl-md0000000">/migrationsフォルダをプラグインに追加します。init.luaファイルがフォルダ内にない場合は、1つ作成します。 ここで、プラグインのすべての移行が参照されます。

お使いのmigrations/init.luaファイルの初回バージョンは単一の移行を指します。

この例では、その移行を000_base_my_pluginと呼びます。

-- `migrations/init.lua`
return {
  "000_base_my_plugin",
}

これは、初期移行を含むファイルが<plugin_name id="sl-md0000000">/migrations/000_base_my_plugin.luaに存在することを意味します。これがどのように行われるかは、次で説明します。

既存のプラグインに新しい移行を追加

プラグインのバージョンがリリースされた後で、変更を導入する必要がある場合が あります。新しい機能が必要になる場合があります。データベーステーブルの行の変更が必要となる可能性があります。

この場合、新しい移行ファイルを作成する必要があります 。 既存のマイグレーションファイルが公開された後は、変更してはいけません(必要であれば、より堅牢で 防弾にすることはできます。例えば、マイグレーションを常にリエントラントに書くようにします)。

移行ファイルに命名するための厳密なルールはありませんが、最初のファイルに000、次のファイルに001というようにプレフィックスを付けるという規則があります。

前の例に続いて、データベースに変更を加えた新しいバージョンのプラグインをリリースする場合(例えば foo というテーブルが必要でした)、<plugin_name id="sl-md0000000">/migrations/001_100_to_110.lua というファイルを追加し、migrations init ファイルで次のように参照します(100 はプラグインの以前のバージョン 1.0.0、110 はプラグインが 1.1.0 に移行されるバージョン)。

-- `<plugin_name id="sl-md0000000">/migrations/init.lua`
return {
  "000_base_my_plugin",
  "001_100_to_110",
}

移行ファイルの構文

移行ファイルは、次の構造を持つテーブルを返すLuaファイルです。

-- `<plugin_name id="sl-md0000000">/migrations/000_base_my_plugin.lua`
return {
  postgres = {
    up = [[
      CREATE TABLE IF NOT EXISTS "my_plugin_table" (
        "id"           UUID                         PRIMARY KEY,
        "created_at"   TIMESTAMP WITHOUT TIME ZONE,
        "col1"         TEXT
      );

      DO $$
      BEGIN
        CREATE INDEX IF NOT EXISTS "my_plugin_table_col1"
                                ON "my_plugin_table" ("col1");
      EXCEPTION WHEN UNDEFINED_COLUMN THEN
        -- Do nothing, accept existing state
      END$$;
    ]],
  }
}

-- `<plugin_name id="sl-md0000000">/migrations/001_100_to_110.lua`
return {
  postgres = {
    up = [[
      DO $$
      BEGIN
        ALTER TABLE IF EXISTS ONLY "my_plugin_table" ADD "cache_key" TEXT UNIQUE;
      EXCEPTION WHEN DUPLICATE_COLUMN THEN
        -- Do nothing, accept existing state
      END;
    $$;
    ]],
    teardown = function(connector, helpers)
      assert(connector:connect_migrations())
      assert(connector:query([[
        DO $$
        BEGIN
          ALTER TABLE IF EXISTS ONLY "my_plugin_table" DROP "col1";
        EXCEPTION WHEN UNDEFINED_COLUMN THEN
          -- Do nothing, accept existing state
        END$$;
      ]])
    end,
  }
}

各ストラテジセクションには、 upとteardown 2 つの部分があります。

  • upは、生のSQLステートメントのオプション文字列です。これらのステートメントは、 kong migrations upが実行されたときに実行されます。

    新しいテーブルの作成や新規レコードの追加といったあらゆる非破壊的な操作は、up セクションで実行することをお勧めします。

  • teardown はオプションの Lua 関数であり、connector パラメータを受け取ります。コネクタ は query メソッドを呼び出して SQL クエリを実行できます。ティアダウンは kong migrations finish によって引き起こされます。

    データの削除や行タイプの変更、新規データの挿入といった破壊的な操作は、teardown セクションで実行することをお勧めします。

すべての SQLステートメントは、可能な限り再入可能になるように記述する必要があります。たとえば、 DROP TABLEの代わりにDROP TABLE IF EXISTSを使用し、CREATE INDEXの代わりにCREATE INDEX IF NOT EXISTを使用するなど。移行が何らかの理由で失敗した場合、問題解決での最初の試行は、単純に移行のやりなおしとなることが考えられます。

schemaでunique制約を使用している場合は、PostgreSQLの移行でこの制約を設定する必要があります。

実際の例を確認するには、Key-Auth プラグインの移行を参照してください。

スキーマを定義する

カスタムプラグインでカスタムエンティティを使用する最初のステップは、1つまたは複数の スキーマ を定義することです。

スキーマはエンティティを記述するLuaテーブルです。たとえば、エンティティのさまざまなフィールドの名前やタイプは何か、などの構造情報があります。 これは、プラグイン設定を説明するフィールドに似ています。 プラグイン設定スキーマと比較すると、カスタムエンティティスキーマには 追加のメタデータが必要です(たとえば、どのフィールドがエンティティのプライマリキーを構成するかなど)。

スキーマは、次の名前のモジュールで定義します。

kong.plugins.<plugin_name id="sl-md0000000">.daos

つまり、プラグインフォルダ内に <plugin_name id="sl-md0000000">/daos.lua というファイルがあるはずです。daos.lua ファイルは、1 つ以上のスキーマを含むテーブルを返します。以下に例を示します。

-- daos.lua
local typedefs = require "kong.db.schema.typedefs"


return {
  -- this plugin only results in one custom DAO, named `keyauth_credentials`:
  {
    name                  = "keyauth_credentials", -- the actual table in the database
    endpoint_key          = "key",
    primary_key           = { "id" },
    cache_key             = { "key" },
    generate_admin_api    = true,
    admin_api_name        = "key-auths",
    admin_api_nested_name = "key-auth",
    fields = {
      {
        -- a value to be inserted by the DAO itself
        -- (think of serial id and the uniqueness of such required here)
        id = typedefs.uuid,
      },
      {
        -- also interted by the DAO itself
        created_at = typedefs.auto_timestamp_s,
      },
      {
        -- a foreign key to a consumer's id
        consumer = {
          type      = "foreign",
          reference = "consumers",
          default   = ngx.null,
          on_delete = "cascade",
        },
      },
      {
        -- a unique API key
        key = {
          type      = "string",
          required  = false,
          unique    = true,
          auto      = true,
        },
      },
    },
  },
}

この例のdaos.luaファイルでは、 keyauth_credentialsと呼ばれる単一のスキーマを導入しています。

以下は、最上位プロパティの説明です。

</tbody> </table> 多くのフィールド属性は、 *検証ルール* をエンコードします。DAOを使用してエンティティを挿入または更新しようとすると、これらの検証がチェックされ、指定された入力がそれらに適合しない場合はエラーが返されます。 `typedefs` 変数(`kong.db.schema.typedefs` を要求することで取得)は、プライマリキーの最も一般的な型である `typedefs.uuid` や `created_at` フィールドの `typedefs.auto_timestamp_s` など、多くの便利な型定義と別名を含むテーブルです。これは、フィールドを定義するときに広く使用されます。 以下は、使用可能ないくつかのフィールド属性の説明の抜粋です。
名称 タイプ 説明
name string(必須) DAO名(kong.db.\[name\])の決定に使用されます。
primary_key table(必須) エンティティのプライマリキーを形成するフィールド名。 スキーマは、ほとんどのKongコアエンティティがidという名前のUUIDを使用している場合でも、複合キーをサポートします。
endpoint_key string\(オプション\) Admin APIで代替識別子として使用されるフィールドの名前。上の例ではkeyが endpoint\_key です。つまり、id = 123 と key = "foo" を持つ認証情報は、/keyauth_credentials/123 と /keyauth_credentials/foo の両方として参照できます。
cache_key table\(オプション\) cache_keyの生成に使用されるフィールドの名前が含まれ、Kongのキャッシュ内のエンティティを明確に識別する必要がある文字列です。通常、例のkeyのような一意のフィールドが適切な候補となります。その他の場合には、複数のフィールドを組み合わせることが望ましいです。
generate_admin_api boolean\(オプション\) エンティティの管理apiを自動生成するかどうか。デフォルトでは、admin apiはカスタムのものを含むすべてのdaoに対して生成されます。dao用に完全にカスタマイズされた管理apiを作成する場合、またはdaoの自動生成を完全に無効にする場合は、このオプションを false に設定します。
admin_api_name boolean\(オプション\) generate_admin_apiが有効になっている場合、admin api 自動ジェネレーターは、自動生成された管理apiのコレクションURLを取得するためにnameを使用します。コレクションURLにnameとは異なる別の名前を付けたい場合もあるでしょう。例えば、DAO keyauth_credentialsにおいては、実際に、自動生成ツールがこのDAOのためのエンドポイントを、別の、より分かりやすいURL名key-authsで生成してくれることを期待していました。(例:http:///keyauth_credentials</code>ではなくhttp:///key-auths</code>など)。 </td> </tr>
admin_api_nested_name boolean\(オプション\) admin_api_nameと同様に、admin_api_nested_nameは、admin api 自動ジェネレータがネストされたコンテキストで作成する dao の名前を指定します。このパラメーターは、nameやadmin_api_nameに満足できない場合にのみ使用する必要があります。レガシー上の理由から、Kongにはkey-authが複数形のhttp:///key-auths</code>に従わないhttp:///consumers/john/key-auth</code>のようなURLがあります。admin_api_nested_name では、このような場合に別の名前を指定できます。</td> </tr>
fields table 各フィールド定義は単一のキーを持つテーブルで、これはフィールド名です。テーブルの値は、 フィールドの属性を含むサブテーブルを含んでおり、その一部については後述します。
属性名 タイプ 説明
type string スキーマは、"string"、"integer"、"number"、"boolean" のスカラー型をサポートします。"array"、"record"、"set" などの複合型もサポートされています。

In addition to these values, the type attribute can also take the special "foreign" value, which denotes a foreign relationship.

Each field will need to be backed by database fields of appropriately similar types, created via migrations.

type is the only required attribute for all field definitions.
default any(type属性との一致) 値が指定されていない場合に、フィールドを挿入しようとしたときにフィールドが持つ値を指定します。デフォルト値は常にLua経由で設定され、基盤となるデータベースによって設定されることはありません。したがって、移行のフィールドにデフォルト値を設定することはお勧めしません
required boolean フィールド上でtrueを設定する際に、特定のフィールドに値がないエンティティを挿入しようとするとエラーが発生します(該当フィールドにデフォルト値がある場合を除く)。
unique boolean

フィールドがtrue に設定される場合にデータベースにエンティティを挿入しようとすると、エラーがスローされますが、別のエンティティで既にそのフィールドに指定済みの値があります。

この属性は、PostgreSQLを使用するときに、マイグレーションでフィールドを UNIQUE として宣言することでバックアップする必要があります。

auto boolean auto が true に設定されているフィールドに値を指定せずにエンティティを挿入しようとすると、

  • type == "uuid"の場合、フィールドはランダムなUUIDを値として受け取ります。
  • type == "string"の場合、フィールドはランダムな文字列を受け入れます。
  • フィールド名がcreated_atまたはupdated_at である場合、このフィールドを適宜挿入または更新する際、現在時刻が入ります。
reference string タイプがforeignのフィールドには必須です。指定する文字列は、必ず既存スキーマの名前にし、外部キーはこの名前を「指す」ことになります。つまり、スキーマBにスキーマAを指す外部キーがある場合は、Bの前にAが読み込まれる必要があります。
on_delete string オプションで、foreignタイプのフィールド専用です。これは、参照されたエンティティが削除された場合に、外部キーによってリンクされたエンティティに何が起こるべきかを指示します。これには3つの潜在的な値があります:

  • "cascade": When the linked entity is deleted, all the dependent entities must also be deleted.
  • "null": When the linked entity is deleted, all the dependent entities will have their foreign key field set to null.
  • "restrict": Attempting to delete an entity with linked entities will result in an error.


In PostgreSQL, you must declare the references as ON DELETE CASCADE/NULL/RESTRICT in a migration.
スキーマの詳細については、以下を参照してください。 * [typedefs.lua](https://github.com/Kong/kong/blob/release/3.0.x/kong/db/schema/typedefs.lua)のソースコードで、デフォルトで何が提供されているかを把握します。 * [コアスキーマ](https://github.com/Kong/kong/tree/release/3.0.x/kong/db/schema/entities)では、ここで説明されていない他のフィールド属性の例を確認できます。 * [組み込みプラグイン用のすべての `daos.lua` ファイル](https://github.com/search?utf8=%E2%9C%93&q=repo%3Akong%2Fkong+path%3A%2Fkong%2Fplugins+filename%3Adaos.lua)、特にこのガイドで例として使用された[key\-auth ファイル](https://github.com/Kong/kong/blob/release/3.0.x/kong/plugins/key-auth/daos.lua)。 カスタムDAO ------- スキーマは、データベースとやり取りするために直接使用されるわけではありません。代わりに、有効なスキーマごとにDAOが構築されます。DAOはそれがラップするスキーマの名前を取り、 `kong.db`インターフェースを通じてアクセス可能です。 上記の例のスキーマでは、生成されたDAOは`kong.db.keyauth_credentials`経由のプラグインで利用可能になります。 ### エンティティを選択します ```lua local entity, err, err_t = kong.db.:select(primary_key) ``` データベース内のエンティティを見つけて返そうとします。次の3つのことが起こり得ます。 * エンティティが見つかりました。この場合、通常のLuaテーブルとして返されます。 * エラーが発生します。たとえば、データベースとの接続が失われるなどです。その場合、 最初に返される値は`nil`で、2番目はエラーを説明する文字列、 最後は表形式の同じエラーになります。 * エラーは発生しませんが、エンティティが見つかりません。その後、関数はエラーなしで`nil`を返します。 使用例: ```lua local entity, err = kong.db.keyauth_credentials:select({ id = "c77c50d2-5947-4904-9f37-fa36182a71a9" }) if err then kong.log.err("Error when inserting keyauth credential: " .. err) return nil end if not entity then kong.log.err("Could not find credential.") return nil end ``` ### すべてのエンティティを反復処理 ```lua for entity, err on kong.db.:each(entities_per_page) do if err then ... end ... end ``` このメソッドは、リクエストページ分割を行うことで、データベース内のすべてのエンティティを効率的に 反復処理します。`entities_per_page`パラメータ(`100`のデフォルト)は、 ページごとに返されるエンティティ数を制御します。 反復ごとに、新しい `entity` が返されます。エラーがある場合は、`err` 変数にエラーが格納されます。推奨する反復方法は、最初に `err` をチェックし、それ以外の場合は `entity` が存在すると仮定することです。 使用例: ```lua for credential, err on kong.db.keyauth_credentials:each(1000) do if err then kong.log.err("Error when iterating over keyauth credentials: " .. err) return nil end kong.log("id: " .. credential.id) end ``` この例では、認証情報を 1000 アイテムごとのページで繰り返し処理し、エラーが発生しない限り IDを記録します。 ### エンティティの挿入 ```lua local entity, err, err_t = kong.db.:insert() ``` データベースにエンティティを挿入し、挿入されたエンティティのコピー、または、`nil`、エラーメッセージ(文字列)とテーブルフォームのエラーを説明するテーブルを返します。 挿入が成功すると、返されるエンティティには、 `default`と`auto` によって提供される追加の値が含まれます。 次の例では、`keyauth_credentials` DAOを使用して、特定のコンシューマに認証情報を挿入し、`key`を`"secret"` に設定しています。外部キーの参照用構文に注目してください。 ```lua local entity, err = kong.db.keyauth_credentials:insert({ consumer = { id = "c77c50d2-5947-4904-9f37-fa36182a71a9" }, key = "secret", }) if not entity then kong.log.err("Error when inserting keyauth credential: " .. err) return nil end ``` 返されたエンティティ(エラーが発生しなかったと仮定して)には、`id`と`created_at`のような`auto`入力されたフィールドが含まれます。 ### エンティティを更新 ```lua local entity, err, err_t = kong.db.:update(primary_key, ) ``` 指定された主キーと値のセットを使用して既存のエンティティが見つかる場合に、そのエンティティを更新します。 返されるエンティティは、更新が行われた後のエンティティ、または `nil` \+ エラーメッセージ \+ エラーテーブルになります。 次の例では、認証情報の ID を指定して、既存の認証情報の `key` フィールドを変更します。 ```lua local entity, err = kong.db.keyauth_credentials:update( { id = "2b6a2022-770a-49df-874d-11e2bf2634f5" }, { key = "updated_secret" }, ) if not entity then kong.log.err("Error when updating keyauth credential: " .. err) return nil end ``` プライマリキーを指定するための構文が、外部キーを指定するために使用する構文と似ていることに注意してください。 ### エンティティのアップサート ```lua local entity, err, err_t = kong.db.:upsert(primary_key, ) ``` `upsert``insert`と`update`が混在している。 * 提供された`primary_key`既存のエンティティを識別すると、 `update`のように機能します。 * 提供された`primary_key`が既存のエンティティを識別しない場合は、次のように動作します。`insert` 次のコードがあるとします。 ```lua local entity, err = kong.db.keyauth_credentials:upsert( { id = "2b6a2022-770a-49df-874d-11e2bf2634f5" }, { consumer = { id = "a96145fb-d71e-4c88-8a5a-2c8b1947534c" } } ) if not entity then kong.log.err("Error when upserting keyauth credential: " .. err) return nil end ``` 次の 2 つのことが起こり得ます。 * IDが `2b6a2022-770a-49df-874d-11e2bf2634f5` の認証情報が存在する場合、このコードはそのコンシューマを指定されたものに設定しようとします。 * 認証情報が存在しない場合、このコードは、指定された id とコンシューマを使用して新しい認証情報の作成を試行します。 ### エンティティの削除 ```lua local ok, err, err_t = kong.db.:delete(primary_key) ``` `primary_key` で識別されるエンティティの削除を試行します。このメソッドを呼び出した後にエンティティが *存在しない* 場合は `true` を返し、エラーが検出された場合は `nil` \+ error \+ errorテーブルを返します。 `delete`の呼び出しは、 *呼び出す前に* エンティティが不在であれば、正常に実行されることに注意してください。 その理由はパフォーマンスにあり、削除前に読み込み操作を実行することをできるだけ回避するためです。 このチェックは手動で実行する必要があり、`delete`を呼び出す前に`select`を使用してチェックします。 例: ```lua local ok, err = kong.db.keyauth_credentials:delete({ id = "2b6a2022-770a-49df-874d-11e2bf2634f5" }) if not ok then kong.log.err("Error when deleting keyauth credential: " .. err) return nil end ``` カスタムエンティティのキャッシュ ---------------- リクエスト/応答ごとにカスタムエンティティが必要になることがあります。 その結果、データストアのクエリが毎回発生します。データストアをクエリするとレイテンシが増加し、リクエスト/応答が遅くなるため、これは非常に非効率的です。 結果、データストアの負荷が増加し、データストアのパフォーマンスそのものや、 ほかのKongノードにまで影響を及ぼす可能性があります。 すべてのリクエスト/レスポンスにカスタムエンティティが必要な場合は、 Kong が提供するメモリ内キャッシュ API を活用してメモリ内にキャッシュするのが良い方法です。 次の章では、カスタムエンティティのキャッシュと、それらがデータストアで変更された場合に無効にする方法について説明します:[カスタムエンティティのキャッシュ](/gateway/3.8.x/plugin-development/entities-cache/)。

前へ データストアへのアクセス
次へ カスタムエンティティのキャッシュ
Thank you for your feedback.
Was this page useful?
情報が多すぎる場合 close cta icon
Kong Konnectを使用すると、より多くの機能とより少ないインフラストラクチャを実現できます。月額1Mリクエストが無料。
無料でお試しください
  • Kong
    APIの世界を動かす

    APIマネジメント、サービスメッシュ、イングレスコントローラーの統合プラットフォームにより、開発者の生産性、セキュリティ、パフォーマンスを大幅に向上します。

    • 製品
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • 製品アップデート
      • 始める
    • ドキュメンテーション
      • Kong Konnectドキュメント
      • Kong Gatewayドキュメント
      • Kong Meshドキュメント
      • Kong Insomniaドキュメント
      • Kong Konnect Plugin Hub
    • オープンソース
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kongコミュニティ
    • 会社概要
      • Kongについて
      • お客様
      • キャリア
      • プレス
      • イベント
      • お問い合わせ
  • 利用規約• プライバシー• 信頼とコンプライアンス
© Kong Inc. 2025