コンテンツにスキップ

作成



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 コードで固定マッチングしないでください。

フィードバック

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