作成¶
POST /api/v1/mgroup/add
概要¶
バックエンドグループを作成し、初期アカウントメンバーを設定できます。
呼び出し前の確認と使用手順¶
まず同名のグループを検索し、既存のアカウントを初期メンバーとして選択します。本 API は名前で重複排除を行いますが冪等キーはありません。タイムアウトした場合は、まず一覧を検索して結果を確認してください。accountUUIDs はグループの関連付けを作成するだけで、アカウントの作成や有効化は行いません。refWorkspaces を受け取る宣言がありますが、現在の作成実装ではワークスペース/ロールのマッピングは保存されません。このパラメータは省略し、新しい 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 から単一のアカウントを取得します。 |
|
| refWorkspaces[*].roleUUIDs[*] | string | 単一のロール UUID 文字列です。数値やオブジェクトは使用しません。成功レスポンスだけでロールが実際に有効であると判断しないでください。 例: readOnly取得または入力方法: 対応するワークスペースのワークスペースロール一覧からロール uuid を取得し、プラットフォームの認可ポリシーに従って選択します。 |
|
| accountUUIDs | array | アカウント UUID の完全な配列で、集合として重複排除されます。呼び出し元は事前にアカウントの存在と必要な状態を検証する必要があり、API は未知/削除済みのアカウントをすべてフィルタリングするわけではありません。省略、null、または [] の場合は初期メンバーを追加しません。 null を許可: True 例: ["acnt_example001"]取得または入力方法: サイトアカウント一覧の content.data[].uuid から実在するアカウントを取得し、まず状態を確認します。 |
|
| name | string | Y | 必須の空でない名前で、最大 256 文字です。 null を許可: False 最大長: 256 例: 示例研发分组取得または入力方法: バックエンドグループ一覧で有効なグループ名を確認してから、新しい空でない名前を指定します。 |
| refWorkspaces | array | 現在の作成 API はこのパラメータを保存しません。省略することを推奨します。作成後に別途ワークスペースロールの変更を呼び出してください。 null を許可: True 例: [{"workspaceUUID": "wksp_example001", "roleUUIDs": ["readOnly"]}]取得または入力方法: ワークスペース一覧からワークスペース UUID を取得し、各ワークスペースについてワークスペースロール一覧からそのワークスペースのロールを取得します。 |
|
| refWorkspaces[*] | object | 1 つのワークスペース認可オブジェクトです。フィールドがリクエストに含まれる場合は、宣言された構造に適合している必要があります。作成時にはこのオブジェクトは適用されません。 例: {"workspaceUUID": "wksp_example001", "roleUUIDs": ["readOnly"]}取得または入力方法: 対象のワークスペースごとに workspaceUUID と完全な roleUUIDs 配列を 1 項目として構成します。同じワークスペースは 1 回だけ指定します。 |
|
| refWorkspaces[*].roleUUIDs | array | 条件付き必須 | 必須の完全なロール配列です。作成時は現在このマッピングを無視します。 null を許可: False 例: ["readOnly"]取得または入力方法: 該当項目の workspaceUUID に基づき、ワークスペースロール一覧から対応する有効なロール UUID を取得します。 |
| refWorkspaces[*].workspaceUUID | string | 条件付き必須 | 必須のワークスペース UUID 文字列です。作成時は現在このマッピングを無視します。 null を許可: False 例: wksp_example001取得または入力方法: ワークスペース一覧から、バックエンドグループによる認可が必要な有効なワークスペースを取得します。 |
パラメータ補足説明¶
サイトレベルの External API AK/SK を使用します。署名方式はExternal API 署名認証を参照してください。バックエンドグループ mgroup_ は複数のワークスペースに関連付けて継承ロールを付与できます。単一のワークスペース内の group_ チームとは異なる種類のオブジェクトです。書き込みリクエストには w 権限が必要で、一覧では r または w を使用できます。リポジトリの countLimit はデフォルト 1000 で、サイト側で上書きできます。現在の判定では既存数がしきい値を超えた場合のみ拒否されるため、しきい値と等しい場合にバックエンドが必ず拒否すると見なすことはできません。作成スナップショットは flush 前に取得されるため、id が null になる可能性があります。
リクエスト例¶
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/add'
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.id | integer または null | レコードの連番です。呼び出しには uuid を使用します。作成スナップショットは flush 前に取得されるため、id が null になる可能性があります。 |
| content.uuid | string | バックエンドグループの UUID で、通常は mgroup_ プレフィックスが付きます。 |
| content.status | integer | 有効なグループは 0 です。一覧では削除済みのグループはフィルタリングされます。 |
| content.creator | string | 作成者の識別子で、External では通常 sys です。 |
| content.updator | string | 最終更新者の識別子で、未更新の場合は空になることがあります。 |
| content.createAt | integer | 作成日時の Unix 秒です。 |
| content.deleteAt | integer | 削除日時の Unix 秒で、未削除の場合は通常 -1 です。 |
| content.updateAt | integer | グループエンティティの更新日時で、未更新の場合は通常 -1 です。メンバーやワークスペースロールのみを変更してもエンティティの時刻が同期更新される保証はなく、これに基づいて認可が変更されたかどうかを判断することはできません。 |
| content.name | string | バックエンドグループの表示名です。 |
{
"code": 200,
"content": {
"id": null,
"uuid": "mgroup_example001",
"status": 0,
"creator": "sys",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例研发分组"
},
"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 オブジェクトを送信してください。 |
| 406 | ft.MissingParameters | name が空文字列 | パラメータ欠落 | 空でないグループ名を指定してください。 |
| 400 | ft.MGroupNameExists | 同名の有効なバックエンドグループが既に存在する | 同名のグループが既に存在します | まず一覧を確認し、重複しない名前を選択してください。既存グループは変更するべきで、重複して作成しないでください。 |
| 400 | ft.MGroupCountExceedsLimit | 既存の有効なグループ数がサイトの countLimit を超えている状態でさらに追加した場合 | グループ数が最大制限を超えています。最大制限数:{} |
管理者がサイトのグループクォータと既存グループを確認し、クリーンアップまたは設定の調整後に再度作成してください。 |
| 500 | ft.InternalServerError | データベース、非同期キャッシュ更新の送信、監査、または未処理のフィールド例外 | 内部エラー | traceId を保存し、一覧からグループ/メンバー/ロールの現在の状態を確認してください。データが既にコミットされている可能性があるため、むやみに重複作成したり全体を上書きしたりしないでください。 |