参照可能なワークスペース一覧¶
GET /api/v1/wksp_share/granted_ws_list
概要¶
付与元サイトごとに、現在のワークスペースで参照可能な許可済みワークスペースを一覧表示します。
呼び出し前の準備と使用手順¶
対象ワークスペースに対して routine.defaultAccess などの読み取り許可を持つ OpenAPI Key を使用します。現在のワークスペースはリクエストヘッダーの Key から特定され、このエンドポイントで workspaceUUID を渡して切り替えることはありません。
現在のワークスペースに明示的に付与された有効な許可レコードを返します。サイト全体や同一組織のワークスペース一覧ではありません。許可状態は有効な active である必要があります。クロスサイトの mirror 同期に失敗し、リソースサマリーがまったくない場合は除外されますが、古いサマリーがある場合は返されることがあります。複数の namespace を指定した場合、同一の許可レコードがすべてのタイプを含む必要があり、異なる許可レコードを組み合わせて 1 件として満たすことはありません。
まず content[].regionCode を取得し、次に各 data[].workspaceUUID を使ってクロスワークスペースクエリの対象を構築します。type/indexes/conditions と実際のクエリ権限には引き続き従う必要があります。一覧に表示されているからといって、現在の呼び出し Key が各データタイプのクエリ権限を持っていること、ソースワークスペースがロックされていないこと、クエリの下流が利用可能であることは保証されません。同一サイトのロック状態の通知と、クロスサイトの未知を表す null は区別する必要があります。
ソースサイトごとにグループ化され、各グループは独立してページングされます。同一の pageIndex/pageSize がすべてのグループに適用され、各グループの pageInfo は content[].pageInfo にあり、トップレベルには pageInfo がありません。総数まで読み終えていないサイトについては個別に続きを取得し、regionCode で 1 グループを固定してページ漏れを避けることを推奨します。サイトに有効な設定がない通常レコードは無視されることがありますが、外部組織のクロスサイトで自身のサイト情報を持つ場合は表示されることがあります。空の結果は [] です。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得・設定方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| filterWsUUIDs | commaArray | 任意。これらのソースワークスペースのみに絞り込みます。現在の実装ではカンマで分割する際に各項目を自動 trim しないため、呼び出し側は空白を入れないでください。受信側ワークスペースの一覧ではありません。 null 許可: False 例: wksp_source_example取得・設定方法: 付与元の workspaceUUID を指定します。複数の場合は半角カンマで区切ります。 |
|
| namespace | commaArray | 任意。カンマ区切りで指定し、空の項目は trim により除去されます。複数タイプを指定した場合、同一の有効な許可レコードがすべてのタイプを同時に含む必要があり、許可が * の場合はすべてを満たします。未知のタイプは利用可能な許可を意味せず、通常は一致しません。 null 許可: False 例: logging,tracing取得・設定方法: クエリ対象のデータタイプ(logging/metric/tracing/rum/lineage/incidents など)を、許可済みの type に基づいて指定します。 |
|
| pageIndex | integer | 任意。デフォルト 1、最小 1。同一ページ番号が各サイトグループに適用され、サイト全体で統一されたページングではありません。 null 許可: False $minValue: 1 例: 1取得・設定方法: 1 から開始し、サイトグループごとにページングを個別に読み取ります。 |
|
| pageSize | integer | 任意。デフォルト 100、最大 100。返却される総件数が pageSize より大きくなる場合があります。 null 許可: False $maxValue: 100 $minValue: 1 例: 100取得・設定方法: 各サイトで期待する 1 ページあたりの件数(1..100)です。 |
|
| regionCode | string | 任意。付与元サイトのコード。サービスは通常のコードと custom: プレフィックス付きの同一コードの両方を受け付けますが、以降のクエリでは返却値をそのまま使用してください。 null 許可: False 例: site_example取得・設定方法: サイト一覧、または本インターフェースの content[].regionCode から取得します。 |
|
| search | string | 任意。付与元の workspaceName/workspaceUUID に対して部分一致検索を行います。対象名は検索しません。 null 許可: False 例: production取得・設定方法: ソースワークスペース名または UUID のキーワードを指定します。 |
パラメータ補足¶
本インターフェースは、query_data で対象ワークスペースの UUID と query.targetRegion を取得するための推奨インターフェースです。
content[j].regionCodeは、そのグループ内の許可済みワークスペースが属するサイトを表し、そのままquery.targetRegionとして使用できます。グループ内のdata[k].regionCodeも同じ意味です。content[j].data内でworkspaceUUIDから対象ワークスペースを特定し、同じグループのregionCodeを使用します。toRegionCodeを対象サイトとして扱わないでください。これは付与先、 つまり現在の API Key が属するワークスペースのサイトを表します。namespaceで許可されたデータタイプをフィルタできます。たとえばログをクエリする場合はnamespace=loggingを渡します。- 本インターフェースは
regionCodeごとのグループで独立してページングされ、pageInfo.countは現在のページの件数のみを表します。初回はregionCodeを渡さずに対象サイトを検出できます。その後は対象サイトごとにregionCodeを明示的に渡し、pageIndex=1から独立してページをめくってください。そのサイトのpageInfo.totalCountに達した場合、またはpageIndex * pageSize >= totalCountを満たした場合に停止します。許可のuuidと(regionCode, workspaceUUID)で重複排除することを推奨します。
具体的なリクエストの組み立て方については、OpenAPI クロスサイトデータクエリ を参照してください。
1. 返却パラメータの説明:
| パラメータ名 | 説明 |
|---|---|
| regionCode | 付与元サイト |
| regionName | 付与元サイト名 |
| workspaceName | 付与元ワークスペース名 |
| workspaceUUID | 付与元ワークスペース UUID |
| toRegionCode | 付与先ワークスペースのサイト |
| toRegionName | 付与先ワークスペースのサイト名 |
| toWorkspaceName | 付与先ワークスペース名 |
| toWorkspaceUUID | 付与先ワークスペース UUID |
| type | ワークスペースの許可タイプ。network、object、dialtest、billing、logging、tracing、metric、rum、keyevent、custom_object、security、profiling。* はすべてのタイプの許可を表します |
| indexes | 許可されたログインデックス名。* はすべてを表します |
注意: 返却される content は付与元サイトごとにグループ化された配列です。各要素の data は、そのサイトの現在のページにおける参照可能なワークスペース情報です。
2. 例の説明: 付与先は、付与元が許可したデータを参照できます 以下の例では、XX ワークスペースが YY ワークスペースにログの testing インデックスの参照権限を付与しており、すなわち YY ワークスペースは XX ワークスペースのログ testing インデックスのデータを参照できます
{
"createAt": 1749542060,
"creator": "acnt_c956fd23a9c2427b96ee372c88ea9b60",
"creatorInfo": {
},
"delayDeleteAt": -1,
"deleteAt": -1,
"id": 442,
"indexes": [
"testing"
],
"regionCode": "daily",
"regionName": "開発環境(daily)",
"status": 0,
"toRegionCode": "testing",
"toRegionName": "テスト環境(testing)",
"toWorkspaceName": "YY",
"toWorkspaceUUID": "wksp_4b57c7bab38e4a2d9630f675dc20015d",
"type": [
"logging"
],
"updateAt": -1,
"updator": "",
"updatorInfo": {
},
"uuid": "grant_02b04aec78c74f869151e3e8c3e54dae",
"workspaceName": "XX",
"workspaceUUID": "wksp_6e310e0c1cbd45b4a27a19bda0fd7582"
}
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/wksp_share/granted_ws_list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode namespace=logging \
--data-urlencode pageIndex=1 \
--data-urlencode pageSize=100
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | array<object> |
付与元サイトごとにグループ化されます。一致しない場合は [] です。 |
| content[].regionCode | string | このグループのソースサイトコード。query_data の query.targetRegion として使用できます。 |
| content[].regionName | string | このグループのサイト表示名。 |
| content[].data | array<object> |
このグループの現在のページの許可レコード。空の場合があります。 |
| content[].data[].id | integer | 許可レコードの数値 ID。 |
| content[].data[].uuid | string | grant_ で始まる許可レコードの UUID。ソースワークスペースの UUID ではありません。 |
| content[].data[].workspaceUUID | string | 付与元/データソースワークスペースの UUID。クロスワークスペースクエリの対象にはこのフィールドを使用します。 |
| content[].data[].workspaceName | string | 付与元ワークスペース名。 |
| content[].data[].toWorkspaceUUID | string | 付与先ワークスペースの UUID。本インターフェースでは通常、現在のワークスペースです。 |
| content[].data[].toWorkspaceName | string | 付与先ワークスペース名。 |
| content[].data[].regionCode | string | 付与元サイトコード。custom: プレフィックスが付く場合があります。 |
| content[].data[].toRegionCode | string | 付与先サイト。履歴で同一サイトの場合の空値は、現在のサイトに正規化されることがあります。 |
| content[].data[].regionName | string | 付与元サイトの現在の言語での表示名。存在しない場合はサイト情報またはコードにフォールバックします。 |
| content[].data[].toRegionName | string | 付与先サイトの表示名。 |
| content[].data[].type | array<string> または string または null |
このレコードで許可されるデータタイプ。現在は通常配列ですが、履歴ではカンマ区切り文字列や null の場合があります。まず実際の型を判定してください。* はすべての許可タイプを表しますが、他の制約を無視するものではありません。 |
| content[].data[].type[] | string | 個々のタイプコード。 |
| content[].data[].indexes | array<string> または null |
ログインデックスの許可範囲。* の場合があります。すべてのデータタイプに共通のリソース一覧として扱わないでください。履歴では null の場合があるため、まず型を判定してください。 |
| content[].data[].indexes[] | string | 個々のインデックス名または *。 |
| content[].data[].conditions | object または null | 許可されたデータのフィルタ条件。データタイプごとに保存され、独自に削除してクエリ許可の根拠とすることはできません。履歴では null の場合があり、この formatter では正規化されません。 |
| content[].data[].conditions.データタイプ | JSON | そのタイプで保存された完全なフィルタルール。構造は許可設定に従い、条件の配列またはオブジェクトの場合があります。 |
| content[].data[].siteRelationType | string | same_site/same_org_cross_site/external_org_cross_site。履歴の値はサイトから推導されます。 |
| content[].data[].grantMode | string | same_site または cross_site。サイト関係から推導されます。 |
| content[].data[].grantStatus | string | 現在有効な許可は active です。pending/revoked などは有効性フィルタで除外されます。 |
| content[].data[].syncStatus | string | クロスサイトリソースサマリーの同期状態(空/success/failed など)。failed でも履歴サマリーがある場合は返されることがあります。 |
| content[].data[].lastSyncAt | integer または null | 最終同期の Unix 秒。未同期の場合は null になります。 |
| content[].data[].sourceBaseUrl | string | 付与元サービスのルートアドレスの履歴フィールド。空の場合があります。クライアントのクロスワークスペースクエリは引き続き権限のある公開エンドポイントを経由します。 |
| content[].data[].targetBaseUrl | string | 付与先サービスのアドレス。空の場合があります。 |
| content[].data[].delayDeleteAt | integer | 削除予定の Unix 秒。予定なしは -1。現在の有効な許可やクエリ時の検証を置き換えるものではありません。 |
| content[].data[].sourceWorkspaceAccess | object | ソースワークスペースのロック状態オブジェクト。常にオブジェクトです。同一サイトで確認できる場合は内部フィールドに値が入り、クロスサイトまたは確認できない場合は内部の isLocked/lockMode が null になります。 |
| content[].data[].sourceWorkspaceAccess.isLocked | integer または null | 0 は未ロック、1 はロック、不明は null。 |
| content[].data[].sourceWorkspaceAccess.lockMode | string または null | none/writeLocked/readWriteLocked、不明は null。最終的なクエリは実際の許可/ロックチェックに基づきます。 |
| content[].data[].status | integer | 有効なレコードは 0。 |
| content[].data[].creator | string | 作成者の識別情報。 |
| content[].data[].updator | string | 更新者の識別情報。 |
| content[].data[].createAt | integer | 作成の Unix 秒。 |
| content[].data[].updateAt | integer | 更新の Unix 秒。未更新は -1。 |
| content[].data[].deleteAt | integer | 削除の Unix 秒。未削除は -1。 |
| content[].data[].extra | object | クロスサイト許可の拡張情報。tempAuthCode/tempAuthCodeHash は再帰的に除去され、トップレベルの authorizationCode は返されません。その他の履歴キーはレコードによって存在する場合があります。 |
| content[].data[].extra.recordRole | string | authority(許可の元レコード)または mirror(ミラー)。通常の同一サイトでは省略される場合があります。 |
| content[].data[].extra.grantStatus | string | 拡張状態。トップレベルの出力状態と統一されます。省略可能。 |
| content[].data[].extra.syncStatus | string | 拡張同期状態。省略可能。 |
| content[].data[].extra.lastSyncAt | integer | 最終同期の Unix 秒。省略可能。 |
| content[].data[].extra.lastSyncError | JSON | 直近の同期失敗情報。省略可能であり、今回の HTTP 失敗ではありません。 |
| content[].data[].extra.lastSyncErrorAt | integer | 直近の同期失敗の Unix 秒。省略可能。 |
| content[].data[].extra.tempAuthCodeExpireAt | integer | 履歴の一時許可の有効期限 Unix 秒。省略可能であり、対応するキーは返されません。 |
| content[].data[].extra.resourceSummary | object | クロスサイトミラーのソースリソースサマリー。省略可能。利用可能なカタログは同期状態に依存します。 |
| content[].data[].extra.resourceSummary.データタイプ | object | logging/rum/tracing/metric/lineage/incidents などのカテゴリ別に保存されたサマリー。 |
| content[].data[].extra.resourceSummary.データタイプ.workspaceUUIDs | array<string> |
そのタイプに関係するソースワークスペース UUID の配列。省略可能。 |
| content[].data[].extra.resourceSummary.データタイプ.workspaceUUIDs[] | string | 個々のソースワークスペース UUID。 |
| content[].data[].extra.resourceSummary.データタイプ.indexInfos | array<object> |
ログインデックスのサマリー(履歴の indexes キーが使われる場合もあります)。各項目のフィールドは同期バージョンによります。 |
| content[].data[].extra.resourceSummary.データタイプ.indexInfos[].name | string | インデックス名。 |
| content[].data[].extra.resourceSummary.データタイプ.indexInfos[].uuid | string | インデックス UUID(存在する場合)。 |
| content[].data[].extra.resourceSummary.データタイプ.rumCfgInfos | array<object> |
RUM アプリケーションのサマリー(存在する場合)。 |
| content[].data[].extra.resourceSummary.データタイプ.その他のフィールド | JSON | そのタイプのソースサマリーのその他の公開保存フィールド。本インターフェースで書き込み可能なパラメータではありません。 |
| content[].data[].extra.sourceSite | object | クロスサイトのソース/ターゲットサイト情報。省略される場合があります。 |
| content[].data[].extra.sourceSite.regionCode | string | サイトコード。 |
| content[].data[].extra.sourceSite.siteCode | string | サイト識別子のエイリアス。 |
| content[].data[].extra.sourceSite.issuer | string | 発行者識別子。 |
| content[].data[].extra.sourceSite.baseUrl | string | サイトサービスのルート URL。 |
| content[].data[].extra.sourceSite.jwksUri | string | 公開検証鍵ディレクトリの URL。 |
| content[].data[].extra.sourceSite.kid | string | 署名公開鍵 ID。 |
| content[].data[].extra.sourceSite.name | string | 表示名。空の場合があります。 |
| content[].data[].extra.sourceSite.publicKeys | array | 公開検証情報の配列(レコードに含まれる場合)。秘密鍵ではありません。 |
| content[].data[].extra.sourceSite.publicKeys[] | object | 1 件の公開検証情報。 |
| content[].data[].extra.sourceSite.publicKeys[].kid | string | 公開鍵 ID。 |
| content[].data[].extra.sourceSite.publicKeys[].publicKey | string | 公開検証用の公開鍵の内容。秘密鍵ではありません。 |
| content[].data[].extra.targetSite | object | クロスサイトのソース/ターゲットサイト情報。省略される場合があります。 |
| content[].data[].extra.targetSite.regionCode | string | サイトコード。 |
| content[].data[].extra.targetSite.siteCode | string | サイト識別子のエイリアス。 |
| content[].data[].extra.targetSite.issuer | string | 発行者識別子。 |
| content[].data[].extra.targetSite.baseUrl | string | サイトサービスのルート URL。 |
| content[].data[].extra.targetSite.jwksUri | string | 公開検証鍵ディレクトリの URL。 |
| content[].data[].extra.targetSite.kid | string | 署名公開鍵 ID。 |
| content[].data[].extra.targetSite.name | string | 表示名。空の場合があります。 |
| content[].data[].extra.targetSite.publicKeys | array | 公開検証情報の配列(レコードに含まれる場合)。秘密鍵ではありません。 |
| content[].data[].extra.targetSite.publicKeys[] | object | 1 件の公開検証情報。 |
| content[].data[].extra.targetSite.publicKeys[].kid | string | 公開鍵 ID。 |
| content[].data[].extra.targetSite.publicKeys[].publicKey | string | 公開検証用の公開鍵の内容。秘密鍵ではありません。 |
| content[].data[].extra.resourceSummary.updatedAt | number | サマリーの更新日時。ソースの同期情報から提供され、省略される場合があります。 |
| content[].data[].extra.resourceSummary.sourceGrantUUID | string | ソースサイトの許可レコード UUID。省略可能。 |
| content[].data[].extra.resourceSummary.logging.indexes | array | 現在のクロスサイトミラーで保持されているログインデックスのサマリー。要素はインデックス名またはソースが返すオブジェクトの場合があります。 |
| content[].data[].extra.resourceSummary.logging.indexes[] | string または object | 個々のログインデックス名またはサマリーオブジェクト。固定のオブジェクトフィールドは保証されません。 |
| content[].data[].extra.resourceSummary.rum.applications | array | 現在のクロスサイトミラーで保持されている RUM アプリケーションのサマリー。 |
| content[].data[].extra.resourceSummary.rum.applications[] | string または object | 個々のアプリケーション識別子またはソースサマリーオブジェクト。実際の同期バージョンに応じて解釈します。 |
| content[].pageInfo.pageIndex | integer | そのグループの現在のページ番号。 |
| content[].pageInfo.pageSize | integer | そのグループの 1 ページあたりの件数。 |
| content[].pageInfo.count | integer | そのグループの現在のページの件数。 |
| content[].pageInfo.totalCount | integer | そのグループの有効な許可の総件数。 |
| content[].declaration | object | 現在の呼び出しワークスペースの共通宣言。data の各レコードには挿入されません。 |
{
"code": 200,
"content": [
{
"regionCode": "site_example",
"regionName": "サンプルサイト",
"data": [
{
"id": 10,
"uuid": "grant_example",
"workspaceUUID": "wksp_source_example",
"workspaceName": "production",
"toWorkspaceUUID": "wksp_example",
"toWorkspaceName": "サンプルワークスペース",
"regionCode": "site_example",
"toRegionCode": "site_example",
"regionName": "サンプルサイト",
"toRegionName": "サンプルサイト",
"type": [
"logging",
"tracing"
],
"indexes": [
"default"
],
"conditions": {},
"siteRelationType": "same_site",
"grantMode": "same_site",
"grantStatus": "active",
"syncStatus": "",
"lastSyncAt": null,
"sourceBaseUrl": "",
"targetBaseUrl": "",
"delayDeleteAt": -1,
"sourceWorkspaceAccess": {
"isLocked": 0,
"lockMode": "none"
},
"status": 0,
"creator": "acnt_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"extra": {}
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 100,
"count": 1,
"totalCount": 1
},
"declaration": {}
}
],
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 宣言されていない Query パラメータを使用した、またはパラメータがルールに違反した | パラメータの解析に失敗 | Query パラメータ表と例を確認してください。 |
| 500 | ft.InternalServerError | ワークスペース/サイト/許可設定、データベースまたはキャッシュの読み取り、およびレスポンスのフォーマットに失敗した | 内部エラー | traceId とクエリ条件を保持し、再試行しても失敗が続く場合は管理者に設定の確認を依頼してください。空の結果からサイトにデータがないと推測しないでください。 |