同一組織のワークスペース簡易リストを取得¶
POST /api/v1/workspace/same_org/list
概要¶
組織宣言に基づいてアクティブなワークスペースを一覧表示します。ID カーソルによるページネーションをサポートします。
呼び出し前および使用手順¶
対象ワークスペースで routine.defaultAccess などの読み取り許可権限を持つ OpenAPI Key を使用します。現在のワークスペースはリクエストヘッダーの Key から取得し、このエントリポイントで workspaceUUID を渡して切り替えることはありません。
現在のアクティブワークスペースには、空でない declaration.organization が必要です。その組織識別子に基づいてすべてのアクティブワークスペースを完全一致で抽出し、現在のワークスペース自身も含みます。呼び出しアカウントが参加しているかどうか、またはクロスワークスペース認可をすでに持っているかどうかによるフィルタリングは行いません。返却結果は同一組織のディレクトリ関係を示すものであり、他のワークスペースのデータを読み取ったり、ワークスペースを管理したり、他のサイトにアクセスしたりできることを意味するものではありません。
workspaceId の降順で並びます。最初の呼び出しでは beforeWorkspaceId を省略し、トップレベルの pageInfo.hasMore を読み取ります。true の場合は nextBeforeWorkspaceId を使用して続行し、workspaceUUIDs の絞り込み条件を維持します。このページではカーソルを使用し、pageIndex/totalCount は提供しません。空のフィルター配列は、同一組織のすべてのワークスペースを対象とすることを意味し、どのワークスペースも対象にしないことを表すものではありません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| workspaceUUIDs[*] | string | 単一の空でない UUID。最大 128 文字。trim 後に重複を排除します。リスト内で現在の組織に属さない項目または非アクティブな項目は返されません。 例: wksp_example取得または入力方法: 実際のワークスペースの workspaceUUID を指定します。数値の workspaceId ではありません。 |
|
| beforeWorkspaceId | integer | 省略可能な正の整数カーソル。最初の呼び出しでは省略または null を指定します。数値の workspaceId がこの値より小さいレコードのみを返します。pageIndex やワークスペース UUID ではありません。独自に加減算しないでください。 null を許可: True 例: 1200取得または入力方法: 前ページのトップレベル pageInfo.nextBeforeWorkspaceId を指定します。最初の呼び出しでは省略します。 |
|
| pageSize | integer | 省略可能な正の整数。省略または null の場合はデフォルト 20 です。上限はサイトの workspaceListPageSizeMax で制御され、デフォルトは 100 です。数値文字列とブール値は使用できません。 null を許可: True 例: 20取得または入力方法: 希望する 1 ページあたりの件数に応じて指定します。通常は 1..100 です。 |
|
| workspaceUUIDs | array | 省略可能な文字列配列。省略、null、[] のいずれも絞り込みを行いません。最大でサイトの maxWorkspaceCount(デフォルト 20)項目までで、制限は重複排除前にチェックされます。各項目の空白を除去して重複を排除します。空白項目、文字列以外、128 文字を超える項目は拒否されます。呼び出し元のメンバーやデータ認可を代わりに作成することはありません。 null を許可: True 例: ["wksp_example"]取得または入力方法: 現在のワークスペースの詳細、または以前の同一組織リストの content.data[].workspaceUUID から取得します。範囲を絞り込みたいワークスペース UUID のみを入力します。 |
パラメータ補足説明¶
このインターフェースは SameOrgTraceQuerySet.enable の制御を受けず、同一組織の trace クエリ対象ワークスペースを選択する補助にのみ使用されます。
workspaceIdはこのインターフェースのページネーションにのみ使用されます。- 後続の trace クエリでは
workspaceUUIDを使用する必要があります。 - このインターフェースは DQL クエリを実行せず、Kodo の最終的な同一組織検証を代替するものでもありません。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/same_org/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"pageSize":20}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.data | array<object> |
現在のページの同一組織ワークスペース。結果が空の場合は []。 |
| content.data[].workspaceId | integer | データベースの数値 ID。リストのカーソルにのみ使用されます。 |
| content.data[].workspaceUUID | string | ワークスペース UUID。後続のクエリ/認可では引き続き個別の条件が必要です。 |
| content.data[].workspaceName | string | ワークスペース名。 |
| content.data[].versionType | string | ワークスペースの実際のバージョンコード(pay/enterprise/unlimited/freeEdition など)。このインターフェースによって切り替えられるものではありません。 |
| content.declaration | object | 現在の呼び出しワークスペースの共通宣言であり、返却される各ワークスペースの宣言ではありません。 |
| pageInfo.pageSize | integer | 今回の 1 ページあたりの件数。 |
| pageInfo.hasMore | boolean | より小さい ID のレコードがまだ存在するかどうか。 |
| pageInfo.nextBeforeWorkspaceId | integer | hasMore=true かつこのページにレコードがある場合にのみ出現します。次回の beforeWorkspaceId です。 |
{
"code": 200,
"content": {
"data": [
{
"workspaceId": 1200,
"workspaceUUID": "wksp_example",
"workspaceName": "示例空间",
"versionType": "pay"
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE",
"pageInfo": {
"pageSize": 20,
"hasMore": false
}
}
エラー応答¶
認証、レート制限、共通リクエストエラーについては、共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたは応答説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反しています | パラメータの解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | リクエスト JSON のトップレベルがオブジェクトではありません | 一部の json ファイルの形式エラー | オブジェクトを送信してください。 |
| 406 | ft.ParameterCheckFailed | UUID リスト/件数/項目、ページサイズ/カーソルが一致しない、または現在のワークスペースに有効な組織宣言がありません | 例: page_size must be <= 100(具体的なフィールドおよび上限は今回返却されたメッセージに準じます) | content.field に基づいて修正してください。エラーの field では workspace_uuids/page_size/before_workspace_id/organization などの内部マッピング名が使用される場合があります。組織宣言の欠落については管理者が確認してください。 |
| 500 | ft.InternalServerError | ワークスペース/サイト/認可設定、データベースまたはキャッシュの読み取り、および応答フォーマットに失敗しました | 内部エラー | traceId とクエリ条件を保持してください。再試行しても失敗が続く場合は、管理者に設定の確認を依頼してください。空の結果からサイトにデータがないと推測しないでください。 |