単一ファイルの内容をアップロード¶
POST /api/v1/rum_sourcemap/upload_file_content
概要¶
指定した環境とバージョン配下に、SourceMap 関連のテキストファイルを 1 つ書き込みます。
呼び出し前と使用手順¶
現在のキーには rum.rumCfgManage が必要です。現在のキーが所属するワークスペースのみが対象です。appId は RUM アプリケーション簡易一覧 の content[].appId から取得し、SDK/エラーレコードの app_id と一致させます。データベース内部の UUID で代用することはできません。SourceMap はアプリケーション、環境 env、バージョン version によって厳密に特定されます。大文字/小文字や空白も識別子自体の一部であるため、収集レコードと完全に一致させる必要があります。env/version を省略するか空文字列にした場合、空の環境/空のバージョンを表し、すべてに一致するワイルドカードではありません。現在のマネージドライフサイクルでは、それぞれ最大 256 文字です。
このエンドポイントは JSON テキストコンテンツを受け取ります。multipart ZIP でも Base64 バイナリでもありません。filename はパッケージ内の相対パスです(例: static/js/app.js.map)。先頭の / は互換性のために除去されますが、..、バックスラッシュ、安全でないリンクは禁止です。常に正規化された相対パスを渡すことを推奨します。content は UTF-8 でそのままエンコードされ、現在のマネージドパスでは先頭と末尾の空白/改行が保持されます。JSON 文字列を再デコードしてファイルオブジェクトにすることはありません。content を省略すると空文字列が書き込まれ、成功したからといってファイルが解析可能であることを証明するものではありません。
同名ファイルが既に存在する場合、そのファイルは置き換えられ、その他のファイルは保持されます。複数ファイルは 1 つずつアップロードできますが、原子的な一括リリースではないため、その間に読み取るとリリース済みのサブセットが見える可能性があります。単一ファイルおよびそのバージョンで集計済みの総容量はサイトの制限(デフォルト 2 GiB)を受けます。ビルド成果物の一貫性を保つため、ZIP による一括アップロードを推奨します。Web/RN では、実際のビルドで生成された .map および必要なソース/JS をアップロードしてください。Android/iOS のネイティブバイナリシンボルは ZIP フローにより適しています。
成功時の true は、今回のファイル書き込みが確認されたことを示します。後続のインデックス作成/安定化期間/クリーンアップからの復旧は非同期で完了する場合があります。操作失敗時でも uploadCommitted=true が付く場合があるため、リリース済みと確認された書き込みを再実行しないでください。409 で所有権/復旧が未確認の場合は、traceId を保持して管理者に処理を依頼し、占有状態を削除したり、やみくもに再送信したりしないでください。完了後はファイルツリーで照合し、スタック解析で実際に一致するか検証してください。一覧にレコードがあることを map 内容が正しいことと同一視しないでください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API キー管理から、この操作権限を持つ OpenAPI キーを取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| appId | string | Y | 必須。現在のワークスペースで有効なアプリケーション識別子です。内部の RumCfg UUID ではなく、ワークスペースをまたいで使用できません。 null 許可: False 例: payment_web取得または入力方法: RUM アプリケーション簡易一覧 の content[].appId またはエラーレコードの app_id から取得します。 |
| content | string | 任意の文字列。省略時は空文字列となり、元の UTF-8 テキストを保持します。Base64 デコードは行いません。空の map のアップロードは推奨しません。 空文字列許可: True null 許可: False 例: {"version":3,"sources":["app.ts"],"names":[],"mappings":"AAAA","sourcesContent":["console.log(1);"]}取得または入力方法: そのバージョンのビルドで生成されたテキスト SourceMap の内容を読み取り、JSON 文字列としてシリアライズします。 |
|
| env | string | 任意の文字列。デフォルトは空の環境で、最大 256 文字です。すべての環境を表すものではありません。null は許可されません。 空文字列許可: True null 許可: False 例: production取得または入力方法: クライアントのリリース環境/エラーレコードの env から取得し、アップロード時と文字単位で一致させます。 |
|
| filename | string | Y | 必須。空でない有効な相対ファイルパスです。POSIX の / 区切りを推奨します。先頭の / は互換性のために除去されます。パス内の ..、バックスラッシュ/リンクなどは拒否されます。クライアントの絶対ディスクパスは渡せません。 空文字列許可: True null 許可: False 例: static/js/app.js.map取得または入力方法: ビルド成果物の相対パスおよびエラースタックのソース URL パスから決定します。 |
| version | string | 任意の文字列。デフォルトは空のバージョンで、最大 256 文字です。最新/すべてのバージョンを表すものではありません。null は許可されません。 空文字列許可: True null 許可: False 例: 1.2.3取得または入力方法: クライアントで実際にリリースされたバージョン/エラーレコードの version から取得し、ビルド成果物に対応させます。 |
パラメータ補足説明¶
注: 同じアプリケーション配下では、同じ version、env の sourcemap は 1 つだけ存在できます。アップロードされたファイルの内容は対象ファイルを直接上書きします。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/upload_file_content' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"appId":"payment_web","env":"production","version":"1.2.3","filename":"static/js/app.js.map","content":"{\"version\":3,\"sources\":[\"app.ts\"],\"names\":[],\"mappings\":\"AAAA\",\"sourcesContent\":[\"console.log(1);\"]}"}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | 成功時は固定で true。単一ファイルのリリースは確認済みですが、非同期の最終インデックス/安定状態は引き続き確認が必要です。 |
| 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": true,
"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/filename を含むオブジェクトを送信してください。 |
| 404 | ft.NotFoundRumSet | アプリケーションが現在のワークスペースにない、削除済み、または存在しない | 指定された RUM 設定が見つかりません | RUM アプリケーション簡易一覧を更新し、現在のワークスペースの実際の appId を使用してください。 |
| 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.SourceMapUploadTooLarge | 単一ファイルまたは集計済みバージョンの総容量がサイト制限(デフォルト 2147483648 バイト)を超えています | SourceMap の今回のアップロードまたは集計済みバージョン容量が制限を超えています(具体的なバイト数は content を参照)。 | その環境/バージョンのファイル総量を減らすか、content.actualBytes/maxBytes を読み取るか、管理者に制限の確認を依頼してください。 |
| 500 | ft.InternalServerError | データベース、Redis、ストレージの読み書き、キュー、または未処理のシステム例外 | 内部エラー | traceId、アプリケーション/env/version/uploadId を保持し、まず一覧/ファイルツリーを確認してください。失敗時には既にファイルがリリースされているか、処理マークが付いている可能性があるため、やみくもに再度上書き/削除しないでください。 |