取得¶
GET /api/v1/dialing_region/{region_uuid}/info
概要¶
現在のワークスペースのセルフホストノードとデプロイサービスアドレスを1件取得します。
呼び出し前の確認と使用手順¶
まず本ワークスペースのセルフホストノードの所属を確認し、その後で下流の詳細を取得します。デフォルトのパブリックノード、他のワークスペースのノード、または存在しないUUIDは、無効なセルフホストノードとして403と見なされます。このAPIにはQuery業務パラメータはなく、タスクの実行やインストールをトリガーしません。serverは現在のデプロイサービスのプロトコル/ホスト/ポートで構成され、ノード接続に使用します。セルフホストノード管理のregion_id/ak/sk設定と組み合わせて使用し、serverを今回のOpenAPIエンドポイントとして扱わないでください。
下流のcontentはそのまま引き継ぎ、外側にserverと正規化された表示名を追加します。現在、フラットなノードの例と旧来のak/regionInfoラッピングの両方が出現する可能性があり、ネストされたラッピングでは名前を再帰的に正規化しません。credentialsは上流が実際に返した場合にのみ存在します。ノード認証情報を含むレスポンスを取得した場合は安全に保管してください。このレスポンスから完全なデプロイ認証情報を取得できない場合は、製品の「設定を取得」を使用し、AK/SKを独自に作成しないでください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| region_uuid | string | Y | デフォルトのパブリックノード、モバイルノードID、keycode、またはタスクUUIDではありません。 例: regn_example取得または入力方法: セルフホストノード一覧のuuidから、現在のワークスペースのowner=customのノードを取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/dialing_region/regn_example/info' \
-H 'DF-API-KEY: <DF-API-KEY>'
レスポンス¶
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.server | string | 現在のノードサービスの完全なベースアドレス。デプロイされたノードで使用され、このOpenAPIのアドレスではありません。 |
| 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,
"server": "https://dialing-service.example.com",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
上流互換ラッピングの例(認証情報はすべてプレースホルダーで、regionInfoは上流構造を保持します。最外層の名前は内層ノードを表すとは限りません):
{
"code": 200,
"content": {
"ak": {
"ak": "NODE-AK-PLACEHOLDER",
"sk": "NODE-SK-PLACEHOLDER",
"external_id": "wksp_example",
"owner": "",
"parent_ak": "PARENT-AK-ID",
"status": "",
"update_at": 0
},
"regionInfo": {
"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
},
"server": "https://dialing-service.example.com",
"name": "",
"nameEn": "",
"nameI18n": {
"zh": "",
"en": "",
"zh-hant": "",
"id": "",
"ja": "",
"ko": ""
},
"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 | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 403 | ft.ForbiddenInvalidSelfBuiltNode | UUIDが現在のワークスペースのセルフホストノード集合に存在しない(デフォルト、他ワークスペース、存在しない場合を含む) | 不正な操作、無効なセルフホストノードID | 現在のワークスペースのセルフホスト一覧からuuidを再取得し、keycodeで代用しないでください。 |
| 406 | ft.DialingBrandNoSetError | ワークスペースに対応する Synthetic テストサービスのブランド設定が欠落している | {}ブランドの Synthetic テスト設定が構成されていません。 |
管理者が現在のワークスペースの Synthetic テストサービスを確認してください。 |
| 400 | ft.DialingAKNoSetError | Synthetic テストサービスの署名認証情報が構成されていない | Synthetic テストの AK 情報が構成されていません。Launcher のアクティベーション設定を確認してください | 管理者がサービスのアクティベーション情報を確認してください。クライアントはこのBodyでこれらの認証情報を送信しません。 |
| 400 | ft.DialingServerError | 下流の Synthetic テストノードAPIが400の業務失敗を返す、またはレスポンスメディアを解析できない | Synthetic テストサービスAPIの呼び出しに失敗しました | message/traceIdを確認し、管理者がノードサービスを検査してください。失敗をノードなしとして扱わないでください。 |
| 500 | ft.InternalServerError | 通常の下流5xx/接続異常、または履歴ノード/関連フィールドの形式、名前、レスポンス組み立ての異常 | 内部エラー | 具体的なノード/フィルターに絞り込み、上流のレスポンス形式とサービスの可用性を確認してください。継続的に失敗する場合はtraceIdを保持してください。 |
| 400 | ft.DialingRegionError | 下流HTTP 400かつerror_code=dialtesting.invalidRegion。その他の4xxも同じコードにマッピングされ、実際のHTTPを保持する | 現在のタスクには一部無効な Synthetic テストノードがあります。設定を更新して再保存してください。 | 有効なセルフホストノードとノードサービスの状態を確認し、元のdialtestingコードで固定マッチングしないでください。 |