コンテンツにスキップ

ホスト label の変更



POST /api/v1/object/hosts/{host}/label/modify

概要

指定したインフラストラクチャオブジェクトの label 集合を全体置換します。省略または空配列の場合はクリアされます。

呼び出し前の注意と使用手順

この label グループはインフラストラクチャオブジェクトにバインドされた label であり、収集 Tag、ホスト名、生ログフィールドを変更するものではなく、グローバルラベルの権限を直接管理するものとも異なります。API Key によって現在のワークスペースが決まります。本ページの JSON Body に従って呼び出してください。このレガシールートのパラメータ取得では、URL パラメータによって JSON の同名値が上書きされたり、他のフィールドが補われたりします。URL には本ページ Body と同じ検証がないため、宣言されていない互換フィールドを安定した拡張契約として扱わないでください。URL の業務パラメータを混在させないでください。

infrastructure.setManage が必要です。host は現在の source 配下のオブジェクト name であり、ルートパスでは一度に 1 つの単一セグメント名のみ指定できます。オブジェクト UUID やグローバル Tag UUID は渡せません。名前に含まれるスラッシュは、エンコードしてもこのパスにマッチしない場合があります。source はオブジェクトの分類と一致している必要があります。まずすべての label を取得で現在の集合を読み取り、残す label.name を保持したうえで、目的の完全な文字列配列を送信してください。増分追加ではありません。

labels を省略するか [] を指定すると、すべてのラベルがクリアされます。省略によって「元の値を保持」を表現することはできません。空でない集合の場合、まずオブジェクトクエリサービスに書き込み、その後、未登録の名前についてグローバルラベルのレコードを作成します。この 2 ステップはサービスをまたぐアトミックトランザクションではないため、後者のステップが失敗してもオブジェクトのラベルが既に有効になっている可能性があります。重複した名前や不正な名前はデータベースエラーの原因となる可能性があります。実際の名前で重複を排除し、グローバルラベルの命名規則に従ってください。クリアはそのオブジェクトのバインドを解除するだけで、グローバルラベルのレコードは削除しません。

成功時は常に true を返し、影響件数や最終的なオブジェクトは提供しません。存在しないオブジェクトが 404 を返すことは保証されず、キャッシュが更新されたことも証明しません。上流の特定の書き込みエラーは SDK で無視されるため、結果が不明な場合は読み戻して確認する必要があります。true だけでは実際の変更を証明できません。

ルートパラメータ

パラメータ名 型 必須 説明
host string Y 実際の URL パスパラメータです。Body または URL パラメータの name でこのパス値が置き換えられることはありません。
例: host-example
取得または入力方法: 現在の source のオブジェクトリストから name をコピーします。1 回に 1 つの単一セグメント名です。

リクエストヘッダー

パラメータ名 型 必須 説明
DF-API-KEY string Y ワークスペースの OpenAPI 認証資格情報です。
例: <DF-API-KEY>
取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。

Body リクエストパラメータ

パラメータ名 型 必須 説明
labels array オプションの文字列要素配列で、最終的な完全な集合を表します。省略または [] でクリアされます。ラベルの詳細オブジェクトや uuid は送信できません。配列要素には再帰的な検証が宣言されていないため、不正な値が事前に 406 になることは保証されません。
null 許可: False
例: ["production", "service-api"]
取得または入力方法: すべての label を取得のレスポンスの content[オブジェクト name].labels[].name からラベル名を取得します。オブジェクト name はパス host および Body の source と対応している必要があり、ラベルの uuid を取得しないでください。
source string Y 必須の文字列です。パスに hosts が含まれるという理由だけで省略したり、すべての source をデフォルトにしたりしないでください。
null 許可: False
例: HOST
取得または入力方法: オブジェクトに一致する実際のオブジェクト分類(例: ホスト HOST)を指定します。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/object/hosts/host-example/label/modify' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"source":"HOST","labels":["production","service-api"]}'

レスポンス

HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。

フィールド 型 説明
content boolean 成功時は常に true です。オブジェクトや label の詳細ではなく、強整合性や影響件数を表すものではありません。
{
  "code": 200,
  "content": true,
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラー応答

認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。

変更処理は上流のラベル書き込みインターフェースを呼び出すため、エラーは上流の状態によって変化する可能性があります。通常の 5xx は最終的に 500 にラップされます。ローカルでホストが見つからないからといって、オブジェクトが存在しない 404 が必ずスローされるわけではなく、冪等性や強整合性を前提とすることはできません。

HTTP ステータス errorCode 発生条件 メッセージまたは応答の説明 対処方法
406 ft.ParameterValidationFailed リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している パラメータ解析失敗 パラメータの位置、フィールド名、型、値を確認してください。
400 ft.RequestJsonFormatError リクエスト JSON の構文が無効 リクエスト JSON の形式エラー content.reason、line、column に従って JSON を修正します。
400 ft.JsonFormatError リクエスト Body が JSON オブジェクトではない 一部の json ファイルの形式エラー source と目的の labels 配列を送信します。
500 ft.InternalServerError ラベル要素/ストレージのエラー、または上流の非透過 5xx 内部エラー まずオブジェクトの現在のラベルを読み取ってどのステップまで実行されたかを判断してから、リトライを決定してください。traceId を提示してください。

フィードバック

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