ワークスペースの Owner を変更¶
POST /api/v1/workspace/{workspace_uuid}/owner/transfer
概要¶
指定したアカウントを Owner に設定し、元の Owner の直接メンバー関連付けを削除します。
呼び出し前の準備と使用手順¶
w 権限の External 認証情報が必要です。まずワークスペース一覧でワークスペースが実在することを確認し、現在の Owner を読み取って引き継ぎの影響を確認したうえで、サイトアカウント一覧から対象アカウントを選択します。対象は本ワークスペースに既に属している必要はなく、必要に応じて直接メンバー関係が新規追加されます。有効なアカウントの使用を推奨します。現在の検証は削除済みアカウントのみを除外するため、無効化されたアカウントでも通過する可能性がありますが、正常にログインできません。agent ソースは Owner になれません。元の Owner の Owner ロールと直接メンバー関連付けは削除されますが、アカウント自体は削除されません。バックエンドのグループなどに基づいて生成される継承関係は、同期してクリアされるものとして扱うべきではありません。対象には Owner ロールが新規追加され、既存の他の直接ロールが併せて削除されることは保証されません。対象が既に現在の Owner である場合は true を直接返します。この操作は請求センターアカウントを作成/移行しません。成功後はワークスペースメンバーと Owner を確認してください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| workspace_uuid | string | Y | 対象ワークスペースの UUID。事前にアクティブ状態とサイトを確認します。 例: wksp_example001取得・記入方法: ワークスペース一覧の content.data[].uuid から取得し、ワークスペース名を確認します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョン。省略したまま本ページのアルゴリズムを継続使用することはできません。 例: v20240417取得・記入方法: 本ページの例ではこの固定バージョンを使用し、例の署名アルゴリズムと組み合わせます。 |
|
| X-Df-Access-Key | string | Y | 読み取りインターフェースでは r または w の認証情報を使用でき、書き込みインターフェースでは 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 リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| accountUUID | string | Y | 必須の対象アカウント UUID 文字列です。宣言上は null を許可していますが、null または空文字列ではアカウントを検索できません。ワークスペース UUID を記入しないでください。この External インターフェースでは、対象があらかじめワークスペースメンバーであることは要求されません。 空文字列を許可: False null を許可: True 例: acnt_example001取得・記入方法: サイトアカウント一覧の content.data[].uuid から対象アカウントを取得します。agent ソースではなく、status=0 を推奨します。 |
パラメータ補足説明¶
認証についてはExternal API 署名認証を参照してください。本ページの例では v20240417 を使用し、元の完全パス、Query、リクエストボディの署名アルゴリズムと組み合わせます。このモジュールは指定ワークスペースのメンバー関係またはロールを操作し、アカウント自体は作成しません。書き込みリクエストが失敗した場合は、まずメンバーとロールの現状を確認してから再試行するか判断してください。事前に一覧からワークスペース UUID を確認してください。現在の移行メソッドはワークスペースの存在確認を別途提供しません。移行と後続のキャッシュクリアは段階的に実行されるため、失敗後は現在の Owner を確認してから次のステップを判断してください。
リクエスト例¶
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/workspace/wksp_example001/owner/transfer'
query = {}
data = {'accountUUID': 'acnt_example001'}
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 | 移行が完了した場合、または対象が既に現在の Owner である場合は true。Owner の詳細は返しません。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
下表は確認済みの業務エラーおよびリクエストエラーです。通常のデータベース/下流 5xx または未処理の例外はグローバルで ft.InternalServerError にラップされます。書き込みリクエストの失敗は部分的に反映されていないことを保証しないため、まず関係の現状を確認してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータの解析に失敗 | パラメータの位置、フィールド名、型、値を確認します。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正します。 |
| 400 | ft.JsonFormatError | リクエスト JSON のトップレベルがオブジェクトでない | 一部の json ファイルの形式エラー | JSON オブジェクトを送信し、配列や null をリクエストボディ全体として使用しないでください。 |
| 404 | ft.NotFoundAccount | 対象 accountUUID が存在しない、削除済み、空、または null | 指定されたアカウントが見つかりません | サイトアカウント一覧から対象アカウントを再選択します。 |
| 400 | ft.AgentMemberCanNotBeOwner | 対象アカウントの source=agent | agent ソースのメンバーはワークスペースの所有者に設定できません | 通常のメンバーアカウントを選択します。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、旧承認タスクのキャンセル、または未処理の配列/フィールド例外 | 内部エラー | traceId を保存し、管理者に実際の関係とキャッシュの確認を依頼します。書き込み操作は部分的にコミットされている可能性があるため、無闇に再実行しないでください。 |