初期化して取得¶
GET /api/v1/workspace/inner_accesskey/{workspace_uuid}/get
概要¶
ワークスペースの組み込み Owner システムキーを取得します。存在しない場合は自動で初期化します。
呼び出し前の準備と使用手順¶
メソッドは GET ですが、この API は w 権限を必要とし、Key を作成する可能性があるため、読み取り専用の確認として使用できません。まずワークスペース一覧からアクティブなワークスペースを選択します。アクティブな inner sys Key が既に存在する場合は、既存の認証情報を返します。存在しない場合は、名前 inner、isSystem=1、isOwnerRole=1 のシステムキーを作成してから、平文の AK/SK を返します。参照のみで初期化を許可しない場合は、組み込みKey一覧を使用してください。この API は既存の認証情報を更新せず、成功レスポンスは固定の10フィールドのみを返し、ロール/権限の詳細や完全なエンティティは含みません。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| workspace_uuid | string | Y | ワークスペースUUID。API Key レコードのUUIDや平文の AK/SK ではありません。 例: wksp_example001取得または入力方法: ワークスペース一覧の content.data[].uuid から取得し、サイトとアクティブ状態を確認します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 秒文字列を生成します。 |
パラメータの補足説明¶
サイトレベルの 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/wksp_example001/get'
query = {}
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.uuid | string | API Key レコードのUUID。呼び出し認証情報の ak/sk とは異なります。 |
| content.createAt | integer | 作成日時のUnix秒。 |
| content.updateAt | integer | 更新日時のUnix秒。未変更の場合は通常 -1 です。 |
| content.name | string | 組み込みKeyの名前。初期化時は inner です。 |
| content.ak | string | 組み込みシステムのAccess Key(平文)。高権限の認証情報として保管してください。External署名用のAKではありません。 |
| content.sk | string | 組み込みシステムのSecret Key(平文)。高権限の認証情報として保管してください。External署名用のSKではありません。 |
| content.workspaceUUID | string | 所属ワークスペースのUUID。 |
| content.businessType | string | このモジュールは inner sys タイプのみを管理します。 |
| content.isSystem | integer | このモジュールはシステムの組み込みKeyのみを管理し、初期化時は 1 です。 |
| content.isOwnerRole | integer | 初期化時は 1 で、Owner ロールの意味を持ちます。通常の手動作成の Owner Key とは別に管理されます。 |
{
"code": 200,
"content": {
"uuid": "wsak_inner_example001",
"ak": "<inner-access-key>",
"sk": "<inner-secret-key>",
"name": "inner",
"businessType": "inner sys",
"workspaceUUID": "wksp_example001",
"isSystem": 1,
"isOwnerRole": 1,
"createAt": 1785427200,
"updateAt": -1
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。
パラメータが宣言と一致しない場合は共通リクエストエラーを返します。データベース、キャッシュなどの通常の内部例外は、最終的に 500 ft.InternalServerError に統一されます。書き込みリクエストが失敗した後は、まず永続状態とキャッシュを確認してください。すべてが反映されていないことを保証するものではありません。
| HTTPステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反しています | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、および値を確認してください。 |
| 401 | ft.WKSPNotExistOrReleased | 対象ワークスペースが存在しない、またはアクティブ status=0 ではありません | ワークスペースが存在しません/または解放済みです | ワークスペース一覧からアクティブなワークスペースを選択してください。このAPIを使って削除済みワークスペースのKeyを作成することはできません。 |
| 500 | ft.InternalServerError | データベース、キャッシュの障害、または明示的に処理されていない内部例外 | 内部エラー | traceId を保存し、まず Key の現在の状態と実際の呼び出し結果を確認してから再試行を判断してください。データベースではすでにコミットされている可能性があるため、エラー応答だけで変更がないと判断することはできません。 |