APIキーの一括更新（Bulk update API keys）

バルク更新APIキーAPI

リクエスト

POST /_security/api_key/_bulk_update

前提条件

• このAPIを使用するには、少なくともmanage_own_api_keyクラスターの権限が必要です。ユーザーは、自分が作成したAPIキーまたは自分に付与されたAPIキーのみを更新できます。他のユーザーのAPIキーを更新するには、run_as機能を使用して、他のユーザーの代理としてリクエストを送信してください。

このAPIの認証資格情報としてAPIキーを使用することはできません。APIキーを更新するには、所有者ユーザーの資格情報が必要です。

説明

このAPIは、単一APIキーの更新に似ていますが、1回のAPI呼び出しで複数のAPIキーに同じ更新を適用できます。この操作は、個別の更新を行うよりもパフォーマンスを大幅に向上させることができます。

期限切れのAPIキーや無効化されたAPIキーを更新することはできません。

このAPIは、APIキーのアクセススコープ、メタデータ、および有効期限の更新をサポートしています。各APIキーのアクセススコープは、リクエストで指定したrole_descriptorsと、リクエスト時の所有者ユーザーの権限のスナップショットから派生します。所有者の権限のスナップショットは、すべての呼び出しで自動的に更新されます。

リクエストでrole_descriptorsを指定しない場合でも、このAPIへの呼び出しはAPIキーのアクセススコープを変更する可能性があります。この変更は、APIキーが作成されたり最後に変更されたりしてから、所有者ユーザーの権限が変更された場合に発生する可能性があります。

リクエストボディ

リクエストボディで以下のパラメータを指定できます。

• ids

• （必須、リスト）更新するAPIキーのID。

• role_descriptors
• （オプション、オブジェクト）APIキーに割り当てるロール記述子。APIキーの有効な権限は、割り当てられた特権と所有者ユーザーの権限の時点スナップショットの交差点です。このパラメータで新しい特権を指定することで、特権を割り当てることができます。割り当てられた特権を削除するには、role_descriptorsパラメータを空のオブジェクト{}として提供します。APIキーに割り当てられた特権がない場合、所有者ユーザーの完全な権限を継承します。role_descriptorsパラメータを提供するかどうかにかかわらず、所有者の権限のスナップショットは常に更新されます。ロール記述子の構造は、APIキー作成APIのリクエストと同じです。
• metadata
• （オプション、オブジェクト）APIキーに関連付ける任意のネストされたメタデータ。

-   `````expiration

• （オプション、文字列）APIキーの有効期限。デフォルトでは、APIキーは期限切れになりません。変更を加えずに省略できます。

レスポンスボディ

成功したリクエストは、更新されたすべてのAPIキーのID、要求された変更がすでに適用されていて更新を必要としなかったAPIキーのID、および失敗した更新のエラー詳細を含むJSON構造を返します。

例

以下の例では、ユーザーが2つのAPIキーを作成することを前提とします。ユーザーは最初のAPIキーを作成します:

Python

resp = client.security.create_api_key(
   name="my-api-key",
   role_descriptors={
   "role-a": {
   "cluster": [
   "all"
   ],
   "indices": [
   {
   "names": [
   "index-a*"
   ],
   "privileges": [
   "read"
   ]
   }
   ]
   }
   },
   metadata={
   "application": "my-application",
   "environment": {
   "level": 1,
   "trusted": True,
   "tags": [
   "dev",
   "staging"
   ]
   }
   },
)
print(resp)

Js

const response = await client.security.createApiKey({
  name: "my-api-key",
  role_descriptors: {
   "role-a": {
   cluster: ["all"],
   indices: [
   {
   names: ["index-a*"],
   privileges: ["read"],
   },
   ],
   },
  },
  metadata: {
   application: "my-application",
   environment: {
   level: 1,
   trusted: true,
   tags: ["dev", "staging"],
   },
  },
});
console.log(response);

コンソール

POST /_security/api_key
{
  "name": "my-api-key",
  "role_descriptors": {
   "role-a": {
   "cluster": ["all"],
   "indices": [
   {
   "names": ["index-a*"],
   "privileges": ["read"]
   }
   ]
   }
  },
  "metadata": {
   "application": "my-application",
   "environment": {
   "level": 1,
   "trusted": true,
   "tags": ["dev", "staging"]
   }
  }
}

これにより、次のAPIキー情報を含むレスポンスが得られます。

コンソール-結果

{
  "id": "VuaCfGcBCdbkQm-e5aOx",
  "name": "my-api-key",
  "api_key": "ui2lp2axTNmsyakw9tvNnw",
  "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}

ユーザーは2番目のAPIキーを作成します:

Python

resp = client.security.create_api_key(
   name="my-other-api-key",
   metadata={
   "application": "my-application",
   "environment": {
   "level": 2,
   "trusted": True,
   "tags": [
   "dev",
   "staging"
   ]
   }
   },
)
print(resp)

Js

const response = await client.security.createApiKey({
  name: "my-other-api-key",
  metadata: {
   application: "my-application",
   environment: {
   level: 2,
   trusted: true,
   tags: ["dev", "staging"],
   },
  },
});
console.log(response);

コンソール

POST /_security/api_key
{
  "name": "my-other-api-key",
  "metadata": {
   "application": "my-application",
   "environment": {
   "level": 2,
   "trusted": true,
   "tags": ["dev", "staging"]
   }
  }
}

次のAPIキー情報が得られます。

コンソール-結果

{
  "id": "H3_AhoIBA9hmeQJdg7ij",
  "name": "my-other-api-key",
  "api_key": "134G4ilmT_uGWXHRfJfXXA",
  "encoded": "SDNfQWhvSUJBOWhtZVFKZGc3aWo6MTM0RzRpbG1UX3VHV1hIUmZKZlhYQQ=="
}

さらに、所有者ユーザーの権限は次のとおりです:

Js

{
  "cluster": ["all"],
  "indices": [
   {
   "names": ["*"],
   "privileges": ["all"]
   }
  ]
}

次の例では、上記で作成されたAPIキーを更新し、新しいロール記述子、メタデータを割り当て、有効期限を更新します。

Python

resp = client.security.bulk_update_api_keys(
   body={
   "ids": [
   "VuaCfGcBCdbkQm-e5aOx",
   "H3_AhoIBA9hmeQJdg7ij"
   ],
   "role_descriptors": {
   "role-a": {
   "indices": [
   {
   "names": [
   "*"
   ],
   "privileges": [
   "write"
   ]
   }
   ]
   }
   },
   "metadata": {
   "environment": {
   "level": 2,
   "trusted": True,
   "tags": [
   "production"
   ]
   }
   },
   "expiration": "30d"
   },
)
print(resp)

Js

const response = await client.security.bulkUpdateApiKeys({
  body: {
   ids: ["VuaCfGcBCdbkQm-e5aOx", "H3_AhoIBA9hmeQJdg7ij"],
   role_descriptors: {
   "role-a": {
   indices: [
   {
   names: ["*"],
   privileges: ["write"],
   },
   ],
   },
   },
   metadata: {
   environment: {
   level: 2,
   trusted: true,
   tags: ["production"],
   },
   },
   expiration: "30d",
  },
});
console.log(response);

コンソール

POST /_security/api_key/_bulk_update
{
  "ids": [
   "VuaCfGcBCdbkQm-e5aOx",
   "H3_AhoIBA9hmeQJdg7ij"
  ],
  "role_descriptors": {
   "role-a": {
   "indices": [
   {
   "names": ["*"],
   "privileges": ["write"]
   }
   ]
   }
  },
  "metadata": {
   "environment": {
   "level": 2,
   "trusted": true,
   "tags": ["production"]
   }
  },
  "expiration": "30d"
}

成功した呼び出しは、APIキーが更新されたことを示すJSON構造を返します:

コンソール-結果

{
  "updated": [
   "VuaCfGcBCdbkQm-e5aOx",
   "H3_AhoIBA9hmeQJdg7ij"
  ],
  "noops": []
}

更新後の両方のAPIキーの有効な権限は、提供されたロール記述子と所有者ユーザーの権限の交差点になります:

Js

{
  "indices": [
   {
   "names": ["*"],
   "privileges": ["write"]
   }
  ]
}

次の例では、APIキーに以前割り当てられた権限を削除し、所有者ユーザーの完全な権限を継承させます。

Python

resp = client.security.bulk_update_api_keys(
   body={
   "ids": [
   "VuaCfGcBCdbkQm-e5aOx",
   "H3_AhoIBA9hmeQJdg7ij"
   ],
   "role_descriptors": {}
   },
)
print(resp)

Js

const response = await client.security.bulkUpdateApiKeys({
  body: {
   ids: ["VuaCfGcBCdbkQm-e5aOx", "H3_AhoIBA9hmeQJdg7ij"],
   role_descriptors: {},
  },
});
console.log(response);

コンソール

POST /_security/api_key/_bulk_update
{
  "ids": [
   "VuaCfGcBCdbkQm-e5aOx",
   "H3_AhoIBA9hmeQJdg7ij"
  ],
  "role_descriptors": {}
}

次のレスポンスが返されます:

コンソール-結果

{
  "updated": [
   "VuaCfGcBCdbkQm-e5aOx",
   "H3_AhoIBA9hmeQJdg7ij"
  ],
  "noops": []
}

更新後のAPIキーの有効な権限は、所有者ユーザーの権限と同じになります:

Js

{
  "cluster": ["all"],
  "indices": [
   {
   "names": ["*"],
   "privileges": ["all"]
   }
  ]
}

次の例では、所有者ユーザーの権限が元の権限から次のように変更されたと仮定します:

Js

{
  "cluster": ["manage_security"],
  "indices": [
   {
   "names": ["*"],
   "privileges": ["read"]
   }
  ]
}

次のリクエストは、2つのAPIキーに関連付けられたユーザーの権限のスナップショットを自動的に更新します。

Python

resp = client.security.bulk_update_api_keys(
   body={
   "ids": [
   "VuaCfGcBCdbkQm-e5aOx",
   "H3_AhoIBA9hmeQJdg7ij"
   ]
   },
)
print(resp)

Js

const response = await client.security.bulkUpdateApiKeys({
  body: {
   ids: ["VuaCfGcBCdbkQm-e5aOx", "H3_AhoIBA9hmeQJdg7ij"],
  },
});
console.log(response);

コンソール

POST /_security/api_key/_bulk_update
{
  "ids": [
   "VuaCfGcBCdbkQm-e5aOx",
   "H3_AhoIBA9hmeQJdg7ij"
  ]
}

次のレスポンスが返されます:

コンソール-結果

{
  "updated": [
   "VuaCfGcBCdbkQm-e5aOx",
   "H3_AhoIBA9hmeQJdg7ij"
  ],
  "noops": []
}

両方のAPIキーの有効な権限は次のようになります:

Js

{
  "cluster": ["manage_security"],
  "indices": [
   {
   "names": ["*"],
   "privileges": ["read"]
   }
  ]
}

APIキーの更新に失敗した場合、エラー詳細はerrorsフィールドに含まれます。例えば:

Js

{
  "updated": ["VuaCfGcBCdbkQm-e5aOx"],
  "noops": [],
  "errors": {
   "count": 3,
   "details": {
   "g_PqP4IBcBaEQdwM5-WI": {
   "type": "resource_not_found_exception",
   "reason": "no API key owned by requesting user found for ID [g_PqP4IBcBaEQdwM5-WI]"
   },
   "OM4cg4IBGgpHBfLerY4B": {
   "type": "illegal_argument_exception",
   "reason": "cannot update invalidated API key [OM4cg4IBGgpHBfLerY4B]"
   },
   "Os4gg4IBGgpHBfLe2I7j": {
   "type": "exception",
   "reason": "bulk request execution failure",
   "caused_by": {
   "type" : "version_conflict_engine_exception",
   "reason" : "[1]: version conflict, required seqNo [1], primary term [1]. current document has seqNo [2] and primary term [1]"
   }
   }
   }
  }
}