一覧取得¶
GET /api/v1/workspace/accesskey/list
概要¶
削除されておらず有効な手動ワークスペース API キーをページ単位で一覧表示します。
呼び出し前の準備と使用手順¶
r または w 権限の External 認証情報が必要です。workspaceUUID は常に指定し、確認済みの対象ワークスペースのみを参照することを推奨します。省略または空文字列の場合は、本サービスの条件に一致するすべてのキーをワークスペース横断で検索し、平文の AK/SK を返します。自動的に特定のログインワークスペースに制限されるわけではありません。status=0、非システム、かつ accountUUID が空のキーのみを返し、個人/Agent に紐づくキーは一覧に表示されません。id の降順で、pageIndex のデフォルトは 1、pageSize のデフォルトは 20 です。検索はキー名のみに一致し、前後の空白は除去されます。一覧はエンティティフィールドを直接返し、ロール、権限、creatorInfo は含みません。有効な権限が必要な場合は、各項目の詳細を呼び出してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョンです。省略したまま本ページのアルゴリズムを使用し続けることはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用し、例の署名アルゴリズムと組み合わせます。 |
|
| X-Df-Access-Key | string | Y | 本モジュールの一覧では r または w 権限を利用できます。その他のインターフェース(GET 詳細を含む)には w 権限の External 認証情報が必要です。 例: <external-access-key>取得または入力方法: サイト管理者が External API AK を割り当てます。ワークスペース OpenAPI Key は使用できません。 |
| X-Df-Nonce | string | Y | 一時的なシリアル番号です。失敗して再送する場合も新しい値を生成し、署名を再計算します。 例: 97d275ee9f774315a7885ba7347acbd9取得または入力方法: リクエストごとに uuid.uuid4().hex を再生成します。 |
| X-Df-Signature | string | Y | 大文字化したメソッド、nonce、元の完全なパス、timestamp、元の UTF-8 リクエストボディをスペースで連結し、HMAC-SHA256 を適用して hex ダイジェストを取得します。 例: <hmac-sha256-hex>取得または入力方法: External API 署名認証 に従い、対応する SK で計算します。完全な実行可能テンプレートは以下を参照してください。 |
| X-Df-Timestamp | string | Y | サイトに設定された署名有効時間枠内である必要があり、例の時刻を再利用できません。 例: 1785427200取得または入力方法: 送信時に str(int(time.time())) で現在の Unix 秒文字列を生成します。 |
クエリリクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| pageIndex | integer | デフォルトは 1、最小値は 1。 null を許可: False $minValue: 1 例: 1取得または入力方法: 1 から開始し、content.pageInfo.totalCount に従って後続ページへ進みます。 |
|
| pageSize | integer | デフォルトは 20、最大値は 100。 null を許可: False $maxValue: 100 $minValue: 1 例: 20取得または入力方法: クライアントの必要に応じて 1 から 100 の範囲で選択します。 |
|
| search | string | 任意。名前の包含一致で検索します。省略または空白の場合はフィルタしません。 null を許可: False 例: 示例取得または入力方法: 既知の API キー名に含まれるキーワードを入力します。 |
|
| workspaceUUID | string | 任意のワークスペース UUID。省略または空文字列の場合はすべてのワークスペースを検索し、特定のワークスペースを自動選択しません。明示的に指定することを推奨します。 null を許可: False 例: wksp_example001取得または入力方法: ワークスペース一覧 の content.data[].uuid から取得し、ワークスペース名と状態を確認します。 |
パラメータ補足¶
サイトレベルの External API AK/SK を使用します。署名方式は External API 署名認証 を参照してください。本ページで生成するワークスペース API キーと External 署名認証情報は同じ認証情報セットではありません。External は現在、AK/SK を平文で返し、フロントエンド画面のマスキングポリシーを適用しません。レスポンス例はすべてプレースホルダー値を使用しているため、実際のレスポンスは認証情報として適切に保管してください。一覧が読み取るのは永続化済みの呼び出し統計です。フロントエンド一覧のように更新待ちの統計キャッシュをマージするフローはないため、統計に遅延が生じる場合があります。
リクエスト例¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 対象サイトのアドレスおよび管理者が割り当てた External API AK/SK に置き換えます。
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'GET'
path = '/api/v1/workspace/accesskey/list'
query = {'workspaceUUID': 'wksp_example001', 'pageIndex': 1, 'pageSize': 20}
data = None
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
レスポンス¶
HTTP 200。application/json の共通レスポンスエンベロープで、業務結果は content にあります。External は declaration を自動的に付加せず、一覧のページネーション情報は content.pageInfo にあります。
| フィールド | 型 | 説明 |
|---|---|---|
| content.data | オブジェクト配列 | 現在のページのキー。結果が空の場合は []。 |
| content.data[].id | integer または null | 内部レコード番号。API 呼び出しでは uuid を使用します。作成スナップショットは flush 前に取得されるため、このフィールドは null になる場合があります。 |
| content.data[].uuid | string | API キーレコードの UUID。呼び出し認証情報の ak/sk とは異なります。 |
| content.data[].status | integer | キーの状態: 0 有効、2 無効、3 削除済み。一覧/詳細は 0 のみを返します。削除操作は、未削除の無効なキーも処理できます。 |
| content.data[].creator | string | 作成元の識別子。External による作成では通常 external です。 |
| content.data[].updator | string | 更新元の識別子。未変更の場合は空になることがあります。 |
| content.data[].createAt | integer | 作成 Unix 秒。 |
| content.data[].deleteAt | integer | 削除 Unix 秒。未削除の場合は通常 -1 です。 |
| content.data[].updateAt | integer | 更新 Unix 秒。まだ変更されていない場合は通常 -1 です。 |
| content.data[].name | string | API キーの表示名。 |
| content.data[].ak | string | ワークスペース Access Key の呼び出し認証情報(平文)。このワークスペースの OpenAPI 認証に使用できますが、本 External リクエストの X-Df-Access-Key ではありません。 |
| content.data[].sk | string | ワークスペース Secret Key の平文。機密認証情報として保存する必要があります。本 External リクエストに対応する SK ではありません。 |
| content.data[].workspaceUUID | string | 所属ワークスペースの UUID。 |
| content.data[].accountUUID | string | 紐づくアカウントの UUID。手動ワークスペースキーでは空文字列です。アカウントに紐づくキーの有効な権限は、アカウントのロールに基づいて確認する必要があります。 |
| content.data[].createdWay | string | 作成元の識別子。例: manual、user、agent。一覧では accountUUID が空でないすべてのキーを除外します。 |
| content.data[].businessType | string | システムの業務タイプ識別子。手動キーでは通常空です。 |
| content.data[].isSystem | integer | システム組み込みキーかどうか。本モジュールのクエリ/操作ではシステムキーを除外します。 |
| content.data[].isOwnerRole | integer | Owner 専用キーかどうか。1 ははい、0 はいいえ。同一ワークスペース内で未削除の Owner キーは最大 1 件です。 |
| content.data[].remark | string | 既存の備考。本 External の公開追加/変更パラメータには remark は含まれません。 |
| content.data[].isBurnAfterReading | integer | 保持されている閲覧後消去フラグ。本モジュールでは読み取り後の破棄を実行しないため、認証情報の失効に依存しないでください。 |
| content.data[].callCount | integer または null | 永続的な累計呼び出し回数。非同期統計であり、リアルタイムのカウントではありません。作成スナップショットは flush 前に null になる場合があります。 |
| content.data[].lastCallAt | integer または null | 最終呼び出しの Unix 秒。通常 -1 は記録なしを意味します。作成スナップショットでは null になる場合があります。 |
| content.pageInfo.pageIndex | integer | 現在のページ番号。 |
| content.pageInfo.pageSize | integer | 1 ページあたりの件数。 |
| content.pageInfo.count | integer | 本ページの件数。 |
| content.pageInfo.totalCount | integer | フィルタ条件に一致する総件数。 |
{
"code": 200,
"content": {
"data": [
{
"id": 1001,
"uuid": "wsak_example001",
"status": 0,
"creator": "external",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例只读API Key",
"ak": "<workspace-api-key>",
"sk": "<workspace-secret-key>",
"workspaceUUID": "wksp_example001",
"accountUUID": "",
"createdWay": "manual",
"businessType": "",
"isSystem": 0,
"isOwnerRole": 0,
"remark": "",
"isBurnAfterReading": 0,
"callCount": 0,
"lastCallAt": -1
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 20,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
一致するキーがない場合:
{
"code": 200,
"content": {
"data": [],
"pageInfo": {
"pageIndex": 1,
"pageSize": 20,
"count": 0,
"totalCount": 0
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーの詳細は 共通エラー定義 を参照してください。
以下の表は確認済みのリクエストおよび業務分岐を示します。通常のデータベース/キャッシュ/監査の 5xx は、グローバルに ft.InternalServerError としてラップされます。書き込みインターフェースがエラーを返した場合、名前、Owner フラグ、ロール、削除状態がすでに保存されている可能性があるため、まず現在の状態を照会してから次の操作を決定する必要があります。
| HTTP ステータス | errorCode | トリガー条件 | メッセージまたはレスポンス説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ失効、監査、または未処理のフィールド例外 | 内部エラー | traceId を保持し、キーの現在の名前、ロール、状態を確認してください。データは先にコミットされてから失敗する可能性があるため、500 のみで未反映と判断できません。 |