ファイルツリーの一覧取得¶
POST /api/v1/rum_sourcemap/file_tree
概要¶
指定した SourceMap バージョンの相対ファイル名とディレクトリ名を一覧表示します。
呼び出し前の前提と使用手順¶
Key は routine.defaultAccess または rum.rumCfgManage のいずれかに一致する必要があります。現在の Key が属するワークスペースのみが対象です。appId は RUMアプリ簡易一覧 の content[].appId から取得し、SDK/エラーレコードの app_id と一致している必要があり、データベース内部の UUID で代用することはできません。SourceMap はアプリケーション、環境 env、バージョン version によって厳密に特定されます。大文字小文字や空白も識別子そのものであるため、収集レコードと完全に一致させる必要があります。env/version を省略するか空文字列にした場合は空の環境/空のバージョンを意味し、すべてに一致するワイルドカードではありません。現在の管理ライフサイクルでは、それぞれ最大 256 文字であることが要求されます。
POST JSON で正確な環境/バージョンを指定します。保護されたローカルスナップショットを読み取り、ready/settling および一部の履歴時刻異常だが読み取り可能な blocked バージョンは返却できます。その他の未準備/ファイル欠落は 404 と reasonCode で説明されます。新規アップロードがまだ processing の場合、以前のマージ成功を根拠に読み取ることはできません。
辞書順にソートされた相対パス文字列を返します。ディレクトリは / で終わり、ネストしたツリーではありません。ファイル内容、サイズ、ダウンロード URL、MD5 は返しません。ZIP のルートディレクトリ階層とスタック URL パスが一致するかの確認に使用します。[] は現在返却されたエントリがないことのみを示し、完全な解析の受け入れ確認の代わりにはなりません。履歴のディレクトリ一覧取得異常もフォールトトレラントで空になる場合があります。
リクエストヘッダ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| appId | string | Y | 現在のワークスペースで有効なアプリケーション識別子を必須指定します。内部の RumCfg UUID ではなく、ワークスペースを跨いで使用することはできません。 null 許可: False 例: payment_web取得または入力方法: RUMアプリ簡易一覧 の content[].appId またはエラーレコードの app_id から取得します。 |
| env | string | オプションの文字列で、デフォルトは空の環境、最大 256 文字です。すべての環境を表すものではなく、null は許可されません。 空文字列許可: True null 許可: False 例: production取得または入力方法: クライアントのリリース環境/エラーレコードの env から取得し、アップロード時と一字一句一致させます。 |
|
| version | string | オプションの文字列で、デフォルトは空のバージョン、最大 256 文字です。最新/すべてのバージョンを表すものではなく、null は許可されません。 空文字列許可: True null 許可: False 例: 1.2.3取得または入力方法: クライアントの実際のリリースバージョン/エラーレコードの version から取得し、ビルド成果物に対応させます。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/file_tree' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"appId":"payment_web","env":"production","version":"1.2.3"}'
レスポンス¶
HTTP 200、application/json。以下の例はそのまま読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | array<string> |
辞書順の相対パスリスト。結果が空の場合は []。 |
| content[] | string | ファイルの相対パス、または / で終わるディレクトリの相対パス。 |
| content.reasonCode | string | エラー応答時のみ: 機械可読な理由。例: active_operation/invalid_scope/registry_missing。 |
| content.action | string | エラー応答時のみ: 推奨アクション。例: retry_after_operation/verify_ownership/check_scope_and_upload。 |
| content.retryable | boolean | エラー応答時のみ: サーバーが推奨する再試行可能フラグ。これのみを根拠に公開済みの書き込みを再生することはできません。 |
| content.uploadCommitted | boolean | 一部の単一ファイルエラー診断時のみ: true は当該書き込みが公開済みであることを示します。省略は false や未書き込みの確認を意味しません。 |
| content.actualBytes | integer | 一部の容量エラーのみ: 集計済みバイト数。 |
| content.maxBytes | integer | 容量/読み取り制限のバイト数。 |
| content.workspaceUUID | string | 一部エラーの制限付き診断: 現在のワークスペース UUID。 |
| content.appId | string | 一部エラーの制限付き診断: 公開アプリケーション識別子。 |
| content.rumCfgUUID | string | 一部エラーの制限付き診断: 内部アプリケーション識別子。サポート調査にのみ使用し、リクエストの appId を置き換えるものではありません。 |
| content.env | string | 一部エラー診断: 環境。 |
| content.version | string | 一部エラー診断: バージョン。 |
| content.bundleUUID | string | 一部エラー診断: 今回の世代レコード ID。uploadId ではありません。 |
| content.state | string | 一部エラー診断: 世代状態。 |
| content.resource | string | 一部の占有診断: リソースタイプ。例: application/bundle。 |
| content.shared | boolean | 一部の占有診断: 共有アクセスかどうか。 |
| content.waitedSeconds | number | 一部の占有診断: 待機済み秒数。 |
| content.waitSeconds | number | 一部の占有診断: 待機可能な秒数。 |
| content.waitExhausted | boolean | 一部の占有診断: 今回の待機が枯渇したか。 |
| content.elapsedSeconds | number | 一部の単一ファイルエラー診断: 操作の所要秒数。 |
| content.phase | string | 一部エラー診断: 失敗フェーズ。 |
| content.phaseElapsedSeconds | number | 一部エラー診断: フェーズ所要秒数。 |
{
"code": 200,
"content": [
"static/",
"static/js/",
"static/js/app.js.map"
],
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
ストレージライフサイクルは互換性のためのエラーコードを維持しています。409 は通常依然として ft.InvalidAction であり、ローカライズされた message と content.reasonCode で理由をさらに区別します。message 名 SourceMapOperationBusy などを errorCode とみなすことはできません。読み取り時のパッケージ欠落/処理中/利用不可は通常 404 ft.SourceMapPackageNotFound です。具体的な理由は reasonCode を参照してください。retryable=true が明示的に返され、かつ現在の状態が許可する場合にのみバックオフして再試行してください。uploadCommitted=true の場合は、公開が確認された書き込みを再生できません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータの解析に失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではない | 一部の json ファイルの形式エラー | appId/env/version のオブジェクトを送信してください。 |
| 404 | ft.NotFoundRumSet | アプリケーションが現在のワークスペースにない、削除済み、または存在しない | 指定された RUM 設定が見つかりません | RUMアプリ簡易一覧を更新し、現在のワークスペースの実際の appId を使用してください。 |
| 404 | ft.SourceMapPackageNotFound | 選択した環境/バージョンにレコードがない、まだ処理中、読み取り不可、または必要なソースファイルが欠落 | reasonCode に応じて、レコード未検出/処理中/読み取り不可/ソースファイル不存在などのローカライズされたメッセージを返します | 正確な appId/env/version を確認してください。registry_missing は未アップロードか、bundle_processing は待機、bundle_unavailable/source_files_missing は状態とファイルを確認します。すべての 404 を未アップロードとみなさないでください。 |
| 409 | ft.InvalidAction | アップロード/読み取り/クリーンアップの競合、旧ディレクトリの引き継ぎ未完了、帰属/復旧の検証待ち、または環境/バージョンがライフサイクルの許容範囲を超えている | reasonCode に応じて具体的なローカライズメッセージを返します。たとえば SourceMap が他のアップロード、読み取り、またはクリーンアップ操作で使用中であるなど | content.reasonCode/action/retryable を確認します。active_operation/active_upload などは案内に従ってバックオフし、owner_recovery_required/ownership_verification_required/legacy_invalid などはまず管理者に検証を依頼し、占有レコードを独自に削除したり強制上書きしたりしないでください。invalid_scope の場合は env/version が最大 256 文字であることを確認してください。 |
| 406 | ft.InvalidFileName | ファイルの相対パス、シンボリックリンク、または履歴公開パスが安全でない | SourceMap ファイルのパスが要件を満たしていないか、サポートされていないリンクが含まれています。アップロードファイルの相対パスとディレクトリ構造を確認してください。 | パッケージ内の正当な相対パスを使用し、..、バックスラッシュ、絶対パス/シンボリックリンクを含めないでください。reasonCode=invalid_path を確認します。 |
| 413 | ft.SourceMapSnapshotTooLarge | 読み取りに必要なファイルスナップショットのサイズがサイト制限(デフォルト 2GiB)を超えている | 今回の SourceMap 読み取りに必要なファイルの合計サイズが制限を超えています | このバージョンのファイル数を減らすか、管理者に制限を確認してもらってください。繰り返し読み取ることで制限を回避しないでください。 |
| 500 | ft.InternalServerError | データベース、ファイル読み取り/スナップショット、履歴設定、または未処理の解析例外 | 内部エラー | traceId とアプリケーション/env/version を保持し、まずバージョン状態とファイルを確認してから実際のエラーに応じて対処してください。読み取りはバックオフして再試行できます。 |