一覧¶
GET /api/v1/workspace/inner_accesskey/list
概要¶
各ワークスペースでアクティブな inner sys のシステム Key をページング取得します。
呼び出し前の準備と使用手順¶
workspaceUUIDs を明示的に指定し、対象ワークスペースの組み込み認証情報を読み取り専用で確認することを推奨します。この Query パラメータは英語のカンマで連結された文字列であり、JSON 配列ではありません。各項目の前後の空白は除去され、空のセグメントは無視されます。省略した場合、または最終的に空になった場合は、本サービスのすべてのワークスペースにあるアクティブな inner sys Key を照会します。レコード id の降順で並び、デフォルトは pageIndex=1、pageSize=50 で、最大 100 です。search は実際には Access Key の平文の部分一致で検索し、名前や SK では検索しません。一覧は id を除く完全な Key エンティティを返し、AK/SK を含みますが、ロールや権限の概要は返しません。一致するものがない場合は空のリストを返し、ワークスペースが見つからないというエラーは報告しません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョン。省略して本ページのアルゴリズムを引き続き使用することはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用し、例の署名アルゴリズムと組み合わせます。 |
|
| X-Df-Access-Key | string | Y | 本モジュールの一覧では r または w 権限を使用できます。その他の 3 項目(GET 初期化を含む)はいずれも w 権限が必要です。 例: <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 秒文字列を生成します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| pageIndex | integer | デフォルトは 1、最小値は 1 です。 null を許可: False $minValue: 1 例: 1取得または入力方法: 最初は 1 とし、その後 content.pageInfo に従ってページ番号を進めます。 |
|
| pageSize | integer | デフォルトは 50、最大 100 です。 null を許可: False $maxValue: 100 $minValue: 1 例: 50取得または入力方法: クライアントの必要に応じて 1 から 100 の間で選択します。 |
|
| search | string | 任意。前後の空白を除去した後、AK の部分一致で検索します。省略または空白の場合はフィルタリングしません。name/SK では一致しません。 null を許可: False 例: known-ak-part取得または入力方法: 既存の組み込み Key 一覧レスポンスの ak、または安全に保存済みの Access Key からキーワードを取得します。 |
|
| workspaceUUIDs | commaArray | 任意の CSV 文字列。省略/空文字列/空のセグメントのみの場合は、すべてのワークスペースを照会します。単一のワークスペースでは角括弧を付けません。 null を許可: False 例: wksp_example001取得または入力方法: ワークスペース一覧から 1 つ以上のワークスペース uuid を取得し、英語のカンマで連結します。 |
パラメータ補足説明¶
サイトレベルの External API 認証情報を使用します。認証についてはExternal API 署名認証を参照してください。一覧では r または w 権限を許可します。その他の 3 項目(GET 初期化を含む)には w 権限が必要です。すべてのレスポンスで高権限の認証情報が平文で返される可能性があるため、通常のフロントエンドページのマスク表示ルールを適用しないでください。例ではプレースホルダー値を使用しています。実際の認証情報は安全に保管してください。
リクエスト例¶
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/inner_accesskey/list'
query = {'workspaceUUIDs': 'wksp_example001', 'pageIndex': 1, 'pageSize': 50}
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 | オブジェクト配列 | 本ページのアクティブなシステム Key。 |
| content.data[].uuid | string | API Key レコード UUID。呼び出し認証情報の ak/sk とは異なります。 |
| content.data[].status | integer | 組み込み Key のステータス。本モジュールの照会および削除では status=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 | 組み込み Key 名。初期化時は inner です。 |
| content.data[].ak | string | 組み込みシステム Access Key の平文。高権限の認証情報として保管してください。External 署名用の AK ではありません。 |
| content.data[].sk | string | 組み込みシステム Secret Key の平文。高権限の認証情報として保管してください。External 署名用の SK ではありません。 |
| content.data[].workspaceUUID | string | 所属ワークスペース UUID。 |
| content.data[].accountUUID | string | 紐付けられたアカウント識別子。初期化されたシステム Key では通常、空文字列です。 |
| content.data[].createdWay | string | 作成元。初期化時は通常 manual です。システム範囲は isSystem/businessType で区別します。 |
| content.data[].businessType | string | 本モジュールは inner sys タイプのみを管理します。 |
| content.data[].isSystem | integer | 本モジュールはシステム組み込み Key のみを管理し、初期化時は 1 です。 |
| content.data[].isOwnerRole | integer | 初期化時は 1 で、Owner ロールの意味を持ちます。通常の手動 Owner Key とは別に管理されます。 |
| content.data[].remark | string | 既存の備考。本モジュールには備考を変更するリクエストパラメータはありません。 |
| 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": [
{
"uuid": "wsak_inner_example001",
"status": 0,
"creator": "external",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "inner",
"ak": "<inner-access-key>",
"sk": "<inner-secret-key>",
"workspaceUUID": "wksp_example001",
"accountUUID": "",
"createdWay": "manual",
"businessType": "inner sys",
"isSystem": 1,
"isOwnerRole": 1,
"remark": "",
"isBurnAfterReading": 0,
"callCount": 0,
"lastCallAt": -1
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 50,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
一致する Key がない場合:
{
"code": 200,
"content": {
"data": [],
"pageInfo": {
"pageIndex": 1,
"pageSize": 50,
"count": 0,
"totalCount": 0
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。
パラメータが宣言に適合しない場合は共通リクエストエラーを返します。データベース、キャッシュなどの通常の内部例外は最終的に 500 ft.InternalServerError に統一されます。書き込みリクエストの失敗後は、まず永続状態とキャッシュを確認してください。すべてが反映されていないことは保証されません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュの失効、または明示的に処理されていない内部例外 | 内部エラー | traceId を保存し、まず Key の現在の状態と実際の呼び出し結果を確認してから再試行を決定してください。データベースはすでにコミットされている可能性があるため、エラーレスポンスだけで変更がないと判断できません。 |