一覧表示¶
GET /api/v1/mgroup/list
概要¶
サイトのバックエンドグループをページングして一覧表示し、アカウントとワークスペース横断ロールを展開できます。
呼び出し前の準備と使用手順¶
有効なグループを作成時間の降順で返します。デフォルトでは members または refWorkspaces は含まれず、それぞれ showMembers、showRefWorkspace で有効にします。無効時は対応するフィールドが省略され、空配列にはなりません。メンバーサマリーには解決可能なアカウントのみが含まれ、アカウント自体のステータスは一律に有効に制限されません。関連付けられたワークスペースも削除済みの可能性があるため、それぞれの status で判断してください。ロールサマリーは無効になったロールを除外します。この一覧は単一ワークスペースのチーム一覧ではなく、groupUUID による完全一致検索も提供しません。名前で検索した後、返された 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 秒文字列を生成します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| pageIndex | integer | デフォルトは 1、最小値は 1 です。 null を許可: False $minValue: 1 例: 1取得または入力方法: 1 から開始し、content.pageInfo に従って後続ページへ進みます。 |
|
| pageSize | integer | デフォルトは 20、最大値は 1000 です。 null を許可: False $maxValue: 1000 $minValue: 1 例: 20取得または入力方法: クライアントの必要に応じて 1 から 1000 を選択します。メンバー/ワークスペースを展開する場合は、1 ページあたりの件数を制御することを推奨します。 |
|
| search | string | 任意。先頭と末尾の空白を除去した後、グループ名の部分一致で検索します。省略または空白の場合はフィルタリングしません。 null を許可: False 例: 研发取得または入力方法: バックエンドグループ名に含まれるキーワードを入力します。 |
|
| showMembers | boolean | 任意。文字列 true/1(大文字小文字と先頭/末尾の空白を無視)で有効になります。それ以外の値では無効となり、デフォルトは false です。 null を許可: False 例: true取得または入力方法: URL Query で true または 1 を指定してアカウント展開を有効にします。不要な場合は省略します。 |
|
| showRefWorkspace | boolean | 任意。文字列 true/1 で有効になり、それ以外の値では無効となり、デフォルトは false です。 null を許可: False 例: true取得または入力方法: URL Query で true または 1 を指定してワークスペースおよびロールの展開を有効にします。 |
パラメータの補足説明¶
サイトレベルの External API AK/SK を使用します。署名方式はExternal API 署名認証を参照してください。バックエンドグループ mgroup_ は複数のワークスペースに関連付けられ、継承ロールを付与できます。単一ワークスペース内の group_ チームとは異なる種類のオブジェクトです。書き込みリクエストには w 権限が必要で、一覧取得には r または w を使用できます。
リクエスト例¶
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 = 'GET'
path = '/api/v1/mgroup/list'
query = {'search': '研发', 'showMembers': 'true', 'showRefWorkspace': 'true', 'pageIndex': 1, 'pageSize': 20}
data = None
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.data | オブジェクト配列 | 現在のページのバックエンドグループ。結果がない場合は []。 |
| content.data[].id | integer または null | レコードのシーケンス番号。呼び出しでは uuid を使用します。作成スナップショットは flush 前に取得されるため、id が null の可能性があります。 |
| content.data[].uuid | string | バックエンドグループの UUID。通常は mgroup_ プレフィックスです。 |
| content.data[].status | integer | 有効なグループは 0 です。一覧では削除済みグループがフィルタリングされます。 |
| content.data[].creator | string | 作成者の識別子。External では通常 sys です。 |
| content.data[].updator | string | 最終更新者の識別子。未更新の場合は空になることがあります。 |
| content.data[].createAt | integer | 作成日時の Unix 秒。 |
| content.data[].deleteAt | integer | 削除日時の Unix 秒。未削除の場合は通常 -1 です。 |
| content.data[].updateAt | integer | グループエンティティの更新日時。未更新の場合は通常 -1 です。メンバー/ワークスペースロールのみを変更した場合、エンティティの更新日時が同期して更新される保証はなく、これに基づいて権限が変更されたかどうかを判断できません。 |
| content.data[].name | string | バックエンドグループの表示名。 |
| content.data[].members | オブジェクト配列 | showMembers が有効な場合のみ存在し、解決できないアカウントは省略されます。 |
| content.data[].members[].uuid | string | アカウント UUID。accountUUIDs の要素として使用できます。 |
| content.data[].members[].status | integer | アカウント自体のステータス。無効/削除済みのステータスを含む場合があり、表示されていることがログイン可能を意味するわけではありません。 |
| content.data[].members[].wsAccountStatus | integer | ID サマリーのワークスペース関係ステータス。この一覧では単一ワークスペースを指定しないため、通常は 3 です。グループの権限付与が失敗したかどうかの判断には使用できません。 |
| content.data[].members[].username | string | アカウントのログイン名。 |
| content.data[].members[].name | string | 表示ニックネーム。 |
| content.data[].members[].iconUrl | string | アバター URL。アバターがない場合は空になることがあります。 |
| content.data[].members[].email | string | アカウントのメールアドレス。 |
| content.data[].members[].mobile | string | アカウントの携帯電話番号。 |
| content.data[].members[].countryCode | string | 携帯電話の国コード。 |
| content.data[].members[].acntWsNickname | string | ID サマリーのワークスペースニックネーム。このサイト一覧では通常空です。 |
| content.data[].refWorkspaces | オブジェクト配列 | showRefWorkspace が有効な場合のみ存在し、各ワークスペースの有効なロールサマリーを含みます。 |
| content.data[].refWorkspaces[].uuid | string | 関連付けられたワークスペースの UUID。書き込みリクエストではフィールド名は workspaceUUID です。 |
| content.data[].refWorkspaces[].name | string または null | 関連付けられたワークスペース名。レコードが存在しない場合は null になることがあります。 |
| content.data[].refWorkspaces[].status | integer または null | ワークスペースのステータス。削除済みの 3 が含まれる場合があります。ワークスペースレコードが見つからない場合は null になることがあります。 |
| content.data[].refWorkspaces[].roles | オブジェクト配列 | 有効なロールサマリー。削除済み/解決できないロールはサマリーに表示されません。これを、関連テーブルに履歴レコードがないと誤解しないでください。 |
| content.data[].refWorkspaces[].roles[].uuid | string | ロール UUID。 |
| content.data[].refWorkspaces[].roles[].name | string | ロールの表示名。 |
| content.pageInfo.pageIndex | integer | 現在のページ番号。 |
| content.pageInfo.pageSize | integer | 1 ページあたりの件数。 |
| content.pageInfo.count | integer | このページのグループ件数。 |
| content.pageInfo.totalCount | integer | フィルタリング後のグループ総数。 |
{
"code": 200,
"content": {
"data": [
{
"id": 1001,
"uuid": "mgroup_example001",
"status": 0,
"creator": "sys",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例研发分组",
"members": [
{
"uuid": "acnt_example001",
"status": 0,
"wsAccountStatus": 3,
"username": "xxx@guance.com",
"name": "示例成员",
"iconUrl": "",
"email": "xxx@guance.com",
"mobile": "",
"countryCode": "",
"acntWsNickname": ""
}
],
"refWorkspaces": [
{
"uuid": "wksp_example001",
"name": "示例空间",
"status": 0,
"roles": [
{
"uuid": "readOnly",
"name": "ReadOnly"
}
]
}
]
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 20,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
展開を有効にしない場合、各グループは基本エンティティ列のみを返します:
{
"code": 200,
"content": {
"data": [
{
"id": 1001,
"uuid": "mgroup_example001",
"status": 0,
"creator": "sys",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例研发分组"
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 20,
"count": 1,
"totalCount": 1
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
一致するものがない場合、data=[] となり、ページネーションの count/totalCount は 0 になります。
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。
表には確認済みのリクエストおよび読み取りエラーを記載します。通常のデータベース、キャッシュ読み取り、または結果フォーマットの例外は最終的に 500 ft.InternalServerError になります。このインターフェースは読み取り専用であり、グループやリレーションを更新しません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認します。 |
| 500 | ft.InternalServerError | データベース、キャッシュ読み取り、または一覧フィールドのフォーマット例外 | 内部エラー | traceId を保持し、後で上限回数まで再試行します。継続的に失敗する場合は、管理者に読み取り経路の確認を依頼してください。 |