作成¶
POST /api/v1/service_manage/add
概要¶
サービスリスト設定を新規作成します。
呼び出し前の準備と使用手順¶
API Key にはサービス管理権限(trace.serviceManage)が必要です。まず [Team] と [Related] を含む完全な TOML 設定を記入してください。サービス名は既存のトレースデータから取得することも、サービスリストを事前に作成することもできます。成功後は content.uuid を保存し、サービスリスト詳細を呼び出してサービスタイプ、色、関連付けを確認します。名前が重複する場合は、まず既存の設定を確認してから、変更インターフェースに切り替えるかどうかを決定してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| serviceCatelog | string | Y | サービスリストの TOML 設定テキスト。完全な JSON エスケープ例はリクエスト例を参照してください。最大重み付き長 65535。ASCII 文字と半角カタカナは 1、その他の文字は 2 として計算します。 null 許可: False $maxCustomLength: 65535 例: "[Team]\nservice = \"checkout\"\ntype = \"web\"\nteam = \"team-commerce\"\ncolour = \"#40C9C9\"\n\n[[Team.oncall]]\nname = \"オンコールメール\"\ntype = \"email\"\nemails = [\"xxx@guance.com\"]\n\n[[Repos]]\nname = \"業務リポジトリ\"\nlink = \"https://example.invalid/repos/checkout\"\nprovider = \"Git\"\n\n[[Docs]]\nname = \"操作マニュアル\"\nlink = \"https://example.invalid/help/checkout\"\nprovider = \"Wiki\"\n\n[Related]\nAppId = \"\"\nTags = [\"team:commerce\"]\nDashboardUUIDs = []\n"取得または入力方法: サービスリスト詳細に originStr=1 を渡して原文を取得するか、下のフィールド表に従って完全な TOML を構築し、JSON 文字列として送信します。 |
パラメータ補足説明¶
serviceCatelog は TOML テキストを含む JSON 文字列です。以下のパスはすべて解析後の TOML 内容を指します。変更時は完全な設定を送信してください。既存の Repos、Docs、Related の関連付けを省略すると、対応する設定やタグが置き換えられ、削除されます。
| TOML フィールド | 型 | 入力および取得元 |
|---|---|---|
| Team | TOMLテーブル |
呼び出し時に必ず指定します。サービスの基本情報を含みます。 |
| Team.service | string |
業務上必須であり、空にできません。アプリケーションパフォーマンスモニタリング(APM)のトレースレコードから service フィールドをコピーするか、事前にサービスリストを作成するサービスの名前を入力します。データベースのフィールド長 256 文字を超えないことを推奨します。 |
| Team.type | string |
省略可能。app、framework、cache、message_queue、custom、db、web、aws_lambda のいずれかを指定します。新規作成時にこれ以外の値を指定すると既存のトレースデータから推測され、一致しない場合は custom になります。変更時にこれ以外の値を指定すると custom に変換されます。 |
| Team.colour | string |
省略可能。有効な色は #C43243, #DE5565, #D77D3D, #FDA82D, #FFD33B, #8934A4, #C75BC9, #F19AF2, #993C7E, #6454CB, #AC8AF0, #6C7AEB, #196AAB, #2EB2EE, #40C9C9, #1A9A82, #417C51, #49B566, #A7D650, #3F94DC です。空値またはその他の色の場合、サービス名から許容範囲内の色が生成されます。 |
| Team.team | string |
チーム名。チームリストから name をコピーできます。存在しない名前を指定するとチームが作成されます。既存のチーム名を明示的に入力することを推奨します。 |
| Team.oncall | array<table> |
連絡先の配列。省略すると空配列になります。TOML では複数の [[Team.oncall]] テーブルを使用できます。 |
| Team.oncall[].name | string |
連絡先の表示名(例: オンコールメール)。 |
| Team.oncall[].type | string |
各項目に email、mobile、slack のいずれかを指定します。 |
| Team.oncall[].emails | array<string> |
type=email の場合にメールアドレスの配列を指定します(例: ["xxx@guance.com"])。 |
| Team.oncall[].mobiles | array<string> |
type=mobile の場合に電話番号の文字列配列を指定します。 |
| Team.oncall[].slack | string |
type=slack の場合に Slack チャンネルのアドレスまたは既存の設定値を指定します。 |
| Repos | array<table> |
コードリポジトリの配列。省略すると空になります。各項目は name、link、provider で構成されます。 |
| Repos[].name | string |
リポジトリの表示名。 |
| Repos[].link | string |
実際のリポジトリ URL を入力します。 |
| Repos[].provider | string |
リポジトリ提供元の表示名。 |
| Docs | array<table> |
関連する操作ドキュメントの配列。省略すると空になります。各項目は name、link、provider で構成されます。 |
| Docs[].name | string |
ドキュメントの表示名。 |
| Docs[].link | string |
顧客がアクセス可能な操作ガイドの URL を入力します。 |
| Docs[].provider | string |
コンテンツ提供元の表示名。 |
| Related | TOMLテーブル |
呼び出し時に必ず指定します。関連付けがない場合も [Related] 空テーブルを保持してください。 |
| Related.AppId | string |
リアルユーザーモニタリング(RUM)のアプリケーション ID。大文字小文字は AppId のまま保持します。RUM アプリケーションの設定または記録された app_id から取得し、省略または空値にできます。 |
| Related.DashboardUUIDs | array<string> |
組み込みビューリストから content.data[].uuid を取得し、このワークスペースの有効な組み込みビューのみを使用します。バインドしない場合は [] を指定します。 |
| Related.Tags | array<string> |
シーンタグ名の配列。詳細のレスポンスに含まれる Related.Tags をコピーできます。空配列にするとタグの関連付けがクリアされます。各名前は最大 128 文字です。 |
完全な設定例
[Team]
service = "checkout"
type = "web"
team = "team-commerce"
colour = "#40C9C9"
[[Team.oncall]]
name = "オンコールメール"
type = "email"
emails = ["xxx@guance.com"]
[[Repos]]
name = "業務リポジトリ"
link = "https://example.invalid/repos/checkout"
provider = "Git"
[[Docs]]
name = "操作マニュアル"
link = "https://example.invalid/help/checkout"
provider = "Wiki"
[Related]
AppId = ""
Tags = ["team:commerce"]
DashboardUUIDs = []
チーム検証では、先にチームが作成・送信され、その後の検証が失敗した場合でもそのチームが残る可能性があります。リクエストがタイムアウトまたは失敗した場合は、まず現在のサービスとチームを照会し、状態を確認してから再試行するかどうかを決定してください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/service_manage/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"serviceCatelog":"[Team]\nservice = \"checkout\"\ntype = \"web\"\nteam = \"team-commerce\"\ncolour = \"#40C9C9\"\n\n[[Team.oncall]]\nname = \"オンコールメール\"\ntype = \"email\"\nemails = [\"xxx@guance.com\"]\n\n[[Repos]]\nname = \"業務リポジトリ\"\nlink = \"https://example.invalid/repos/checkout\"\nprovider = \"Git\"\n\n[[Docs]]\nname = \"操作マニュアル\"\nlink = \"https://example.invalid/help/checkout\"\nprovider = \"Wiki\"\n\n[Related]\nAppId = \"\"\nTags = [\"team:commerce\"]\nDashboardUUIDs = []\n"}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.uuid | string | サービスリストの UUID。 |
| content.service | string | 保存後のサービス名。 |
| content.type | string | 保存後のサービス分類。 |
| content.declaration | object または null | ワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"uuid": "sman_example",
"service": "checkout",
"type": "web",
"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.JsonFormatError | JSON のトップレベルがオブジェクトでない | 一部の json ファイル形式エラー | リクエストボディを JSON オブジェクトとして構成してください。 |
| 400 | ft.SetFormatError | serviceCatelog を TOML として解析できない | サービスリストの toml 形式の解析に失敗 | TOML の構文を修正し、JSON 内の改行と二重引用符が正しくエスケープされていることを確認してください。 |
| 400 | ft.MissingCustomParameters | Team は存在するが service フィールドがない | service フィールドの欠落 | [Team] に service 文字列を指定してください。 |
| 400 | ft.ErrorFieldType | TOML 内のサービスタイプ、色、チーム名、配列、または連絡先タイプが要件を満たさない | {} フィールドの型エラー | TOML フィールド表に従って誤ったフィールドを修正してください。連絡先の type には email、mobile、slack のいずれかを使用します。 |
| 406 | ft.MissParamService | Team.service が空文字列 | 必須パラメータの欠落、サービス名 | 実際のサービス名を入力してください。 |
| 400 | ft.ServiceNameRepeat | 同じワークスペースに一致する有効なサービスリストが既に存在 | サービス名は既に存在します | まずリストを確認してください。新規作成で重複する場合はその UUID での変更に切り替え、変更時に重複する場合は別の名前を使用してください。 |
| 400 | ft.InvalidInnerDashboardUUID | Related.DashboardUUIDs に、ワークスペース内に存在しない、削除済み、または組み込みビューでない UUID が含まれる | 無効なダッシュボード UUID: {} | 組み込みビューリストから有効な UUID を再選択してください。関連付けしない場合は空配列を指定します。 |
| 400 | ft.TagScopeMismatch | Related.Tags 内の既存の同名タグがシーンのスコープと互換性がない | 例: team:commerce: ['monitor'] -> scene | シーンまたは汎用スコープのタグを選択するか、別の名前を使用してください。 |
| 406 | ft.ExceedMaxCharacterLimit | Related.Tags 内のタグ名が 128 文字を超える | {} が最大文字長制限を超えています | タグ名を短くしてください。 |
| 500 | ft.InternalServerError | 有効な TOML に Team または Related テーブルがない、または保存中に明示的に処理されていない構造異常が発生 | 内部エラー | [Team] と [Related] を含む完全な設定を送信してください。失敗後はチームとサービスの現状を確認してから再試行するかどうかを決定してください。 |