APIキーの更新（Update API key）

APIキーの更新API

リクエスト

PUT /_security/api_key/<id>

前提条件

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

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

説明

このAPIを使用して、APIキーの作成またはAPIキーの付与APIによって作成されたAPIキーを更新します。多くのAPIキーに同じ更新を適用する必要がある場合は、バルク更新APIキーを使用してオーバーヘッドを削減できます。

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

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

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

パスパラメータ

• id
• （必須、文字列）更新するAPIキーのID。

リクエストボディ

リクエストボディには、以下のパラメータを指定できます。これはオプションです。

• role_descriptors
• （オプション、オブジェクト）このAPIキーに割り当てるロール記述子。APIキーの有効な権限は、割り当てられた権限と所有者ユーザーの権限のスナップショットの交差点です。このパラメータで新しい権限を指定することで、権限を追加できます。割り当てられた権限を削除するには、空のrole_descriptorsパラメータ、つまり空のオブジェクト{}を提供できます。APIキーに割り当てられた権限がない場合、所有者ユーザーの完全な権限を継承します。role_descriptorsパラメータを提供するかどうかにかかわらず、所有者の権限のスナップショットは常に更新されます。ロール記述子の構造は、APIキーの作成APIのリクエストと同じです。
• metadata
• （オプション、オブジェクト）APIキーに関連付けたい任意のメタデータ。ネストされたデータ構造をサポートしています。metadataオブジェクト内では、_で始まるトップレベルキーはシステム使用のために予約されています。指定された場合、これは以前にAPIキーに関連付けられたメタデータを完全に置き換えます。
• expiration
• （オプション、文字列）APIキーの有効期限。デフォルトでは、APIキーは期限切れになりません。変更しない場合は省略できます。

レスポンスボディ

• updated
• （boolean）trueの場合、APIキーが更新されました。falseの場合、変更が検出されなかったため、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キー情報を提供するJSON構造を返します。例えば:

コンソール-結果

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

以下の例では、所有者ユーザーの権限は次のようになります:

Js

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

次の例では、上記で作成したAPIキーを更新し、新しいロール記述子とメタデータを割り当てます:

Python

resp = client.security.update_api_key(
   id="VuaCfGcBCdbkQm-e5aOx",
   role_descriptors={
   "role-a": {
   "indices": [
   {
   "names": [
   "*"
   ],
   "privileges": [
   "write"
   ]
   }
   ]
   }
   },
   metadata={
   "environment": {
   "level": 2,
   "trusted": True,
   "tags": [
   "production"
   ]
   }
   },
)
print(resp)

Js

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

コンソール

PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
{
  "role_descriptors": {
   "role-a": {
   "indices": [
   {
   "names": ["*"],
   "privileges": ["write"]
   }
   ]
   }
  },
  "metadata": {
   "environment": {
   "level": 2,
   "trusted": true,
   "tags": ["production"]
   }
  }
}

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

コンソール-結果

{
  "updated": true
}

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

Js

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

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

Python

resp = client.security.update_api_key(
   id="VuaCfGcBCdbkQm-e5aOx",
   role_descriptors={},
)
print(resp)

Js

const response = await client.security.updateApiKey({
  id: "VuaCfGcBCdbkQm-e5aOx",
  role_descriptors: {},
});
console.log(response);

コンソール

PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
{
  "role_descriptors": {}
}

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

コンソール-結果

{
  "updated": true
}

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

Js

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

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

Js

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

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

Python

resp = client.security.update_api_key(
   id="VuaCfGcBCdbkQm-e5aOx",
)
print(resp)

Js

const response = await client.security.updateApiKey({
  id: "VuaCfGcBCdbkQm-e5aOx",
});
console.log(response);

コンソール

PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx

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

コンソール-結果

{
  "updated": true
}

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

Js

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