RUM 設定の変更¶
POST /api/v1/rum_cfg/{appid}/modify
概要¶
RUM アプリケーションの表示設定、識別子、または Client Token のバインドを変更します。
呼び出し前の確認と使用手順¶
現在のキーには rum.rumCfgManage が必要です。パスの appid は簡易一覧の appId/uuid から取得します。事前に存在を確認する必要があり、変更 API で存在を確認しないでください。
jsonContent は name/extend 単位でマージされます。type は完全に省略する必要があり、元の値を渡した場合も 406 になります。extend が存在する場合はオブジェクト全体が置換され、{} でクリア、省略時は保持されます。jsonContent={} または Body 全体が {} の場合でも、更新時刻は更新され、マッピング同期が実行されます。newAppId は省略または空値の場合は変更されません。非空で名前を変更する場合は、SDK/SourceMap/外部リンクの変更を同時に計画する必要があり、既存の履歴データはこの API によって一括で書き換えられません。custom アプリケーションの dashboardUuids は全量置換され、[] でクリア、省略時は保持されます。名前変更のみの場合は、元のバインドを保持して移行します。
clientToken は省略または空値の場合、元の関連付けが保持されます。このときレスポンスの content.clientToken は旧内部関連付け UUID(wctn_)であり、SDK に直接設定できません。明示的な非空値が検証を通過した場合に限り、レスポンスでその平文が返されます。バインドを変更しても旧 Token は失効しません。旧 Token は他のアプリケーションで使用されている可能性があります。アプリケーションの関連付けの置換を、認証情報の失効と同一視しないでください。
ローカルでコミットされた後にマッピングが同期されます。下流またはキューの失敗は許容されて成功として返される場合があり、mapping_ready などの AIAPI 付加情報は返されません。失敗またはタイムアウト時は、まず簡易一覧で新旧の appId と jsonContent を照合し、その後管理者に Token/マッピングを確認してもらってください。盲目的に繰り返し変更しないでください。対象が存在せず dashboardUuids を渡していない場合、現在は空オブジェクトの読み取りにより 500 になることがあります。明示的に dashboardUuids を指定した分岐では先に NotFoundRumSet が返されます。いずれの場合も、まず一覧を更新してください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| appid | string | Y | 現在のワークスペースで公開されているアプリケーション識別子です。データベース上の実際の RumCfg UUID ではありません。SDK 設定および SourceMap リクエストに使用されます。 例: payment_web取得または入力方法: RUM アプリケーション簡易一覧から content[].appId を取得するか(uuid も同じ値)、現在のワークスペースの RUM アプリケーション設定から取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報です。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| dashboardUuids[*] | string | 単一の dsbd_ または itgr_ 識別子文字列です。 例: dsbd_example取得または入力方法: ダッシュボード一覧から dsbd_ UUID を取得するか、組み込みビュー一覧から itgr_ UUID を取得し、現在のワークスペースで読み取り可能であることを確認します。 |
|
| jsonContent.extend.カスタムキー | any | 動的な JSON 値です。オブジェクト/配列/文字列/数値/真偽値/null が可能で、文字列に限定されません。公開された固定機能のセマンティクスはないため、機密認証情報を保存しないでください。 例: payment取得または入力方法: 呼び出し元の業務資料です。 |
|
| clientToken | string | 任意の文字列です。作成時に省略または空値の場合は Token が自動生成されます。明示的な値がサイト全体に存在しない場合は現在のワークスペース用に新規作成され、既に存在する場合はアクティブかつ同一ワークスペースである必要があります。データベース上は最大 64 文字で、32 桁のランダムな 16 進数を推奨します。変更時に省略または空文字列の場合は元のバインドが保持され、自動生成もクリアもされません。非空値は同じルールで解決/新規作成されます。旧 Token の内部 wctn_ UUID を平文として扱わないでください。空文字列を許可: True null を許可: False 例: <RUM-CLIENT-TOKEN>取得または入力方法: 作成時は省略してサーバー側で生成することを推奨します。再利用する場合は、現在のワークスペースの Client Token 管理からアクティブな Token の平文を取得します。DF-API-KEY や収集 Token で代用できません。 |
|
| dashboardUuids | array | type=custom の場合にのみ使用します。作成時に省略または [] の場合はバインドなしです。変更時に省略の場合は保持、[] の場合はクリア、存在する場合は全量置換され、前後の空白を除去した後に重複排除されます。dsbd_ は同一ワークスペースでアクティブかつ読み取り権限が必要です。itgr_ は現在の言語選択で有効かつ非表示でない組み込みビューである必要があります。作成時に非 custom の場合、このリストは無視されます。変更時に非 custom で明示的に指定した場合は 400 になります。null を許可: False 例: ["dsbd_example"]取得または入力方法: ダッシュボード一覧から dsbd_ UUID を取得するか、組み込みビュー一覧から itgr_ UUID を取得し、現在のワークスペースで読み取り可能であることを確認します。 |
|
| jsonContent | json | JSON オブジェクトです。作成時は必須で、変更時に省略した場合は {} として扱われます。内部の name/type/extend はそれぞれパラメータ表に従って処理されます。変更時はフィールド単位で旧 jsonContent がマージされますが、extend が存在する場合はオブジェクト全体が置換され、再帰的にはマージされません。例: {"name": "支付Web", "type": "web", "extend": {}}取得または入力方法: アプリケーションの接続方式、表示名、業務表示拡張から構築します。 |
|
| jsonContent.extend | json | 任意の JSON オブジェクトです。null/配列/文字列は宣言により拒否されます。固定の必須サブキーはなく、実行設定や認証情報としては使用されません。作成時に省略した場合はこのキーは追加されません。変更時に省略の場合は保持、{} の場合はクリア、存在する場合は全体置換されます。null を許可: False 例: {"team": "payment"}取得または入力方法: 呼び出し元がアプリケーションの表示/編集拡張を保存します。変更前に読み取り、保持が必要なキーをコピーしてください。 |
|
| jsonContent.name | string | 作成時は必須の文字列で、最大 256 文字です。変更時に省略した場合は保持されます。同一ワークスペース内のアクティブなアプリケーション名と重複できません。現在の宣言では非空を強制していませんが、識別可能な非空の名前を使用することを推奨します。 null を許可: False 最大長: 256 例: 支付Web取得または入力方法: アプリケーションの保守担当者が表示名を入力します。 |
|
| jsonContent.type | string | 作成時は web/miniapp/android/ios/custom/reactnative/harmonyos のいずれかが必須です。変更時は元の型を渡した場合でも 406 NotSupportModifyAppType になるため、完全に省略する必要があります。ルートの列挙値に含まれているからといって、変更可能と判断しないでください。 null を許可: False 選択可能な値: ['web', 'miniapp', 'android', 'ios', 'custom', 'reactnative', 'harmonyos'] 例: web取得または入力方法: SDK/収集プラットフォームに応じて選択します。このパラメータで既存の型を変更することはできません。 |
|
| newAppId | string | 任意で最大 48 文字です。省略または空文字列の場合は保持され、非空の場合は公開識別子を変更します。SDK、SourceMap などの参照を同時に更新する必要があります。内部の実際の UUID は保持され、コントローラーは RUM Trace 設定と custom バインドを移行します。名前変更を履歴テレメトリデータの書き換えとして扱いません。 空文字列を許可: True null を許可: False $maxCharacterLength: 48 例: payment_web_v2取得または入力方法: アプリケーション接続の移行計画に従って選択し、事前に同一ワークスペース内で識別子が使用されていないか確認します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_cfg/payment_web/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"jsonContent":{"name":"支付Web新名称"}}'
レスポンス¶
HTTP 200、application/json。以下の例は、そのまま読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | データベース行 ID です。作成時はコミット前スナップショットを返すため null になることがあり、公開識別子として使用しません。 |
| content.uuid | string | 公開互換エイリアスで、常に appId と等しく、内部の実際の RumCfg UUID ではありません。 |
| content.appId | string | SDK/クエリで使用するアプリケーション識別子です。 |
| content.workspaceUUID | string | 所属ワークスペースの UUID です。 |
| content.status | integer | データベースのステータスです。アクティブは通常 0、削除済みの 3 は簡易一覧に表示されません。 |
| content.creator | string | 作成主体です。OpenAPI では通常 Key リソースの UUID です。 |
| content.updator | string | 最終更新主体です。作成後に未更新の場合は空になることがあります。 |
| content.createAt | integer | Unix 秒の作成時刻です。 |
| content.updateAt | integer | Unix 秒の更新時刻です。作成後に未更新の場合は -1 になることがあります。 |
| content.deleteAt | integer | Unix 秒の削除時刻です。正常時は -1 です。 |
| content.jsonContent | object | アプリケーション内容オブジェクトです。 |
| content.jsonContent.name | string | アプリケーションの表示名です。 |
| content.jsonContent.type | string | web/miniapp/android/ios/custom/reactnative/harmonyos。 |
| content.jsonContent.extend | object | 任意で保存される動的拡張です。存在しない場合はこのキーを省略できます。 |
| content.jsonContent.extend.カスタムキー | JSON | 呼び出し元が保存した拡張キーと値です。サーバーが追加の実行パラメータをサポートすることを意味しません。 |
| content.clientToken | string | 明示的な非空の clientToken が検証を通過した場合は平文です。省略または空値で保持された場合は内部 Token UUID(wctn_)であり、SDK 認証情報として使用できません。 |
| content.declaration | object | 現在のワークスペースの公開宣言です。 |
{
"code": 200,
"content": {
"id": 123,
"uuid": "payment_web",
"appId": "payment_web",
"workspaceUUID": "wksp_example",
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427260,
"deleteAt": -1,
"jsonContent": {
"name": "支付Web新名称",
"type": "web",
"extend": {
"team": "payment"
}
},
"clientToken": "wctn_example",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、および共通リクエストエラーについては、共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたは応答説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認します。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正します。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではない | 一部の json ファイル形式エラー | オブジェクトを送信します。 |
| 406 | ft.NotSupportModifyAppType | jsonContent に type キーが存在する(元の型であっても) | 既存アプリケーションのアプリケーションタイプ変更は現在サポートされていません | type を完全に省略します。別のプラットフォームが必要な場合は別のアプリケーションを作成します。 |
| 404 | ft.NotFoundRumSet | dashboardUuids を明示的に指定した場合に対象アプリケーションが存在しない/削除済み/ワークスペースが異なる | 指定された RUM 設定が見つかりません | 現在のワークスペースの簡易一覧から存在する appId を取得します。 |
| 400 | ft.SignNameRepeat | カスタム appId/newAppId が現在のワークスペースのアクティブ設定で既に使用されている | 現在のワークスペースに同名の識別子payment_webが既に存在します |
簡易一覧で確認し、変更時は元の appId を特定します。未使用の識別子を選択してください。 |
| 400 | ft.RumSetNameRepeat | 同一ワークスペースのアクティブなアプリケーションが既にその名前を使用している | 現在のワークスペースに同名の RUM 設定名支付Webが既に存在します |
未使用のアプリケーション名を選択します。結果が不明な場合は先に照会し、重複作成しないでください。 |
| 400 | ft.InvalidRumDashboardID | 非 custom アプリケーションに dashboardUuids を渡した、または custom ビュー識別子が無効/アクセス権なし | カスタム RUM アプリケーションに関連付けられたダッシュボードが無効、またはアクセス権がありません | custom アプリケーションのみバインドを更新できます。読み取り可能な UUID を確認してください。 |
| 400 | ft.RumClientTokenUnavailable | 明示的に指定した Client Token は存在するがステータスがアクティブでない | この Client Token は利用できません。交換または再生成してください | 現在のワークスペースのアクティブな Token を選択するか、作成時に省略して自動生成します。失効済みの値を再利用しないでください。 |
| 400 | ft.RumClientTokenWorkspaceMismatch | 明示的な Token が他のワークスペースで既に使用されている | この Client Token は他のワークスペースで既に使用されています。交換または再生成してください | 現在のワークスペース専用の Token を使用し、他のワークスペースの収集認証情報をコピーしないでください。 |
| 429 | ft.OperationTooFrequently | 現在のワークスペースで他の RUM 作成/変更/削除/Token 操作が書き込みロックを保持しており、5 秒以内に取得できなかった | 操作が頻繁すぎます。しばらくしてから再試行してください | 他の操作の終了を待ってバックオフします。現在の状態を読み戻してから再試行し、並行して変更しないでください。 |
| 500 | ft.InternalServerError | データベース/ロックサービス、履歴設定の形式、または未処理のシステム例外。存在しないアプリケーションを変更し dashboardUuids を渡していない場合も、空オブジェクトへのアクセスにより 500 になることがある | 内部エラー | まず現在のワークスペースのアプリケーション簡易一覧で実際の設定を確認します。書き込みが既にコミットされている可能性があるため、重複作成や Token の繰り返し変更を避け、traceId を保持して管理者に確認を依頼してください。 |