コンテンツにスキップ

一覧表示



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 を保持し、後で上限回数まで再試行します。継続的に失敗する場合は、管理者に読み取り経路の確認を依頼してください。

フィードバック

このページは役に立ちましたか?