RUM 設定の追加¶
POST /api/v1/rum_cfg/add
概要¶
RUM アプリケーション設定を作成し、クライアント Token の関連付けを確立します。
呼び出し前の準備と使用手順¶
現在の Key には rum.rumCfgManage 権限が必要で、現在のワークスペースのみが対象です。アプリケーションプラットフォーム、表示名、appId を先に決定し、作成後にレスポンスの appId と clientToken の平文をクライアント SDK に設定します。DF-API-KEY はこの管理リクエストにのみ使用し、ブラウザに配布することはできません。
customIdentity は旧互換フィールドです。appId が存在する場合はそちらが優先され(空文字列を含む)、最終的に空の場合にのみ自動生成されます。custom アプリケーションでは、読み取り可能なダッシュボード/組み込みビューを任意で関連付けられます。他のタイプでは dashboardUuids は使用されません。新しい Token 名は RUM- とアプリケーション名から構成されます。明示的な Client Token は、現在のワークスペースの有効な値の再利用、または独立した値の新規作成が可能です。
プリンシパルと Token を先に送信し、その後 RUM データマッピングを非同期で同期します。タスクの投入や下流の失敗は通常、補助状態として記録され、本インターフェースは成功を維持します。HTTP 200 はデータクエリレプリカの準備完了を証明しません。この公開レスポンスは mapping_status などの AIAPI フィールドを返さず、新しい Token がすべての収集ノードで有効になっていることも保証しません。実際の SDK 接続による受け入れ確認が必要です。作成には冪等キーがありません。ネットワーク障害時はまず appId/名前で簡易一覧を検索し、重複作成や新しい認証情報の紛失を避けてください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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取得または入力方法: 呼び出し元の業務情報。 |
|
| appId | string | 任意の文字列で、最大 48 文字です。省略時は customIdentity と互換となり、最終的に空値の場合は appid_ で始まる値が自動生成されます。現在の OpenAPI では AIAPI の英数字とアンダースコアの正規表現を強制していません。SDK/SourceMap との互換性のため、英数字とアンダースコアのみを使用し、パス記号を含めないことを推奨します。 空文字列を許可: True null を許可: False $maxCharacterLength: 48 例: payment_web取得または入力方法: 呼び出し元が SDK で使用する一意のアプリケーション識別子を決定し、事前に簡易一覧で確認します。 |
|
| clientToken | string | 任意の文字列です。作成時に省略または空値の場合は Token が自動生成されます。明示的な値がサイト全体に存在しない場合は現在のワークスペース用に新規作成され、既に存在する場合は有効かつ同じワークスペースである必要があります。データベース上は最大 64 文字で、32 桁のランダムな十六進値を推奨します。変更時に省略または空文字列の場合は元のバインディングを維持し、自動生成やクリアは行いません。空でない値は同じルールで解析/新規作成されます。古い Token の内部 wctn_ UUID を平文として扱わないでください。 空文字列を許可: True null を許可: False 例: <RUM-CLIENT-TOKEN>取得または入力方法: 作成時は省略してサーバー側で生成することを推奨します。再利用が必要な場合は、現在のワークスペースのクライアント Token 管理から有効な Token の平文を取得します。DF-API-KEY や収集 Token で代用することはできません。 |
|
| customIdentity | string | 任意の文字列で、最大 19 文字です。appId キーが完全に省略された場合にのみ候補となります。appId が明示的な空文字列の場合はこの旧フィールドを上書きし、自動生成に切り替わります。appId を優先することを推奨します。 空文字列を許可: True null を許可: False $maxCharacterLength: 19 例: payment_web取得または入力方法: 作成時に任意で指定できる旧互換のアプリケーション識別子で、呼び出し元が決定します。 |
|
| dashboardUuids | array | type=custom の場合にのみ使用されます。作成時に省略または [] の場合はバインディングなしです。変更時に省略した場合は維持し、[] の場合はバインディングをクリアし、指定した場合は全体を置換します。前後の空白を除去したうえで重複を排除します。dsbd_ は同じワークスペースで有効かつ読み取り権限が必要です。itgr_ は現在の言語選択で有効かつ非表示でない組み込みビューである必要があります。作成時に custom 以外の場合はこのリストは無視されます。変更時に custom 以外で明示的に指定すると 400 になります。 null を許可: False 例: ["dsbd_example"]取得または入力方法: ダッシュボード一覧 から dsbd_ UUID を取得するか、組み込みビュー一覧 から itgr_ UUID を取得し、現在のワークスペースで読み取り可能であることを確認します。 |
|
| jsonContent | json | Y | JSON オブジェクト。作成時は必須で、変更時に省略した場合は {} として扱います。内部の name/type/extend はそれぞれパラメータ表に従って処理されます。変更時はフィールド単位で旧 jsonContent をマージしますが、extend が指定された場合はオブジェクト全体を置換し、再帰的にはマージしません。 null を許可: False 例: {"name": "支付Web", "type": "web", "extend": {}}取得または入力方法: アプリケーションの接続方式、表示名、業務表示用の拡張から構成します。 |
| jsonContent.extend | json | 任意の JSON オブジェクトです。null/配列/文字列は宣言により拒否されます。固定の必須サブキーはなく、実行設定や認証情報としては使用されません。作成時に省略した場合はこのキーを補完せず、変更時に省略した場合は保持し、{} の場合はクリアし、指定した場合は全体を置換します。 null を許可: False 例: {"team": "payment"}取得または入力方法: 呼び出し元がアプリケーションの表示/編集用拡張を保存します。変更前に読み取り、保持が必要なキーをコピーしてください。 |
|
| jsonContent.name | string | Y | 作成時は必須の文字列で、最大 256 文字です。変更時に省略した場合は保持されます。同じワークスペース内の有効なアプリケーション名は重複できません。現在の宣言では空でないことを強制していませんが、識別可能な空でない名前の使用を推奨します。 null を許可: False 最大長: 256 例: 支付Web取得または入力方法: アプリケーションの保守担当者が表示名を入力します。 |
| jsonContent.type | string | Y | 作成時は web/miniapp/android/ios/custom/reactnative/harmonyos のいずれかが必須です。変更時は元の型を渡しても 406 NotSupportModifyAppType となるため、完全に省略する必要があります。ルートの列挙で入力可能だからといって、変更可能と判断しないでください。 null を許可: False 選択可能な値: ['web', 'miniapp', 'android', 'ios', 'custom', 'reactnative', 'harmonyos'] 例: web取得または入力方法: SDK/収集プラットフォームに応じて選択します。このパラメータで既存の型を変更することはできません。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_cfg/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"appId":"payment_web","jsonContent":{"name":"支付Web","type":"web","extend":{"team":"payment"}}}'
レスポンス¶
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 | 作成時に有効な Client Token の平文を返します。安全に保存する必要があります。変更レスポンスには互換分岐があるため、該当ページを参照してください。 |
| content.declaration | object | 現在のワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": null,
"uuid": "payment_web",
"appId": "payment_web",
"workspaceUUID": "wksp_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"jsonContent": {
"name": "支付Web",
"type": "web",
"extend": {
"team": "payment"
}
},
"clientToken": "<RUM-CLIENT-TOKEN>",
"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 ファイル形式エラー | jsonContent オブジェクトを含めて送信します。 |
| 400 | ft.SignNameRepeat | カスタム appId/newAppId が現在のワークスペースの有効な設定で既に使用されている | 現在のワークスペースに同名の識別子 payment_web が既に存在します |
簡易一覧で確認し、変更の場合は元の appId を特定します。未使用の識別子を選択してください。 |
| 400 | ft.RumSetNameRepeat | 同じワークスペースの有効なアプリケーションが既にこの名前を使用している | 現在のワークスペースに同名の RUM 設定名 支付Web が既に存在します |
未使用のアプリケーション名を選択します。結果が不明な場合は先に照会し、重複作成しないでください。 |
| 400 | ft.InvalidRumDashboardID | custom の dashboardUuids 項目が不正、欠落、非表示、または読み取り権限なし | カスタム RUM アプリケーションに関連付けられたダッシュボードが無効、またはアクセス権がありません | 現在読み取り可能なダッシュボード/組み込みビュー一覧から有効な UUID を取得します。他のリソース 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 | データベース/Token の作成、ロックサービス、または未処理の設定例外 | 内部エラー | まず appId/名前で簡易一覧を照会し、アプリケーションが作成済みか確認します。管理者が Token と非同期マッピングを確認します。重複作成や認証情報の紛失を避けてください。 |