変更¶
POST /api/v1/workspace/declaration/modify
概要¶
現在のワークスペース宣言を全体置換し、カスタムフィールドは文字列に変換され、組織識別子はシステムによって維持されます。
呼び出し前と使用手順¶
対象ワークスペースの API Key を使用します。ワークスペースは Key によって決定され、Query または Body で workspaceUUID を別途渡すことはできません。ワークスペース宣言は業務識別子と返却表示に使用するキーと値の設定であり、データアクセス認可、課金組織の移行、リソース名変更のためのインターフェースではありません。
まず完全な宣言を読み取り、バックアップしてから declaration オブジェクトを送信します。変更は古い設定を全体置換します。送信されなかったカスタムキーは削除され、{} は古いカスタムキーをクリアします。organization はサーバー側で強制的に上書きされます。business を省略した場合または null の場合は空文字列になり、文字列は前後の空白が除去され、それ以外の値は JSON 文字列化されます。その他の非文字列のカスタム値も JSON 文字列に変換されます。属性値を使用して所属組織や権限を変更することはできません。
free/freeEdition ワークスペースでは現在、直接 true を返し保存されないため、HTTP 200 を実際の変更と同一視しないでください。その他のプランでは送信後にキャッシュを更新します。有料プランで組織情報が利用できない場合、書き込みに失敗することがあります。デプロイメントプランでは organization は固定の default_private_organization です。成功時はブール値のみを返すため、再度読み取って確認してください。キャッシュ更新の失敗は送信後に発生する可能性があるため、エラー後はまず読み戻してから再試行を判断してください。バックグラウンドの組織同期によって宣言値が再度調整されることもあるため、組織関連フィールドはサーバー側の結果を基準にしてください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエスト Body パラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| declaration.organization | string | 渡してもシステムの値で上書きされるため、組織の切り替えには使用できません。 例: organization_example取得または入力方法: サーバー側でワークスペースのプランと組織情報に基づいて決定されるため、呼び出し側は省略できます。 |
|
| declaration.business | 任意の JSON 値 | オプション。省略時または null の場合は空文字列になります。文字列は前後の空白が除去され、配列/オブジェクト/数値/ブール値は JSON 文字列になり、元の構造は保持されません。 例: checkout取得または入力方法: 業務上の所属識別子を入力します。複数の所属がある場合は、安定した文字列を独自に取り決めることを推奨します。 |
|
| declaration.{カスタムキー} | 任意の JSON 値 | カスタム属性を格納できます。文字列はそのまま保存され、非文字列は json.dumps で変換されます。JSON オブジェクト/数値型が保持されることに依存しないでください。後続のバックグラウンド同期で値/空白が調整される可能性があります。 例: platform取得または入力方法: チームで取り決めた実際のキー名でプレースホルダーを置き換えます(例: costCenter)。 |
|
| declaration | json | Y | 必須の JSON オブジェクト。オブジェクト以外はパラメータ検証段階で拒否される必要があります。{} は有効ですが古いカスタムキーをクリアし、システムの organization と business のみを再構築します。増分パッチではありません。 null を許可: False 例: {"business": "checkout", "costCenter": "platform"}取得または入力方法: まず現在の宣言を読み取り、引き続き必要なトップレベルの業務/カスタムキーを保持し、共通の補助 declaration を除外してから全体を送信します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/declaration/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"declaration":{"business":"checkout","costCenter":"platform"}}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | 処理完了時に true を返します。無料プラン/無料版では現在、変更なしで true となるため、読み戻して確認する必要があります。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
組織上流の失敗時は、実際のエラーコード/メッセージが保持される場合があり、今回のレスポンスを基準とします。動的な下流エラーを固定のパラメータ 406 として偽装しません。リクエストには workspaceUUID、ブランド、Boss ノードのフィールドは含まれません。これらは現在のワークスペースによって決定されます。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 401 | ft.WKSPNotExistOrReleased | 現在のワークスペースが存在しないか、すでに解放されています | ワークスペースが存在しない/または解放済み | Key の帰属とワークスペースの状態を確認してください。 |
| 406 | ft.InvalidBossNode | 有料/エンタープライズプランの組織ノード設定が存在しない | 無効な Boss ノード | 管理者に連絡して組織サイト設定を修正してください。呼び出し側はブランド/ノードフィールドを送信する必要はありません。 |
| 500 | ft.InternalServerError | 組織上流、ストレージ送信、またはキャッシュ更新の失敗 | 内部エラー | traceId を保持し、まず読み取って保存済みかどうかを確認してから再試行を判断してください。 |
| 400 | ft.JsonFormatError | リクエスト JSON のトップレベルがオブジェクトではない(例: 配列や文字列) | 一部の json ファイル形式エラー | declaration オブジェクトを含む JSON オブジェクトを送信してください。 |