コンテンツにスキップ

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 を保持して管理者に確認を依頼してください。

フィードバック

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