すべてのラベルを取得¶
POST /api/v1/object/hosts/label/list
概要¶
データソースとオブジェクト名に基づいて、インフラストラクチャオブジェクトにバインドされたラベルの詳細を読み取ります。
呼び出し前の確認と使用手順¶
このグループのラベルはインフラストラクチャオブジェクトにバインドされたラベルであり、収集 Tag、ホスト名、元のログフィールドを変更するものではなく、グローバルラベルの権限を直接管理することとも異なります。API Key は現在のワークスペースを決定します。本ページの JSON Body に従って呼び出してください。このレガシールートのパラメータ取得では、URL パラメータによって JSON の同名値が上書きされたり、他のフィールドが補完されたりします。URL には本ページの Body と同じ検証がないため、宣言されていない互換フィールドを安定した拡張契約として扱わないでください。URL の業務パラメータを混在させないでください。
routine.defaultAccess、infrastructure.setManage、または anonymous.snapshotShared のいずれかのエントリ権限が必要です。実際のオブジェクトクエリはデータアクセスルールにも制約されます。source には実際のオブジェクト分類を指定し、ホストの場合は通常 HOST です。names を指定しない場合、または [] の場合は、その分類で返されるすべてのオブジェクトをクエリしますが、ワークスペース全体のすべてのグローバルラベルを一覧表示するわけではありません。names で少数のオブジェクトを事前に絞り込んで検証できます。timeRange には 2 つの Unix ミリ秒時刻を明確に指定することを推奨します。指定しない場合は上流に空の範囲を渡すため、すべての履歴データが返されることは保証されません。
動的なオブジェクト名マッピングを返します。オブジェクトが見つからない場合は {} になることがあります。ラベルクエリとオブジェクトストレージにはキャッシュが存在する可能性があり(従来の使用説明では通常約 5 分)、変更後は待機して読み戻し、確認してください。強整合性を要求することはできません。元のラベル文字列は現在のワークスペースのグローバルラベル情報と照合されます。未登録のラベルは空の UUID を持つ一時オブジェクトとして返され、今回の読み取りによって自動作成されることはありません。
ラベルの scope の正規化では all、scene、monitor、dialing、security、infrastructure、catalog をサポートします。all は他のスコープと混在できません。既存のラベルの scope が不正な場合、クエリも 406 invalid scope を返します。ラベル設定を確認し、今回の Body だけを変更しないでください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| names | array | オプションの配列です。省略または [] の場合、名前でフィルタリングしません。要素はすべて重複排除された文字列にすることを推奨します。公開配列には要素ごとの型検証がないため、不正な要素は業務段階で失敗する可能性があります。 null 許可: False 例: ["host-example"]取得または入力方法: 実際のオブジェクト一覧からオブジェクトの name をコピーし、ソース分類と一致させます。 |
|
| source | string | Y | 必須の文字列です。データドメイン namespace=object ではありません。ソースコードには HOST のみに限定する列挙制約はありません。 null 許可: False 例: HOST取得または入力方法: インフラストラクチャページのオブジェクト分類、または実際のオブジェクトの収集 class から取得します。ホストでは通常 HOST を使用します。 |
| timeRange | array | オプションの配列です。有効な整数のミリ秒を 2 つ指定することを推奨します。宣言には長さ/要素型の制限がなく、省略時はクエリサービスに [] を渡します。 null 許可: False 例: [1785427200000, 1785429000000]取得または入力方法: 表示するオブジェクトの開始・終了 Unix ミリ秒時刻を選択します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/object/hosts/label/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"source":"HOST","names":["host-example"],"timeRange":[1785427200000,1785429000000]}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.オブジェクト名 | object | 動的なオブジェクト名キーです。クエリで返される tags.name に対応し、固定の host フィールドではありません。 |
| content.オブジェクト名.labels | array | label 名でソートされたラベル情報オブジェクトのリストです。文字列配列ではありません。 |
| content.オブジェクト名.labels[] | object | 1 つのラベルの情報です。未登録のラベルも一時オブジェクトとして返されます。 |
| content.オブジェクト名.labels[].uuid | string | グローバルラベルの UUID です。未登録のラベルでは空文字列になり、tag UUID 管理インターフェースには使用できません。 |
| content.オブジェクト名.labels[].workspaceUUID | string | 登録済みラベルの所属ワークスペースです。一時オブジェクトでは空になります。 |
| content.オブジェクト名.labels[].name | string | ラベル名です。後続で labels を変更する場合は、オブジェクト全体や uuid ではなく、この name 値を送信してください。 |
| content.オブジェクト名.labels[].description | string | グローバルラベルの説明です。一時オブジェクトでは空になります。 |
| content.オブジェクト名.labels[].colour | string | ラベルの色です。一時オブジェクトでは default になります。 |
| content.オブジェクト名.labels[].scope | array | グローバルラベルの有効範囲です。一時オブジェクトではデフォルトで [all] になり、現在の Key のデータアクセス権限ではありません。 |
| content.オブジェクト名.labels[].id | integer または string | 登録済みラベルの内部行番号です。一時オブジェクトでは空文字列になり、リソース呼び出しのパラメータとしては使用しません。 |
| content.declaration | object または null | 空でない結果の最外層にのみ付加される共通ワークスペース宣言です。各オブジェクトや label に再帰的に補完されることはありません。 |
{
"code": 200,
"content": {
"host-example": {
"labels": [
{
"uuid": "tag_example",
"workspaceUUID": "wksp_example",
"name": "production",
"description": "生产环境",
"colour": "default",
"scope": [
"all"
],
"id": 10
},
{
"uuid": "",
"workspaceUUID": "",
"name": "unmanaged-label",
"description": "",
"colour": "default",
"scope": [
"all"
],
"id": ""
}
]
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては、共通エラー定義を参照してください。
クエリは実際のデータ権限とクエリサービスに応じて、その他の構文/データドメインエラーを返します。HTTP とエラーコードは実際のレスポンスおよび共通説明に従って処理してください。ここでは現在の get_obj_labels について説明しており、異なる形式を返す内部 v2 メソッドではありません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | Body が JSON オブジェクトではない | 一部の json ファイル形式エラー | 本ページの JSON オブジェクトを送信してください。 |
| 406 | ft.DqlParseError | ソース/名前から有効なクエリ式を構成できない | dql parser 解析失敗: {} | 実際のソースとオブジェクト名を使用し、引用符や構文制御文字を含む値を手作業で構築しないでください。まずクエリを確認してください。 |
| 503 | ft.QueryServiceUnavailable | オブジェクトクエリの上流 503 が正規化された | クエリサービスは一時的に利用できません。しばらくしてから再試行してください | content.retryable のヒントに従ってバックオフして再試行し、高頻度でポーリングしないでください。 |
| 500 | ft.InternalServerError | 上流の構造、配列子要素/ラベル名の型異常、キャッシュ/データベースエラー、または非透過サービス 5xx | 内部エラー | オブジェクトクエリの範囲を絞り、既存のラベル情報と上流レスポンスの構造を確認してください。バックオフして再試行し、失敗が続く場合は traceId を提供してください。 |
| 406 | ft.ParameterValidationFailed | 既存のグローバルラベルの scope が空配列/未知の値を含む/all との混合などの不正な組み合わせ | invalid scope | 管理者に依頼して、該当するグローバルラベルの scope を修正してください。この種のエラーは、今回のクエリパラメータが不正であるとは限りません。 |