コンテンツにスキップ

参照可能なワークスペース一覧



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 とクエリ条件を保持し、再試行しても失敗が続く場合は管理者に設定の確認を依頼してください。空の結果からサイトにデータがないと推測しないでください。

フィードバック

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