変更¶
POST /api/v1/mgroup/{group_uuid}/modify
概要¶
バックエンドグループの名前を変更し、完全なアカウントリストに基づいてメンバーをリセットします。
呼び出し前の準備と使用手順¶
まずバックエンドグループリストを呼び出して showMembers を有効にし、既存の完全なメンバーを保存してから、対象リストを送信します。これは全体置換であり、増分追加ではありません。accountUUIDs を指定した場合、リストに含まれない既存のメンバー関係は削除されます。accountUUIDs を省略するとメンバーは保持され、null または [] を指定するとメンバーがクリアされます。名前のみを変更する場合は空の配列を含めないでください。name を省略すると名前は保持され、両方を省略した場合は関係を変更せずに 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 リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| accountUUIDs[*] | string | 単一のアカウント UUID 文字列であり、メールアドレスやワークスペース UUID ではありません。 例: acnt_example001取得・入力方法: サイトアカウントリストの content.data[].uuid から単一のアカウントを取得します。 |
|
| accountUUIDs | array | アカウント UUID の完全な配列で、集合として重複排除されます。呼び出し元はアカウントの存在と必要な状態を事前に検証する必要があり、API は未知のアカウントや削除済みアカウントをすべて主動的にフィルタリングするわけではありません。省略すると保持、明示的な null または [] で全メンバーをクリア、非空の配列で完全置換します。 null 許可: True 例: ["acnt_example001"]取得・入力方法: サイトアカウントリストの content.data[].uuid から実際のアカウントを取得し、先に状態を確認します。 |
|
| name | string | 任意。最大 256 文字です。null は不可で、空でない名前を指定することを推奨します。 null 許可: False 最大長: 256 例: サンプル開発グループの新しい名前取得・入力方法: 必要に応じて新しい名前を入力します。保持する場合は省略します。 |
パラメータの補足説明¶
サイトレベルの External API AK/SK を使用します。署名方式はExternal API 署名認証を参照してください。バックエンドグループ mgroup_ は複数のワークスペースに関連付けて継承ロールを付与できます。単一ワークスペース内の group_ チームとは異なる種類のオブジェクトです。書き込みリクエストには w 権限が必要で、リストには r または w を使用できます。メンバー変更後、関連するワークスペースのメンバー権限キャッシュを非同期でリフレッシュします。HTTP 200 は、すべてのセッションが新しい権限を消費済みであることを意味しません。グループエンティティの updateAt が、メンバーのみの変更を反映することを保証しません。
リクエスト例¶
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'
query = {}
data = {'name': 'サンプル開発グループの新しい名前', 'accountUUIDs': ['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 | 成功時は true で、アカウントごとの結果はありません。変更フィールドを送信していない場合も 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 を取得します。 |
| 400 | ft.MGroupNameExists | 同じ名前のアクティブなバックエンドグループが既に存在する | 同じ名前のグループが既に存在する | まずリストを確認し、重複しない名前を選択します。既存のグループは変更するべきで、重複して作成しないでください。 |
| 500 | ft.InternalServerError | データベース、非同期キャッシュリフレッシュの送信、監査、または未処理のフィールド例外 | 内部エラー | traceId を保存し、リストからグループ/メンバー/ロールの現在の状態を確認します。データがすでにコミットされている可能性があるため、むやみに重複作成や全体上書きをしないでください。 |