コンテンツにスキップ

インポート



POST /api/v1/tag/import

概要

名前でタグを一括作成または上書きし、スコープ影響を事前チェックして項目ごとに送信します。

呼び出し前の確認と使用手順

まず check で重複名を確認し、上書きが必要な場合は recover を使用します。バッチ全体に対して、テンプレート/同一バッチ内の重複名、既存の重複、およびスコープ影響を先に検証します。recover で参照/モニタリング設定の削除を伴う変更があり、有効なインポート資格情報がない場合は、正常に requiresConfirmation=true と scopePreviews を返し、バッチ全体はまだ書き込まれていません。確認後、tagUUID ごとに scopePreviewTokens を整理し、完全に同じインポートテンプレートで再試行します。token の期限切れ/影響変化時には新しいプレビューが返されるため、完了済みとして扱わないでください。独立した scope_preview の資格情報にはインポート全体のフィンガープリントがないため、この分岐の資格情報を直接代用できません。

事前チェックに合格した後、各項目を個別に送信します。一部が失敗しても成功済みのタグはロールバックされません。失敗した項目の名前は failedNames で確認でき、traceId と合わせて調査したうえで対象を絞って再試行してください。skip は successCount または failCount に含まれないため、両者の合計が入力数より少なくなることがあります。recover で description/colour/scope を省略すると、空文字列/default/all で上書きされます。古いテンプレートをインポートする場合は、scope のデフォルト all が適用範囲を広げる可能性があるため特に注意してください。Synthetic テストの同期に失敗した場合は pendingDialingTaskUUIDs として別途返され、送信済みのタグは引き続き成功としてカウントされます。インポートされるのはタグ定義のみで、リソースの関連付けや権限設定は復元されません。

リクエストヘッダー

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

Body リクエストパラメータ

パラメータ名 型 必須 説明
scopePreviewTokens.タグUUID string 1つのタグのインポート確認資格情報。
例: IMPORT-PREVIEW-TOKEN
取得または入力方法: 今回の scopePreviews で対応する tagUUID の previewToken。
tags[*].scope[*] string 配列のメンバーで、all と具体値を混在させません。
例: monitor
取得または入力方法: 上位の列挙値から単一のスコープを選択します。
repeatTagNameOp string 省略可能。デフォルトは check。check は重複名がある場合に repeat_name を正常返し、バッチ全体を書き込みません。skip は既存項目を変更しません。recover はテンプレートに従って、既存名に対応する description/colour/scope を全体として上書きし、省略時はそれぞれ空文字列/default/all になります。
許容 null: False
選択可能な値: ['check', 'skip', 'recover']
例: check
取得または入力方法: check は重複確認、skip は既存をスキップ、recover は既存を上書きします。
scopePreviewTokens object 省略可能なマッピングです。値の最大長は 128 です。正規化された完全なインポートファイル、および現在の識別情報/影響フィンガープリントにバインドされ、有効期間は 600 秒です。独立した scope_preview の token をインポート token の代わりに使用しないでください。確認後の再試行では、tags の内容/順序およびポリシーを完全に一致させてください。
許容 null: False
例: {"tag_example": "IMPORT-PREVIEW-TOKEN"}
取得または入力方法: 本 API の requiresConfirmation 分岐の scopePreviews[] から、項目ごとに tagUUID→previewToken を取得します。
tags array はい 必須の空でないオブジェクト配列です。各項目のフィールドは宣言に準拠している必要があり、name は trim 後にチェックされます。ファイル全体で同名(大文字と小文字を区別)の場合は直ちにエラーになります。
許容 null: False
例: [{"name": "production", "description": "本番リソースを統一的にマークします。", "colour": "default", "scope": ["scene", "monitor"]}]
取得または入力方法: export レスポンスの content から配列を取得し、各項目の declaration を削除します。
tags[*] object リソース参照/UUID/権限フィールドは受け付けません。エクスポートの共通エンベロープをそのまま送信することはできません。
例: {"name": "production", "description": "本番リソースを統一的にマークします。", "colour": "default", "scope": ["scene", "monitor"]}
取得または入力方法: 単一の {name,description,colour,scope} テンプレート。
tags[*].colour string 省略可能。デフォルトは default。recover は元の色を置き換えます。50 カウント単位以下を推奨します。
許容 null: False
例: default
取得または入力方法: 一覧にある既存の colour を流用するか、デフォルトの default を使用します。
tags[*].description string 省略可能。デフォルトは空文字列。recover は元の説明をクリアします。100 カウント単位以下を推奨します。
許容 null: False
例: 本番リソースを統一的にマークします。
取得または入力方法: 業務担当者がこのタグの用途を説明します。
tags[*].name string はい 必須の空でない名前です。trim 後に大文字と小文字を区別する重複チェックの対象になります。インポート宣言には作成ページの長さ上限が指定されていないため、顧客向け UI との互換性を保つために引き続き 50 カウント単位以下を推奨します。
許容 null: False
例: production
取得または入力方法: 業務で定義したタグ名。まずタグ一覧で使用済みの名前を確認します。
tags[*].scope any 空でないスコープ配列です。列挙値は all(グローバル)、scene(シーン)、monitor(モニタリング)、dialing(Synthetic テスト)、security(セキュリティ)、infrastructure(インフラストラクチャ)、catalog(統合カタログ)です。旧形式の単一値文字列との互換性があります。all は他の値と混在できません。重複値は除去され、固定の列挙順で返されます。[]/null/未知の値は受け付けません。新規作成/インポートで省略した場合は ["all"] がデフォルトになり、変更時に省略した場合は既存値が維持されます。scope はタグの適用範囲を制限するだけで、リソース権限を付与しません。インフラストラクチャ/統合カタログの名前バインディングは、ここでのエンティティ参照のクリーンアップによって書き換えられません。
許容 null: False
例: ["scene", "monitor"]
取得または入力方法: タグをバインドする必要があるリソースの業務タイプに応じて選択します。

パラメータ補足説明

この API は、グローバルタグテンプレートを個別にインポートするために使用します。

呼び出しフロー

  1. tags 配列を準備します。各要素は 1 つのタグテンプレートを表します。
  2. 同名タグが存在する場合の処理ポリシーを repeatTagNameOp で指定します。
  3. ポリシーが check で同名タグが存在する場合、API は直接 repeat_name を返し、DB への書き込みは実行しません。

repeatTagNameOp の説明

値 説明
check 重複のみをチェックします。同名タグが存在する場合は repeat_name を返します。
skip 既存の同名タグをスキップし、存在しないタグのみをインポートします。
recover 対象ワークスペースに同名タグが既にある場合、その description と colour を上書きします。

テンプレートフィールド

フィールド type 必須 説明
name string はい タグ名
description string いいえ タグの説明
colour string いいえ タグの色
scope string いいえ 単一スコープ。旧ファイルではデフォルト all。

レスポンスの説明

  • インポートの実行に成功すると、successCount、failCount を返します。
  • 一部のオブジェクトの実行に失敗した場合、レスポンスに failedNames が追加されます。
  • check モードで重複が見つかった場合、repeat_name を返します。
  • スコープの上書きがリソースに影響する場合は、先に requiresConfirmation と scopePreviews を返します。確認後、scopePreviewTokens を付けて元のファイルを再送信します。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/tag/import' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"repeatTagNameOp":"check","tags":[{"name":"production","description":"本番リソースを統一的にマークします。","colour":"default","scope":["scene","monitor"]}]}'

レスポンス

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

フィールド 型 説明
content.successCount integer このバッチで項目ごとに送信に成功した数。skip でスキップされたものは含みません。
content.failCount integer 項目ごとの異常失敗数。skip は含みません。
content.failedNames array<string> 失敗がある場合に現れる名前。項目ごとのエラーコードは返されません。
content.failedNames[] string 個々の失敗名。
content.pendingDialingTaskUUIDs array<string> タグは送信済みだが Synthetic テストの配信に失敗したタスクの集合。省略可能です。
content.pendingDialingTaskUUIDs[] string 確認対象のタスク UUID。
content.repeat_name array<string> check がヒットした場合に統計の代わりに返され、バッチ全体は書き込まれていません。
content.repeat_name[] string 同名タグの名前。
content.requiresConfirmation boolean 事前チェックで確認が必要な場合に true。統計の代わりに返され、今回バッチ全体は書き込まれていません。
content.scopePreviews array<object> scope 変更の確認が必要なタグのプレビュー。
content.scopePreviews[].tagUUID string 対象タグの UUID。
content.scopePreviews[].oldScope array<string> 現在のスコープを正規化した配列。
content.scopePreviews[].oldScope[] string 個々の旧 scope。
content.scopePreviews[].newScope array<string> 対象スコープを正規化した配列。
content.scopePreviews[].newScope[] string 個々の新 scope。
content.scopePreviews[].requiresConfirmation boolean クリーンアップされるエンティティ参照またはモニタリング設定が存在するかどうか。公開されている modify では引き続き token を省略して直接実行できます。
content.scopePreviews[].affectedResourceCount integer 業務リソースごとに重複を除いた総数。リレーション数とは異なります。SLO 内部のルールは所属する SLO に集約されます。
content.scopePreviews[].affectedRelationCount integer クリーンアップが見込まれるエンティティ参照の件数。
content.scopePreviews[].affectedConfigCount integer クリーンアップが見込まれる incidentsTags のルール設定数。
content.scopePreviews[].orphanRelationCount integer 参照は存在するが対応する有効なリソースが欠落しているリレーション数。リレーション影響にも含まれます。
content.scopePreviews[].summary array<object> リソースタイプ別に集計した、重複を除いたリソース数。
content.scopePreviews[].summary[].resourceType string dashboard/viewer/service/checker/smartMonitor/aiMonitor/incident/dialing/security/slo などの実際の業務タイプ。
content.scopePreviews[].summary[].count integer このタイプのリソース数。
content.scopePreviews[].data array<object> このページで影響を受けるリソースの概要。
content.scopePreviews[].data[].resourceType string 業務リソースのカテゴリ。
content.scopePreviews[].data[].resourceUUID string リソース UUID。
content.scopePreviews[].data[].name string リソースの表示名。名前がない場合は UUID にフォールバックします。
content.scopePreviews[].data[].scope string このリソースが属する scope。
content.scopePreviews[].previewToken string 600 秒間有効なプレビュー資格情報。今回の識別情報/ワークスペース/タグ/対象 scope/影響フィンガープリントにバインドされ、認証 Token ではありません。
content.scopePreviews[].pageInfo object プレビュー明細はデフォルトで 1 ページ目にページングされ、共通の最上位レベルには昇格されません。
content.scopePreviews[].pageInfo.pageIndex integer デフォルトは 1。
content.scopePreviews[].pageInfo.pageSize integer デフォルトは 50。
content.scopePreviews[].pageInfo.totalCount integer このタグで重複を除いた影響リソースの総数。
content.declaration object 共通宣言。
{
  "code": 200,
  "content": {
    "successCount": 1,
    "failCount": 0,
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

check で重複名がヒットした場合:

{
  "code": 200,
  "content": {
    "repeat_name": [
      "production"
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

recover で確認が必要な場合:

{
  "code": 200,
  "content": {
    "requiresConfirmation": true,
    "scopePreviews": [
      {
        "tagUUID": "tag_example",
        "oldScope": [
          "all"
        ],
        "newScope": [
          "scene"
        ],
        "requiresConfirmation": true,
        "affectedResourceCount": 1,
        "affectedRelationCount": 1,
        "affectedConfigCount": 0,
        "orphanRelationCount": 0,
        "summary": [
          {
            "resourceType": "checker",
            "count": 1
          }
        ],
        "data": [
          {
            "resourceType": "checker",
            "resourceUUID": "rul_example",
            "name": "本番モニター",
            "scope": "monitor"
          }
        ],
        "previewToken": "PREVIEW-TOKEN",
        "pageInfo": {
          "pageIndex": 1,
          "pageSize": 50,
          "totalCount": 1
        }
      }
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラー応答

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

HTTP ステータス errorCode 発生条件 メッセージまたはレスポンスの説明 対処方法
406 ft.ParameterValidationFailed リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している パラメータ解析失敗 パラメータの位置、フィールド名、型、値を確認してください。
400 ft.RequestJsonFormatError リクエスト JSON の構文が無効 リクエスト JSON の形式エラー content.reason、line、column に従って JSON を修正してください。
400 ft.ErrorFieldCheck いずれかの trim 後の name が空 {} フィールド検証失敗 空でない名前を指定してください。
400 ft.FileObjectNameRepeat 同一バッチ内で trim 後に大文字と小文字が同じ名前が存在する ファイル内に同じ名前のオブジェクトが存在する 先に入力名の重複を除去してください。
500 ft.InternalServerError データベース、タグ/権限構造、キャッシュ、またはレスポンスのフォーマットに失敗 内部エラー リクエストを確認してからタグの現在の状態を読み戻してください。書き込みがすでに送信されている可能性があるため、むやみに繰り返さず、失敗が継続する場合は traceId を提供してください。

フィードバック

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