インポート¶
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 は、グローバルタグテンプレートを個別にインポートするために使用します。
呼び出しフロー
tags配列を準備します。各要素は 1 つのタグテンプレートを表します。- 同名タグが存在する場合の処理ポリシーを
repeatTagNameOpで指定します。 - ポリシーが
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 を提供してください。 |