変更¶
POST /api/v1/service_manage/{service_uuid}/modify
概要¶
指定したサービスリストの設定を変更します。
呼び出し前の準備と使用手順¶
API Key にはサービス管理権限(trace.serviceManage)が必要です。まずサービスリスト詳細を使用して現在のTOMLをエクスポートし、編集のベースにします。引き続き使用するリポジトリ、ドキュメント、関連情報は保持してください。完全な設定を送信した後、同じUUIDで再取得して確認します。対象UUIDが無効な場合は内部エラーが返されることがあるため、先に一覧で対象を確認してください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| service_uuid | string | Y | 現在のワークスペース内のサービスリストUUID。プレフィックスは sman_ です。 null 許可: False 例: sman_example取得または入力方法: サービスリスト一覧 の content.data[].uuid から取得します。新規作成レスポンスの 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/sman_example/modify' \
-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] を含む完全な設定を送信してください。失敗後はチームとサービスの現在の状態を確認してから、再試行するか判断してください。 |
| 500 | ft.InternalServerError | パス内のサービスUUIDが存在しない、削除済み、または現在のワークスペースにありません | 内部エラー | 先にサービスリスト一覧で対象を確認してください。このエラーを直接、保存済みと見なさないでください。 |