ワークスペース

現在の Workspace を更新

Workspace の name と status を更新します。両方とも必須です。status は active / inactive で、inactive では全 API キーが認証できません。metadata を省略すると現値を保持し、metadata={} でクリアします。null は指定できません。 is_beta は既定で無効な読み取り専用フラグです。利用申請はプラットフォームへ。PATCH や metadata では変更できません。

PATCHhttps://api.unifyport.ai/v1/workspace

対応チャネル

all

呼び出す前に

対象ワークスペースの X-Api-Key をサーバー側で使用します。実行前にすべてのプレースホルダーを置き換えます。

リクエスト

curl -X PATCH "https://api.unifyport.ai/v1/workspace" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production Workspace",
  "status": "active",
  "metadata": {
    "region": "global",
    "env": "production"
  }
}'

リクエストパラメータ

ヘッダー

X-Api-Key

string必須

ワークスペース API キー。このヘッダーからワークスペースを特定します。

Content-Type

string必須

JSON のリクエストボディを送る場合は application/json を使用します。

リクエストボディ

name

string必須

Workspace の表示名。

minLength: 1

status

string必須

Workspace の状態: active または inactive。inactive ではすべての API キーが認証できません。

enum: active, inactive

metadata

object

Workspace メタデータ。PATCH では省略で保持、{} でクリアします。null は無効です。

結果の確認

この API に記載された応答項目と HTTP 状態で結果を判断し、関連操作から次の手順を選びます。

レスポンス 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "name": "Production Workspace",
    "status": "active",
    "metadata": {
      "region": "global",
      "env": "production"
    },
    "account_quota": 10,
    "account_quota_used": 1,
    "account_quota_unlimited": false,
    "is_beta": false
  }
}

レスポンスボディ

is_beta

boolean

is_beta は既定で無効な読み取り専用フラグです。利用申請はプラットフォームへ。PATCH や metadata では変更できません。

name

string

Workspace の表示名。

status

string

Workspace の状態: active または inactive。inactive では全 API キーが認証できません。

enum: active, inactive

metadata

object

Workspace に保存された自分の環境ラベル。

account_quota

integer

現在有効な読み取り専用のアカウント総容量。無料枠と有効期限内の有料枠を含み、使用済み数は差し引きません。期限切れの有料枠は含まれません。

format: uint64

account_quota_used

integer

現在使用中の読み取り専用アカウント枠数。アカウントの作成で消費し、削除で解放します。認証待ち、停止中、切断中のアカウントも含みます。有料枠の期限切れ後は使用数が account_quota を超える場合がありますが、実際の使用数を返します。

format: uint64

account_quota_unlimited

boolean

互換性のために残されている読み取り専用フィールド。現在のクォータモードでは常に false を返します。アカウント容量は account_quota を参照してください。

レスポンス

200

200 OK

リクエスト成功。レスポンスボディの例を参照してください。

400

Bad Request

リクエストボディ、パス、またはパラメータが不正です。

401

Unauthorized

X-Api-Key ヘッダが欠落しているか無効です。

403

Forbidden

リクエストは識別されましたが、この操作は許可されていません。

404

Not Found

要求されたリソースが見つかりません。error.code と現在の操作を合わせて確認してください。

500

Internal Server Error

サービスで予期しないエラーが発生しました。

失敗時の対応

HTTP 状態と error.code/numeric_code を確認し、request_id を保存します。原因に応じてパラメーター修正・認証・状態確認を行い、送信や書き込みの再試行前に前回の結果を確認します。エラーリファレンス

HTTP ステータス、error.code、error.numeric_code を現在の操作と合わせて確認します。数値コードは文字列です。request_id は調査用で、冪等性キーやタスク ID ではありません。

invalid_request · 10000 · 400

JSON 本文と必須項目を確認してください。

対処と再試行: 操作とチャネルの条件に従ってパラメーターを修正してから再実行します。同じ無効なリクエストを繰り返しても解決しません。

JSON の例です。message は実際の原因によって変わります · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

invalid_target_workspace · 11003 · 400

上書き対象のワークスペースが空、または形式が無効です。上書き用ヘッダーを削除し、対象ワークスペースの API Key を使用してください。

発生条件: ワークスペースを上書きする X-Workspace-Id リクエストヘッダーを送った場合に適用されます。

対処と再試行: 操作とチャネルの条件に従ってパラメーターを修正してから再実行します。同じ無効なリクエストを繰り返しても解決しません。

JSON の例です。message は実際の原因によって変わります · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

update_workspace_failed · 41001 · 400

操作が拒否されました。リクエストを確認し、request_id を保存してください。

対処と再試行: 変更を繰り返す前にリソースの現在の状態と前回の結果を確認します。request_id を保存し、結果不明の書き込みを自動で繰り返さないでください。

JSON の例です。message は実際の原因によって変わります · 400 · 41001

{
  "request_id": "req_example",
  "error": {
    "code": "update_workspace_failed",
    "numeric_code": "41001",
    "message": "Failed to update workspace"
  }
}

invalid_api_key · 11001 · 401

API Key が正しく有効か確認してください。

対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。

JSON の例です。message は実際の原因によって変わります · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

X-Api-Key ヘッダーを追加してください。

対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。

例 · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

workspace_override_forbidden · 11002 · 403

この API Key に許可されていないワークスペースの上書きを要求しています。上書き用ヘッダーを削除し、対象ワークスペースの API Key を使用してください。

発生条件: ワークスペースを上書きする X-Workspace-Id リクエストヘッダーを送った場合に適用されます。

対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。

JSON の例です。message は実際の原因によって変わります · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

target_workspace_not_found · 11004 · 404

上書きで指定したワークスペースが存在しないか利用できません。所有範囲を確認し、上書き用ヘッダーを削除して対象ワークスペースの API Key を使用します。再試行で権限は増えません。

発生条件: ワークスペースを上書きする X-Workspace-Id リクエストヘッダーを送った場合に適用されます。

対処と再試行: 対象の識別子、所有範囲、現在のワークスペースを確認します。不存在やアクセス不可が確認された対象を、一時的なサービス障害として自動再試行しないでください。

JSON の例です。message は実際の原因によって変わります · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}