クエリロールAPI

Query DSL を使用して、ページネーション 形式でロールを取得します。

リクエスト

GET /_security/_query/role

POST /_security/_query/role

前提条件

  • このAPIを使用するには、少なくとも read_security クラスター権限を持っている必要があります。

説明

ロール管理APIは、ファイルベースのロール管理 を使用するよりも、一般的にロールを管理するための推奨方法です。クエリロールAPIは、ロールファイルで定義されたロールや、組み込みのロールを取得しません。オプションでクエリを使用して結果をフィルタリングできます。また、結果はページネーションされ、ソートされることもあります。

リクエストボディ

リクエストボディに次のパラメータを指定できます：

  • query
  • (オプション、文字列) 返すロールをフィルタリングするためのクエリ。クエリは、match_all、bool、term、terms、match、ids、prefix、wildcard、exists、range、および simple query string を含むクエリタイプのサブセットをサポートします。
    ロールに関連する次の値をクエリできます。
    query の有効な値
    • name
    • (キーワード) ロールの名前。
    • description
    • (テキスト) ロールの説明。
    • metadata
    • (フラット化) ロール に関連するメタデータフィールド、例えば metadata.app_tag。メタデータは内部的にフラット化フィールドタイプとしてインデックスされます。これは、すべてのサブフィールドがクエリおよびソート時に keyword フィールドのように動作することを意味します。また、フィールド名パターンをサポートするクエリタイプに対しても、ワイルドカードパターンを使用してメタデータフィールドのサブセットを参照することはできません。最後に、metadata フィールドを単に言及することで、すべてのメタデータフィールドを一緒に検索できます（すなわち、ドットやサブフィールド名が続かない場合）。
    • applications
    • ロールが付与するアプリケーション権限のリスト。
      • application
      • (キーワード) 権限およびリソースに関連するアプリケーションの名前。
      • privileges
      • (キーワード) ロールが付与する権限の名前。
      • resources
      • (キーワード) 権限が適用されるリソース。
  • from
  • (オプション、整数) 開始ドキュメントオフセット。非負である必要があり、デフォルトは 0 です。
    デフォルトでは、from および size パラメータを使用して、10,000件を超えるヒットをページングすることはできません。より多くのヒットをページングするには、search_after パラメータを使用します。
  • size
  • (オプション、整数) 返すヒットの数。負であってはならず、デフォルトは 10 です。
    デフォルトでは、from および size パラメータを使用して、10,000件を超えるヒットをページングすることはできません。より多くのヒットをページングするには、search_after パラメータを使用します。
  • sort
  • (オプション、オブジェクト) ソート定義。username、roles または enabled でソートできます。さらに、_doc フィールドに対してインデックス順でソートを適用することもできます。
  • search_after
  • (オプション、配列) 検索後 定義。

レスポンスボディ

このAPIは、次のトップレベルフィールドを返します：

  • total
  • 見つかったロールの総数。
  • count
  • レスポンスで返されたロールの数。
  • roles
  • クエリに一致するロールのリスト。返されたロールの形式は、ロール定義形式の拡張です。transient_metadata.enabled および _sort フィールドが追加されます。ロールが自動的に無効化される場合、transient_metadata.enabled は false に設定されます。たとえば、ロールがインストールされたライセンスによって許可されていない権限を付与する場合です。検索クエリがいくつかのフィールドでソートされている場合、_sort が存在します。これは、ソートに使用された値の配列を含みます。

例

次のリクエストは、ロール名でソートされたすべてのロールをリストします：

Python

  1. resp = client.security.query_role(
  2.    sort=[
  3.    "name"
  4.    ],
  5. )
  6. print(resp)

Js

  1. const response = await client.security.queryRole({
  2.   sort: ["name"],
  3. });
  4. console.log(response);

コンソール

  1. POST /_security/_query/role
  2. {
  3.    "sort": ["name"]
  4. }

成功した呼び出しは、1つ以上のロールに対して取得された情報を含むJSON構造を返します：

コンソール-結果

  1. {
  2.    "total": 2,
  3.    "count": 2,
  4.    "roles": [
  5.    {
  6.    "name" : "my_admin_role",
  7.    "cluster" : [
  8.    "all"
  9.    ],
  10.    "indices" : [
  11.    {
  12.    "names" : [
  13.    "index1",
  14.    "index2"
  15.    ],
  16.    "privileges" : [
  17.    "all"
  18.    ],
  19.    "field_security" : {
  20.    "grant" : [
  21.    "title",
  22.    "body"
  23.    ]
  24.    },
  25.    "allow_restricted_indices" : false
  26.    }
  27.    ],
  28.    "applications" : [ ],
  29.    "run_as" : [
  30.    "other_user"
  31.    ],
  32.    "metadata" : {
  33.    "version" : 1
  34.    },
  35.    "transient_metadata" : {
  36.    "enabled" : true
  37.    },
  38.    "description" : "Grants full access to all management features within the cluster.",
  39.    "_sort" : [
  40.    "my_admin_role"
  41.    ]
  42.    },
  43.    {
  44.    "name" : "my_user_role",
  45.    "cluster" : [ ],
  46.    "indices" : [
  47.    {
  48.    "names" : [
  49.    "index1",
  50.    "index2"
  51.    ],
  52.    "privileges" : [
  53.    "all"
  54.    ],
  55.    "field_security" : {
  56.    "grant" : [
  57.    "title",
  58.    "body"
  59.    ]
  60.    },
  61.    "allow_restricted_indices" : false
  62.    }
  63.    ],
  64.    "applications" : [ ],
  65.    "run_as" : [ ],
  66.    "metadata" : {
  67.    "version" : 1
  68.    },
  69.    "transient_metadata" : {
  70.    "enabled" : true
  71.    },
  72.    "description" : "Grants user access to some indicies.",
  73.    "_sort" : [
  74.    "my_user_role"
  75.    ]
  76.    }
  77.    ]
  78. }
このリクエストのために取得されたロールのリスト

同様に、次のリクエストを使用して、説明に基づいてユーザーアクセスロールのみをクエリできます：

Python

  1. resp = client.security.query_role(
  2.    query={
  3.    "match": {
  4.    "description": {
  5.    "query": "user access"
  6.    }
  7.    }
  8.    },
  9.    size=1,
  10. )
  11. print(resp)

Js

  1. const response = await client.security.queryRole({
  2.   query: {
  3.    match: {
  4.    description: {
  5.    query: "user access",
  6.    },
  7.    },
  8.   },
  9.   size: 1,
  10. });
  11. console.log(response);

コンソール

  1. POST /_security/_query/role
  2. {
  3.   "query": {
  4.    "match": {
  5.    "description": {
  6.    "query": "user access"
  7.    }
  8.    }
  9.   },
  10.   "size": 1
  11. }
最も一致するロールのみを返します

コンソール-結果

  1. {
  2.    "total": 2,
  3.    "count": 1,
  4.    "roles": [
  5.    {
  6.    "name" : "my_user_role",
  7.    "cluster" : [ ],
  8.    "indices" : [
  9.    {
  10.    "names" : [
  11.    "index1",
  12.    "index2"
  13.    ],
  14.    "privileges" : [
  15.    "all"
  16.    ],
  17.    "field_security" : {
  18.    "grant" : [
  19.    "title",
  20.    "body"
  21.    ]
  22.    },
  23.    "allow_restricted_indices" : false
  24.    }
  25.    ],
  26.    "applications" : [ ],
  27.    "run_as" : [ ],
  28.    "metadata" : {
  29.    "version" : 1
  30.    },
  31.    "transient_metadata" : {
  32.    "enabled" : true
  33.    },
  34.    "description" : "Grants user access to some indicies."
  35.    }
  36.    ]
  37. }