【モバイル Synthetic テスト】ノード選択テンプレートを保存¶
POST /api/v1/dialing_task/mobile/templates/save
概要¶
モバイル Synthetic テストのノード選択テンプレートスナップショットを作成または全体更新します。
呼び出し前の準備と使用手順¶
templateUUID を省略すると作成し、空でない場合は同一ワークスペースに既存のテンプレートを更新します。最大 100 個で、既存テンプレートの更新では件数は増えません。name/nodeSelection はどちらも必須で、全体を置き換え、リーフフィールド単位のマージは行いません。nodes は ID 構造のみを検査して元の ID/順序を保持し、存在や静的マッピングをリアルタイムに確認しません。groups はグループとメンバーをリアルタイムに照会し、存在しない場合、空のグループ、メンバーが現在のノード集合にない場合は失敗します。
テンプレートの保存では、タスクは作成されず、Synthetic テストは実行されず、同じ選択を参照する既存タスクが一括変更されることもありません。テンプレートの保存自体にはモバイル Synthetic テスト規約への同意は不要ですが、サービスが現在有効で書き込み権限が必要です。ワークスペースの相互排他とトランザクションを使用し、エラー時はまず一覧/get で保存済みか確認してください。成功レスポンスの静的マッピング組み立てはコミット後に行われるため、最終的に 500 でも保存済みの場合があります。重複して作成しないでください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| nodeSelection.mode | string | mobile 必須。nodes はノードを指定し、groups はノードグループを指定します。 例: nodes取得または入力方法: モバイルリソース/テンプレートから読み取って選択します。 |
|
| nodeSelection.ids | array | mobile 必須。空でなく一意の文字列配列で、対応するリソース id を取得します。region UUID ではありません。 例: ["NODE-ID"]取得または入力方法: モバイルリソース/テンプレートから読み取って選択します。 |
|
| nodeSelection.ids[*] | string | mobile 必須。単一の現在のノードまたはグループ id で、nodes は英数字、アンダースコア、ハイフンのみです。 例: NODE-ID取得または入力方法: モバイルリソース/テンプレートから読み取って選択します。 |
|
| nodeSelection.sampleCount | integer | mobile 必須。各ノードで独立にサンプリングする回数は 1..5 で、選択したノード/グループメンバー数に制限されません。 例: 1取得または入力方法: モバイルリソース/テンプレートから読み取って選択します。 |
|
| name | string | Y | 必須。trim 後が空でなく 256 文字以下で、名称は空白除去後に同一ワークスペース内で一意です。古い空白付き名称で回避することはできません。 例: 生产节点取得または入力方法: 業務担当者が現在のワークスペースで一意のテンプレート名を定義します。 |
| nodeSelection | json | Y | mobile 必須で、mode/ids/sampleCount の 3 つのキーのみを持ちます。スナップショットを保存し、テンプレートを動的に追従しません。nodes は ID 構造のみを検証して元の ID/順序を保持し、リアルタイムの存在やマッピング済みであることを保証しません。groups は現在のグループとメンバーを照会し、ノード集合を照合します。 例: {"mode": "nodes", "ids": ["NODE-ID"], "sampleCount": 1}取得または入力方法: nodes はモバイルリソースからノード ID を取得します。groups は現在、既存の同一ワークスペースのテンプレートまたは管理者が確認したグループレコードから ID を取得する必要があります(リソース入口では現在グループを取得しません)。ノード選択テンプレートのスナップショットを再利用することもできます。 |
| templateUUID | string | 任意。省略または空文字列の場合は作成し、空でない場合は指定した既存テンプレートを更新します。ワークスペースを跨いだり、存在しない新しい UUID を指定したりすることはできません。 例: dsel_example取得または入力方法: 更新時は現在のワークスペースのテンプレート一覧から templateUUID を取得します。 |
パラメータ補足説明¶
返される各テンプレート項目には selectedNodeMappings 配列が付属し、要素は resources.nodes[].mapping を再利用します。nodeId:string、continent/country/province/city/operator:{code,zh,en}|null、network/client_type:string です。 nodeSelection.ids の現在のデータベース表示マッピングのみを取得し、ID を文字列に変換して重複を除去し、見つからない場合はスキップします。マッピングがない場合または groups モードの場合は [] を返します。表示情報はリアルタイムに利用可能であることを示すものではなく、一覧バッチではマッピングを 1 回だけ読み取ります。 このフィールドは読み取り専用で永続化されず、保存時に返送しないでください。元のリアルタイムリソースと選択有効性の検証は維持されます。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/dialing_task/mobile/templates/save' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"生产节点","nodeSelection":{"mode":"nodes","ids":["NODE-ID"],"sampleCount":1}}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.templateUUID | string | dsel_ ワークスペース内のテンプレート UUID で、タスクまたはノード ID ではありません。 |
| content.name | string | trim 後のテンプレート名。 |
| content.nodeSelection | object | 保存されたノード選択スナップショット。タスクにコピーされ、リアルタイム参照ではありません。 |
| content.nodeSelection.mode | string | nodes/groups。 |
| content.nodeSelection.ids | array<string> | 空でなく重複のない元のノードまたはグループ ID 配列。保存前に重複を拒否し、元の ID/順序を保持し、region UUID は渡せません。 |
| content.nodeSelection.ids[] | string | 対応するリソース id。 |
| content.nodeSelection.sampleCount | integer | 各ノードで独立にサンプリングする回数 1..5。 |
| content.selectedNodeMappings | array<object> | nodes のみの選択済み静的マッピング。リアルタイムの可用性は照会しません。欠落時または groups 時は []。 |
| content.selectedNodeMappings[].nodeId | string | ノード文字列 ID。 |
| content.selectedNodeMappings[].network | string | 静的ネットワークタイプ。 |
| content.selectedNodeMappings[].client_type | string | 静的クライアントタイプ。 |
| content.selectedNodeMappings[].continent | object または null | 静的な地域/キャリアラベル。province は null の可能性があります。 |
| content.selectedNodeMappings[].continent.code | string | 取得元コード。 |
| content.selectedNodeMappings[].continent.zh | string | 中国語名。 |
| content.selectedNodeMappings[].continent.en | string | 英語名。 |
| content.selectedNodeMappings[].country | object または null | 静的な地域/キャリアラベル。province は null の可能性があります。 |
| content.selectedNodeMappings[].country.code | string | 取得元コード。 |
| content.selectedNodeMappings[].country.zh | string | 中国語名。 |
| content.selectedNodeMappings[].country.en | string | 英語名。 |
| content.selectedNodeMappings[].province | object または null | 静的な地域/キャリアラベル。province は null の可能性があります。 |
| content.selectedNodeMappings[].province.code | string | 取得元コード。 |
| content.selectedNodeMappings[].province.zh | string | 中国語名。 |
| content.selectedNodeMappings[].province.en | string | 英語名。 |
| content.selectedNodeMappings[].city | object または null | 静的な地域/キャリアラベル。province は null の可能性があります。 |
| content.selectedNodeMappings[].city.code | string | 取得元コード。 |
| content.selectedNodeMappings[].city.zh | string | 中国語名。 |
| content.selectedNodeMappings[].city.en | string | 英語名。 |
| content.selectedNodeMappings[].operator | object または null | 静的な地域/キャリアラベル。province は null の可能性があります。 |
| content.selectedNodeMappings[].operator.code | string | 取得元コード。 |
| content.selectedNodeMappings[].operator.zh | string | 中国語名。 |
| content.selectedNodeMappings[].operator.en | string | 英語名。 |
| content.declaration | object | 共通宣言。 |
{
"code": 200,
"content": {
"templateUUID": "dsel_example",
"name": "生产节点",
"nodeSelection": {
"mode": "nodes",
"ids": [
"NODE-ID"
],
"sampleCount": 1
},
"selectedNodeMappings": [],
"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 | Body が JSON オブジェクトではない | 一部の json ファイル形式エラー | 完全な name/nodeSelection オブジェクトを送信してください。 |
| 400 | ft.ParamsValidateError | 識別子、ノード選択構造/範囲、名称、テンプレート数、またはプロトコルパラメータが現在の契約に適合しない | パラメータ検証失敗: {} | message と任意の content.reason/field に従って修正し、まず現在のワークスペースの一覧から対象を再取得してください。 |
| 400 | ft.InvalidAction | モバイル Synthetic テストが現在有効でない、または許可されない操作/トランザクション状態が存在する | 無効な操作 | 管理者がモバイル Synthetic テスト機能を確認してください。テンプレートの読み取り/削除はスイッチがオフでも自動的に禁止されません。 |
| 400 | ft.DialingServerError | モバイルサービス呼び出しの失敗、リソースの返却形状/バインディング情報の不一致 | テストサービスインターフェースの呼び出し失敗 | reason、outcomeUnknown を確認し、traceId と併せて照合してください。静的マッピングの欠落で上流の失敗を覆い隠すことはできません。 |
| 409 | ft.MobileDialingOperationBusy | ワークスペース相互排他ロックの待機がタイムアウトし、今回実行されなかった | 現在のワークスペースで他の操作が進行中です。今回の操作は実行されていません。しばらくしてから再試行してください。 | operationExecuted=false/retryable=true の場合はバックオフ後に再試行し、並行して上書きしないでください。 |
| 401 | ft.WKSPNotExistOrReleased | 待機後にワークスペースが存在しない/解放済み | ワークスペースが存在しない/または解放済み | 再試行を停止し、有効なワークスペースを確認してください。 |
| 403 | ft.WorkspaceIsLocked | 待機後にワークスペースがロックされている | ワークスペースがロックされているため操作できません | ロック解除と操作可能な状態を確認してください。 |
| 406 | ft.NotFoundWorkspace | 保存時のロック取得でワークスペースレコードが存在しない | 指定されたワークスペースが見つかりません | 有効なワークスペースを確認してください。 |
| 500 | ft.InternalServerError | ストレージ読み取り、履歴設定、またはローカル静的マッピングのフォーマット異常 | 内部エラー | 具体的なタスク/テンプレートまたはフィルターまで絞り込み、継続的に失敗する場合は traceId を保持して読み取り段階を確認してください。 |