作成¶
POST /api/v1/dialing_region/regist
概要¶
現在のワークスペースのセルフホスト Synthetic テストノード設定を登録します。
呼び出し前の確認と使用手順¶
まずノードプラン、ネットワーク位置、一意の keycode/表示名を確認してください。サーバー側は帰属を現在の Key ワークスペースにバインドし、サーバー側の作成/更新アイデンティティと Unix 秒を付加します。外部スペースの external_id やカスタム extend_info は受け取りません。登録はノード設定のみであり、DataKit のインストールやハートビートのオンラインを保証するものではありません。成功後は実際のレスポンスの content.uuid または content.regionInfo.uuid に基づいてノード UUID を取得し、ノード詳細/製品の「設定を取得」からデプロイ資料を取得してください。セルフホストノード管理を参考にインストールを完了し、isAlive=true を照会して受け入れ確認を行います。
レスポンスはノードそのものの場合もあれば、上流の ak/regionInfo ラッパーを保持する場合もあります。ノードの AK/SK を OpenAPI Key として扱わないでください。実際の値はノードに安全に設定する場合にのみ使用してください。現在のコントローラーは最外層の名前のみを正規化し、ラッパー内の regionInfo は自動で再帰変換しません。表示には実際のノードオブジェクトと nameI18n を優先して読み取ってください。名前の重複についてはまずセルフホストノードを確認してください。クロスワークスペースでグローバルに一意であることを保証するものではありません。下流の登録が成功したもののレスポンス/後続処理が失敗した場合は、まず一覧で keycode を確認し、盲目的に再登録しないでください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得してください。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| nameI18n.zh | string | 任意の言語メンバー。省略時は空/フォールバックとなり、ノード識別子は変更されません。 例: 生产自建节点取得または入力方法: 顧客がその言語の表示名を提供します。 |
|
| nameI18n.en | string | 任意の言語メンバー。省略時は空/フォールバックとなり、ノード識別子は変更されません。 例: Production self node取得または入力方法: 顧客がその言語の表示名を提供します。 |
|
| nameI18n.zh-hant | string | 任意の言語メンバー。省略時は空/フォールバックとなり、ノード識別子は変更されません。 例: Production self node取得または入力方法: 顧客がその言語の表示名を提供します。 |
|
| nameI18n.id | string | 任意の言語メンバー。省略時は空/フォールバックとなり、ノード識別子は変更されません。 例: Production self node取得または入力方法: 顧客がその言語の表示名を提供します。 |
|
| nameI18n.ja | string | 任意の言語メンバー。省略時は空/フォールバックとなり、ノード識別子は変更されません。 例: Production self node取得または入力方法: 顧客がその言語の表示名を提供します。 |
|
| nameI18n.ko | string | 任意の言語メンバー。省略時は空/フォールバックとなり、ノード識別子は変更されません。 例: Production self node取得または入力方法: 顧客がその言語の表示名を提供します。 |
|
| city | string | 任意、null 可。 null を許可: True 例: Hangzhou取得または入力方法: 実際の都市に従って入力してください。 |
|
| company | string | 任意、null 可。ワークスペースの帰属を決定しません。 null を許可: True 例: example取得または入力方法: ノードが属する企業に従って入力してください。 |
|
| country | string | Y | 必須文字列。公開レイヤーでは国の列挙を固定せず、ノード管理と一致させます。 null を許可: False 例: China取得または入力方法: ノードの実際の国に従って入力してください。 |
| internal | boolean | Y | 必須ブール値。ノードがイントラネットからアクセス可能か、または有効かどうかを示すものではありません。 null を許可: False 例: true取得または入力方法: true は国内、false は海外です。ノードの実際の所在地に従って入力してください。 |
| isp | string | Y | 必須文字列。現在の Studio はキャリアの列挙を固定せず、上流の検証も代替しません。 null を許可: False 例: example-isp取得または入力方法: 実際のノードのネットワークキャリア/プロバイダーから識別子を取得してください。 |
| keycode | string | Y | 必須文字列。本ワークスペース内の完全一致による重複事前チェックであり、自動で trim/大文字小文字の統一は行いません。上流に別の制約がある可能性があり、大文字小文字で回避しないでください。登録後に返される uuid ではありません。 null を許可: False 例: example-self-node取得または入力方法: ノードに安定したデプロイ識別子を設定し、本ワークスペースのノード keycode を先に確認して重複を避けてください。 |
| name | string | 任意、null/空文字列可。空でない明示的な name は nameI18n.zh を上書きします。有効な表示名がない場合、重複チェックは keycode にフォールバックします。trim による統一は行わないため、クライアント側で事前に正規化してください。 空文字列を許可: True null を許可: True 例: 生产自建节点取得または入力方法: 業務上の表示名。空でないことを推奨し、現在のワークスペースの既存ノード表示名/名前なしノードの keycode との競合を避けてください。 |
|
| nameI18n | json | 任意、null 可。明示的な name は zh を優先し、その他の言語は正規化し、未知の言語は無視し、欠落言語は空文字として表示時のフォールバックに従います。各値は文字列を推奨します。ノード登録に必要な JSON シリアライズ文字列ではありません。 null を許可: True 例: {"zh": "生产自建节点", "en": "Production self node"}取得または入力方法: 製品がサポートする言語で名前マッピングを入力してください。現在は zh/en/zh-hant/id/ja/ko をサポートしています。 |
|
| province | string | 任意、null 可。省略するとその地域情報を提供しません。 null を許可: True 例: Zhejiang取得または入力方法: 実際のノードの省に従って入力してください。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/dialing_region/regist' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"internal":true,"isp":"example-isp","country":"China","province":"Zhejiang","city":"Hangzhou","name":"生产自建节点","nameI18n":{"zh":"生产自建节点","en":"Production self node"},"company":"example","keycode":"example-self-node"}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.uuid | string | regn_ ノード UUID。通常タスクの regions 作成時にこの値を使用します。 |
| content.keycode | string | ノードのデプロイ/識別コード。regions UUID としては使用しません。 |
| content.owner | string | セルフホストノード custom。 |
| content.name | string | 現在のリクエスト言語に応じて選択された名前。 |
| content.nameEn | string | 英語互換の表示名。 |
| content.name_en | string | 上流の旧英語名。条件付きで保持されます。 |
| content.nameI18n | object | 正規化された言語名マッピング。 |
| content.nameI18n.言語コード | string | その言語の表示名。 |
| content.internal | boolean | true は国内、false は海外。ネットワークのプライベート性ではありません。 |
| content.country | string | 国。 |
| content.province | string | 省。 |
| content.city | string | 都市。 |
| content.isp | string | キャリア/プロバイダー。 |
| content.status | string | ノードサービス状態(OK/disabled など)。タスク実行状態ではありません。 |
| content.heartbeat | integer | ノードの最新ハートビート(Unix 秒)。上流の定義に準じます。 |
| content.region | string | 上流のリージョン識別子。 |
| content.company | string | 企業情報。 |
| content.external_id | string | セルフホストの帰属などの上流フィールド。デフォルトノードでは通常空です。 |
| content.parent_ak | string | 上流互換の帰属フィールド。空の場合があります。クライアントはこれを OpenAPI Key として扱いません。 |
| content.extend_info | string | 上流の拡張 JSON 文字列または空文字列。デフォルトではオブジェクトではありません。 |
| content.create_at | integer | 上流の作成時間フィールド。履歴では -1 の場合があります。タスクの createAt とは区別してください。 |
| content.その他の上流フィールド | JSON | 上流互換の追加フィールドをそのまま引き継ぎます。未記載のキーをそのまま書き込み可能なパラメータとして扱わないでください。 |
| content.ak | object | 一部の上流の登録/詳細レスポンスに含まれるノードデプロイ認証情報オブジェクト。このオブジェクトがない場合は製品から設定を取得し、フィールドが常に存在すると仮定しないでください。 |
| content.ak.ak | string | ノード AK 識別子。本リクエストの DF-API-KEY ではありません。 |
| content.ak.sk | string | ノード SK。安全なデプロイ設定にのみ使用し、実際の値を公開または記録しないでください。 |
| content.ak.external_id | string | 認証情報が帰属するワークスペース識別子。 |
| content.ak.owner | string | 上流の認証情報 owner フィールド。 |
| content.ak.parent_ak | string | 上流の親認証情報識別子。直接認証可能なシークレットとして扱わないでください。 |
| content.ak.status | string | 上流の認証情報状態。 |
| content.ak.update_at | integer | 上流の更新時間。実際の単位を保持し、履歴では 0 です。Studio の updateAt と混同しないでください。 |
| content.regionInfo | object | 一部の上流におけるラッパーノードオブジェクト。フラットなノードフィールドと同じ意味です。このコントローラーはこのオブジェクトの名前を再帰的に正規化しません。 |
| content.regionInfo.uuid | string | regn_ ノード UUID。通常タスクの regions 作成時にこの値を使用します。 |
| content.regionInfo.keycode | string | ノードのデプロイ/識別コード。regions UUID としては使用しません。 |
| content.regionInfo.owner | string | セルフホストノード custom。 |
| content.regionInfo.name | string | 現在のリクエスト言語に応じて選択された名前。 |
| content.regionInfo.nameEn | string | 英語互換の表示名。 |
| content.regionInfo.name_en | string | 上流の旧英語名。条件付きで保持されます。 |
| content.regionInfo.nameI18n | object | 正規化された言語名マッピング。 |
| content.regionInfo.nameI18n.言語コード | string | その言語の表示名。 |
| content.regionInfo.internal | boolean | true は国内、false は海外。ネットワークのプライベート性ではありません。 |
| content.regionInfo.country | string | 国。 |
| content.regionInfo.province | string | 省。 |
| content.regionInfo.city | string | 都市。 |
| content.regionInfo.isp | string | キャリア/プロバイダー。 |
| content.regionInfo.status | string | ノードサービス状態(OK/disabled など)。タスク実行状態ではありません。 |
| content.regionInfo.heartbeat | integer | ノードの最新ハートビート(Unix 秒)。上流の定義に準じます。 |
| content.regionInfo.region | string | 上流のリージョン識別子。 |
| content.regionInfo.company | string | 企業情報。 |
| content.regionInfo.external_id | string | セルフホストの帰属などの上流フィールド。デフォルトノードでは通常空です。 |
| content.regionInfo.parent_ak | string | 上流互換の帰属フィールド。空の場合があります。クライアントはこれを OpenAPI Key として扱いません。 |
| content.regionInfo.extend_info | string | 上流の拡張 JSON 文字列または空文字列。デフォルトではオブジェクトではありません。 |
| content.regionInfo.create_at | integer | 上流の作成時間フィールド。履歴では -1 の場合があります。タスクの createAt とは区別してください。 |
| content.regionInfo.その他の上流フィールド | JSON | 上流互換の追加フィールドをそのまま引き継ぎます。未記載のキーをそのまま書き込み可能なパラメータとして扱わないでください。 |
| content.declaration | object | 最外層の非空オブジェクトに付加される共通宣言。ネストされたオブジェクトには再帰的に付加されません。 |
{
"code": 200,
"content": {
"uuid": "regn_example",
"keycode": "example-self-node",
"owner": "custom",
"name": "生产自建节点",
"nameEn": "Production self node",
"nameI18n": {
"zh": "生产自建节点",
"en": "Production self node"
},
"internal": true,
"country": "China",
"province": "Zhejiang",
"city": "Hangzhou",
"isp": "example",
"status": "OK",
"heartbeat": 1785427200,
"region": "example-region",
"company": "",
"external_id": "wksp_example",
"parent_ak": "",
"extend_info": "",
"create_at": 1785427200,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
通常の Synthetic テスト SDK は、下流の error_code=dialtesting.invalidRegion を一律に ft.DialingRegionError にマッピングし、実際の HTTP を保持します(400 に限定されません)。その他の下流 4xx は実際の HTTP と error_code/message(ft プレフィックスのない上流コードを含む)を保持し、記載のないコードも返される可能性があります。>=500 は公開エントリで一律に 500 ft.InternalServerError にラップされます。SDK は上流の content を返し、本コントローラーは固定の regionInfo/ak 構造に一律に再ラップしません。実際のデプロイバージョンに応じてフラットまたは互換ラッパーを識別する必要があり、未知の追加フィールドは互換性のため保持されます。
| HTTP ステータス | errorCode | トリガー条件 | メッセージまたはレスポンス説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | Body のトップレベルがオブジェクトではありません | 一部の json ファイル形式エラー | 本ページの登録オブジェクトを送信してください。 |
| 400 | RegionRepeatNameKeycode | 本ワークスペースのセルフホストノードに同じ keycode が既に存在 | ノード Code{} は既に存在します |
一意の keycode に変更するか、既存ノードを使用してください。実際の errorCode には ft プレフィックスがありません。 |
| 400 | RegionRepeatKeycode | 表示名またはフォールバック keycode が本ワークスペースの既存ノード表示名と競合 | ノード名の重複 | 一意の表示名に変更してください。この履歴上のエラーコード名はチェック内容と異なり、実際のコードには ft プレフィックスがありません。 |
| 406 | ft.DialingBrandNoSetError | ワークスペースに対応する Synthetic テストサービスのブランド設定が欠落 | {} ブランドの Synthetic テスト設定が未設定です。 |
管理者が現在のワークスペースの Synthetic テストサービスを確認してください。 |
| 400 | ft.DialingAKNoSetError | Synthetic テストサービスの署名認証情報が未設定 | Synthetic テストの AK 情報が未設定です。Launcher のアクティベーション設定を確認してください | 管理者がサービスアクティベーション情報を確認してください。クライアントは本 Body でこれらの認証情報を送信しません。 |
| 400 | ft.DialingServerError | 下流の Synthetic テストノードインターフェースが 400 の業務失敗を返す、またはレスポンスメディアを解析できない | Synthetic テストサービスインターフェースの呼び出し失敗 | message/traceId を確認し、管理者がノードサービスを検査してください。失敗をノードなしとして扱わないでください。 |
| 500 | ft.InternalServerError | 通常の下流 5xx/接続異常、または履歴ノード/関連フィールドの形式、名前、レスポンス組み立ての異常 | 内部エラー | 具体的なノード/フィルターに絞り、上流レスポンス形式とサービス可用性を確認してください。継続的に失敗する場合は traceId を保持してください。 |
| 400 | ft.DialingRegionError | 下流 HTTP400 かつ error_code=dialtesting.invalidRegion。その他の 4xx も同じコードにマッピングされ、実際の HTTP を保持 | 現在のタスクには一部の Synthetic テストノードが無効になっているため、設定を更新して再保存してください。 | 有効なセルフホストノードとノードサービス状態を確認し、元の dialtesting コードで固定マッチングしないでください。 |