ワークスペースを管理¶
POST /api/v1/mgroup/{group_uuid}/modify/workspace
概要¶
バックエンドグループのワークスペース間ロール認可を完全に置き換えます。
呼び出し前と使用手順¶
まずバックエンドグループ一覧で showRefWorkspace を有効にして既存の完全なマッピングを読み取り、次にワークスペースごとにワークスペースロール一覧から対象ロールを確認します。refWorkspaces が含まれる場合は全体を置き換え、一覧にない既存のワークスペース認可は削除されます。省略した場合は維持され、null または [] の場合はグループのすべてのワークスペースロールをクリアします。各 workspaceUUID は 1 回だけ指定します。重複した項目は先頭の項目のみ使用され、マージされません。あるワークスペースの roleUUIDs=[] は、そのワークスペースにおけるグループロールを削除することを示します。ワークスペース自体とアカウントは削除されません。本 API は、ワークスペース/ロールの存在、所属ワークスペース、または対象認可の制約を項目ごとに検証しません。管理者が事前に各項目を確認する必要があり、true を有効な権限が確立済みであるとみなしてはいけません。グループ/関係の状態が先にコミットされ、その後、権限キャッシュの更新が配信されます。HTTP 200 は、後続のすべてのリクエストが直ちに新しい権限を使用することを保証しません。配信または監査の失敗による 500 は、主体の保存後に発生する場合もあります。まずページングで一覧を読み取り、uuid で特定します。変更時は完全な members/refWorkspaces を展開して確認する必要があり、削除時は対象がすでにアクティブ一覧にないことを確認してから再試行を判断します。更新対象一覧が空の場合、共有タスクはすべてのアクティブなワークスペースを更新します。現在のグループのみを更新するものと解釈してはいけません。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| group_uuid | string | Y | 有効なバックエンドグループUUIDであり、単一ワークスペースのgroup_チームUUIDではありません。 例: mgroup_example001取得または入力方法: バックエンドグループ一覧のcontent.data[].uuidから取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョン。省略したうえで本ページのアルゴリズムを引き続き使用することはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用し、例の署名アルゴリズムと組み合わせます。 |
|
| X-Df-Access-Key | string | Y | 読み取り API では r または w の認証情報を使用でき、書き込み API では 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 秒文字列を生成します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| refWorkspaces[*].roleUUIDs[*] | string | 単一のロールUUID文字列であり、数値やオブジェクトは使用しません。成功レスポンスだけからロールが実際に有効であると判断しないでください。 例: readOnly取得または入力方法: 対応するワークスペースのワークスペースロール一覧からロールuuidを取得し、プラットフォームの認可ポリシーに従って選択します。 |
|
| refWorkspaces | array | 完全なワークスペースとロールの対象一覧。このフィールドが含まれる場合は全体を置き換えます。一覧にない既存のワークスペース認可は削除されます。省略した場合は維持され、null または [] の場合はすべてのワークスペースロール認可をクリアします。 null を許可: True 例: [{"workspaceUUID": "wksp_example001", "roleUUIDs": ["readOnly"]}]取得または入力方法: ワークスペース一覧からワークスペースUUIDを取得し、その後ワークスペースごとにワークスペースロール一覧からそのワークスペースのロールを取得します。 |
|
| refWorkspaces[*] | object | 1 つのワークスペース認可オブジェクト。フィールドがリクエストに含まれる場合でも、宣言された構造に準拠する必要があります。workspaceUUID が重複する場合は最初のロール一覧のみが使用され、マージされません。 例: {"workspaceUUID": "wksp_example001", "roleUUIDs": ["readOnly"]}取得または入力方法: 対象ワークスペースごとに workspaceUUID と完全な roleUUIDs 配列を 1 項目として構成します。同じワークスペースは 1 回だけ指定します。 |
|
| refWorkspaces[*].roleUUIDs | array | 条件必須 | 必須の完全なロール配列。各項目は先頭と末尾の空白を除去し、重複を排除し、空文字列を削除します。[] はそのワークスペースのすべてのグループロール認可を削除します。ロールの存在/帰属を完全には検証せず、Owner の一意性や引き継ぎの検証も実行しません。API が未知のロールや他のワークスペースのロールを拒否することを前提にできません。Owner の変更を伴う場合は正式な引き継ぎフローに従う必要があります。 null を許可: False 例: ["readOnly"]取得または入力方法: 対象項目の workspaceUUID に対応する有効なロールUUIDをワークスペースロール一覧から取得します。 |
| refWorkspaces[*].workspaceUUID | string | 条件必須 | 必須のワークスペースUUID文字列。事前にワークスペースの存在と状態を確認する必要があります。本 API は項目ごとに検証しないため、誤った UUID も保存される可能性があります。 null を許可: False 例: wksp_example001取得または入力方法: ワークスペース一覧から、バックエンドグループによる認可が必要なアクティブなワークスペースを取得します。 |
パラメータ補足説明¶
サイトレベルの External API AK/SK を使用します。署名方式はExternal API 署名認証を参照してください。バックエンドグループmgroup_は複数のワークスペースに関連付けて継承ロールを付与できます。単一ワークスペース内のgroup_チームとは異なる種類のオブジェクトです。書き込みリクエストには w 権限が必要で、一覧では r または w を使用できます。roleUUIDs は増分ではなく完全な対象配列を使用し、メンバーが継承する権限もそれに伴って変化します。保存後、関連するワークスペースメンバーのキャッシュが非同期で更新されます。完了後に一覧と実際のアクセス権限を照会して確認してください。
リクエスト例¶
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 = 'POST'
path = '/api/v1/mgroup/mgroup_example001/modify/workspace'
query = {}
data = {'refWorkspaces': [{'workspaceUUID': 'wksp_example001', 'roleUUIDs': ['readOnly']}]}
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 | boolean | 処理が成功した場合は true。実際の書き込み数や有効な認可一覧は返しません。refWorkspaces を省略して変更がない場合も true になります。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。
表には確認済みのリクエストおよび業務エラーを記載しています。通常の内部例外は最終的に 500 ft.InternalServerError になります。グループ/関係がコミット済みで、その後のキャッシュまたは監査が失敗する可能性があります。まず現在の状態を読み取り、エラーだけから未反映と推測してはいけません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンス説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析に失敗 | パラメータの位置、フィールド名、型、値を確認します。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON 形式エラー | content.reason、line、column に従って JSON を修正します。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではない | 一部の json ファイル形式エラー | 表に従って JSON オブジェクトを送信します。 |
| 404 | ft.MGroupNoExists | グループUUIDが存在しない、またはグループが削除済み | グループが存在しない | バックエンドグループ一覧から有効なmgroup_レコードuuidを取得します。 |
| 500 | ft.InternalServerError | データベース、非同期キャッシュ更新の配信、監査、または未処理のフィールド例外 | 内部エラー | traceId を保存し、一覧からグループ/メンバー/ロールの現在の状態を確認します。データはすでにコミットされている可能性があるため、盲目的に重複作成または全体上書きをしないでください。 |