作成¶
POST /api/v1/issue/add
概要¶
Issue を作成し、レベル、担当者、ソース、チャンネル、および任意の添付ファイルを設定して、後続の通知を送信します。
呼び出し前の準備と使用手順¶
まず有効なレベル一覧を照会して利用可能なレベルを選択します。最小リクエストには name、level、description、extend={} が含まれます。初期 statusType は 10 Open に固定され、作成 API は statusType を受け付けません。すべての Issue はデフォルトチャンネルに配信されます。channelUUIDs と extend.channels により、同一ワークスペースのチャンネルを追加できます。担当者を指定しない場合、既存の設定に従って担当者なしのエスカレーション通知フローに入る可能性があります。ソースが通常の手動 Issue または viewer の場合、初期化用のシステム返信タスクが投入されることもあります。現在のタスクは Obsy の change 操作レコードを生成しますが、この API では AI 分析結果を保証しません。後続の返信一覧で確認できます。API の成功は通知の到達を意味しません。通知は非同期で実行され、受信者はチャンネル購読、通知先、通知ポリシー、担当者、および今回の @ メンバーによって決まります。コンソールで通知設定と実際の到達状況を確認してください。書き込み、後続通知、添付ファイル処理は段階的に実行されます。失敗またはタイムアウトした場合は、まずリソースが作成または更新済みかどうかを照会してから再試行を判断し、重複レコードと通知を避けてください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| attachmentUuids[*] | json | アップロード済み添付ファイルの単一 UUID。 例: att_example取得または入力方法: 添付ファイルをアップロード の content.attachmentUuid を取得します。 |
|
| extend.text | json | 任意のプレーンテキスト。サーバー側の長さチェックに使用し、最大 3000 文字です。 例: 定位生产接口延迟。取得または入力方法: 説明からプレーンテキストを抽出し、3000 文字以内に収めます。省略した場合は空テキストとしてチェックされます。 |
|
| extend.channels | array | チャンネル参照配列。既にバインドされたチャンネルに追加マージされ、[] は既存のバインドをクリアしません。 例: [{"type": "#", "uuid": "chan_example", "name": "生产异常"}]取得または入力方法: チャンネル一覧 から実際のチャンネル UUID を取得し、説明内の # チャンネルを参照します。省略した場合は追加しません。 |
|
| extend.channels[*] | json | チャンネル参照オブジェクト。 例: {"type": "#", "uuid": "chan_example", "name": "生产异常"}取得または入力方法: 各項目に同一ワークスペースの実在するチャンネルを 1 つ選択します。 |
|
| extend.channels[*].uuid | json | チャンネル UUID。 例: chan_example取得または入力方法: チャンネル一覧 の content[].uuid から取得します。 |
|
| extend.channels[*].name | json | クライアント表示名。 例: 生产异常取得または入力方法: チャンネル一覧 から対応する name を取得して表示に使用します。省略できます。 |
|
| extend.channels[*].type | json | チャンネル参照マーカー。 例: #取得または入力方法: チャンネル参照では固定で # を使用します。サーバーは読み取り結果にこのマーカーを補完します。 |
|
| extend.channels[*].exists | json | 任意の表示マーカー。サーバー側のリソース検証の代替にはなりません。 例: true取得または入力方法: 有効性の証明として渡す必要はありません。照会レスポンスでは現在のリソース存在性に基づいて再計算されます。 |
|
| extend.members | array | 今回の @ メンバー参照。1 回限りの通知メールアドレスを収集するために使用し、担当者配列ではありません。 例: [{"type": "@", "uuid": "acnt_example", "name": "值班工程师"}]取得または入力方法: 対象ワークスペースのメンバー管理からアカウント UUID を取得します。省略した場合は今回の @ メンバーを追加しません。 |
|
| extend.members[*] | json | メンバー参照オブジェクト。 例: {"type": "@", "uuid": "acnt_example", "name": "值班工程师"}取得または入力方法: @ が必要な各アカウントのオブジェクトを入力します。 |
|
| extend.members[*].uuid | json | メンバーアカウント UUID。 例: acnt_example取得または入力方法: 対象ワークスペースのメンバー管理から acnt_ アカウント UUID を取得します。 |
|
| extend.members[*].name | json | クライアント表示名。 例: 值班工程师取得または入力方法: メンバーの表示名を使用します。省略できます。 |
|
| extend.members[*].type | json | メンバー参照マーカー。 例: @取得または入力方法: メンバー参照には @ を使用します。 |
|
| extend.members[*].exists | json | 任意の表示マーカー。 例: true取得または入力方法: 有効性の証明として渡す必要はなく、照会時に再計算されます。 |
|
| extend.extra | json | 外部表示情報。API の実際の認証/作成者 ID を置き換えません。 例: {}取得または入力方法: サードパーティ連携で外部操作者を表示する必要がある場合に入力します。ない場合は省略するか {} を指定します。 |
|
| extend.extra.creator | json | 作成者の表示オブジェクト。 例: {"name": "外部工单创建人", "email": "xxx@guance.com"}取得または入力方法: 連携システムの作成者を使用します。変更時、既存の creator は通常サーバー側で保持されます。 |
|
| extend.extra.creator.name | json | 表示名。省略できます。 例: 外部工单创建人取得または入力方法: 外部システムの表示名を取得します。 |
|
| extend.extra.creator.email | json | 表示メールアドレス。省略できます。 例: xxx@guance.com取得または入力方法: 外部システムのメールアドレスを取得します。例は架空のアドレスです。 |
|
| extend.extra.updator | json | 更新者の表示オブジェクト。 例: {"name": "外部工单更新人", "email": "xxx@guance.com"}取得または入力方法: 変更時は連携システムの今回の操作者情報を取得します。 |
|
| extend.extra.updator.name | json | 表示名。省略できます。 例: 外部工单更新人取得または入力方法: 外部システムの表示名を取得します。 |
|
| extend.extra.updator.email | json | 表示メールアドレス。省略できます。 例: xxx@guance.com取得または入力方法: 外部システムのメールアドレスを取得します。 |
|
| extend.manager | array | 担当者識別子配列。担当者なしの場合は [] または省略します。変更時は完全な対象配列を渡します。無効なアカウント/チーム/通知先はフィルタされる可能性があります。dutyPerson はワークスペースのタイムゾーンにおける当日のオンコールカレンダーに基づいて具体的な対象に解決され、当日の HH:MM 時間帯では判定されません。今回保存した後、その後のシフト変更には自動追従しません。 例: ["acnt_example"]取得または入力方法: 対象ワークスペースのメンバー管理から acnt_ アカウント UUID、チーム管理から group_ UUID を取得します。通知先 UUID は通知先一覧から取得します。実際のメールアドレスまたは dutyPerson を入力することもできます。 |
|
| extend.manager[*] | json | アカウント UUID、チーム UUID、通知先 UUID、メールアドレス、または dutyPerson。 例: acnt_example取得または入力方法: 対象ワークスペースのメンバー管理から acnt_ アカウント UUID、チーム管理から group_ UUID を取得します。通知先 UUID は通知先一覧から取得します。実際のメールアドレスまたは dutyPerson を入力することもできます。 |
|
| extend.linkList | array | 参考リンク配列。クライアントの必要に応じて保存されます。 例: [{"name": "处理手册", "link": "https://example.com/runbook"}]取得または入力方法: 業務側からアクセス可能な参考リンクを提供します。省略した場合は追加しません。 |
|
| extend.linkList[*] | json | リンクオブジェクト。 例: {"name": "处理手册", "link": "https://example.com/runbook"}取得または入力方法: 各項目は参考リンクを 1 つ表します。 |
|
| extend.linkList[*].name | json | リンク名。 例: 处理手册取得または入力方法: リンクの表示名を入力します。 |
|
| extend.linkList[*].link | json | リンクアドレス。 例: https://example.com/runbook取得または入力方法: アクセス可能な完全な URL を入力します。例のドメインは置き換えてください。 |
|
| extend.sourceLink | json | 任意のソースリンク。viewer の単一データ分析時に doc_time に基づいて対象レコードのクエリ時間枠を特定できます。 例: https://example.com/source?doc_time=1785430800000取得または入力方法: コンソールのソースページから完全なリンクを取得します。viewer ソースの doc_time は Unix ミリ秒を使用します。 |
|
| extend.extra.managerInfos | json | メールアドレス担当者の表示情報マップ。省略できます。 例: {"xxx@guance.com": {"name": "外部值班人"}}取得または入力方法: extend.manager 内のメールアドレスをキーとして、外部担当者の表示情報を入力します。 |
|
| extend.extra.managerInfos.邮箱.name | json | 単一のメールアドレス担当者の表示名。 例: 外部值班人取得または入力方法: メールアドレスのキーは担当者配列内のメールアドレスと一致する必要があります。氏名は外部業務システムから取得します。 |
|
| channelUUIDs[*] | json | 単一チャンネル UUID。 例: chan_example取得または入力方法: チャンネル一覧 の content[].uuid を取得します。 |
|
| attachmentUuids | array | 添付ファイル UUID 配列。作成時に添付ファイルをバインドし、[] で古い添付ファイルを削除することはできません。 null を許可: True 例: []取得または入力方法: 先に添付ファイルをアップロードを呼び出し、content.attachmentUuid を保存します。このワークスペースで実際にアップロードされ利用可能な添付ファイルのみ使用できます。省略または [] の場合は添付ファイルを追加しません。 |
|
| channelUUIDs | array | 作成時に配信するチャンネル配列。常にデフォルトチャンネルを含み、無効なチャンネルは無視されます。 null を許可: True 例: ["chan_example"]取得または入力方法: チャンネル一覧 から同一ワークスペースの有効なチャンネル UUID を取得します。省略または [] の場合はデフォルトチャンネルと extend 参照チャンネルのみを保持します。 |
|
| description | string | Y | Issue の説明。作成時に必須です。extend.text のプレーンテキスト長チェックとは区別されます。 null を許可: False 例: 定位生产接口延迟,记录处理过程。取得または入力方法: 現象、範囲、処理目標を入力します。詳細な診断資料は添付ファイルとしてアップロードできます。 |
| extend | json | Y | 必須の拡張オブジェクト。内容がない場合は {} を渡し、null を渡さないでください。 null を許可: True 例: {}取得または入力方法: 拡張内容がない場合は {} を渡します。変更前に元の値を読み取り、完全なオブジェクト内で変更が必要なフィールドを調整します。 |
| level | string | Y | 現在有効なレベル UUID。作成時に必須で、空文字列を渡すこともできます。レベルの表示名から UUID を推測しないでください。 空文字列を許可: True null を許可: False 例: system_level_1取得または入力方法: 先に有効なレベル一覧を呼び出し、実際に返された uuid を取得します。レベルを指定しない場合は空文字列を渡します。 |
| name | string | Y | Issue のタイトル。最大 256 文字です。 null を許可: False 最大長: 256 例: checkout-api 延迟异常取得または入力方法: 問題の現象に基づいて明確なタイトルを入力します。 |
| resource | string | ソースモジュール/表示名。省略時は空文字列です。 空文字列を許可: True null を許可: False 例: TRACING取得または入力方法: 実際のソースページからモジュール値またはソース名を取得します。エクスプローラーでは LOG、TRACING、EVENTS、RUM がよく使用されます。通常の手動 Issue では省略します。 |
|
| resourceType | string | ソースタイプ。event、dashboard、viewer から選択できます。作成後、本モジュールの変更 API ではソース変更を提供しません。 null を許可: False 指定可能な値: ['event', 'dashboard', 'viewer'] 例: viewer取得または入力方法: 実際にイベント、ダッシュボード、またはエクスプローラーに由来する場合のみ event/dashboard/viewer を選択します。通常の手動 Issue では省略します。 |
|
| resourceUUID | string | 対応するソース識別子。省略時は空文字列です。viewer の値を一律に dashboard UUID として扱わないでください。 空文字列を許可: True null を許可: False 例: DOC-EXAMPLE取得または入力方法: イベントソースの場合はイベントの __docid、ダッシュボードの場合は dashboard UUID、viewer の単一データの場合は __docid を入力します。エクスプローラー全体の場合は空文字列を渡せます。 |
パラメータ補足¶
添付ファイルは先に添付ファイルをアップロードを呼び出し、attachmentUuid を attachmentUuids に入力します。存在しない、または利用できない添付ファイルは内部エラーを引き起こす可能性があるため、確認してからバインドしてください。extend.channels/members の exists は表示用フィールドであり、認可の根拠ではありません。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/issue/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"checkout-api 延迟异常","level":"system_level_1","description":"定位生产接口延迟,记录处理过程。","extend":{}}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | レコード番号。Issue/返信の作成レスポンスは永続化前に構築される場合、null になることがあります。リソース操作には uuid を使用してください。 |
| content.uuid | string | リソース UUID。 |
| content.workspaceUUID | string | 所属ワークスペース UUID。 |
| content.status | integer | レコードステータス。0 は正常、3 は削除済みです。Issue の業務ステータス statusType とは区別されます。 |
| content.creator | string | 作成呼び出し元の識別情報。API Key 識別子、アカウント、またはシステム ID の場合があります。 |
| content.updator | string | 最終更新者。未設定の場合は空文字列です。 |
| content.createAt | integer | 作成時間、Unix 秒。 |
| content.updateAt | integer | 最終更新時間、Unix 秒。未更新の場合は -1 になることがあります。 |
| content.deleteAt | integer | 削除時間、Unix 秒。未削除の場合は -1 です。 |
| content.name | string | Issue のタイトル。 |
| content.level | string | レベル UUID。空文字列は未指定を表し、レベル名ではありません。 |
| content.statusType | integer | ステータス: 10 Open、15 Working、20 Resolved、25 Closed、30 Pending。 |
| content.statusTypeUpdateRecord | array<string> |
ステータス変更履歴。各項目は Unix 秒&&ステータス名の形式です。 |
| content.statusTypeUpdateRecord[] | string | 単一のステータス変更レコード。 |
| content.description | string | Issue の説明。 |
| content.resourceType | string | ソースタイプ。event、dashboard、viewer など。自動生成の場合は checker、keyeventAutoDiscovery などになることもあります。 |
| content.resourceUUID | string | 関連ソース識別子。具体的な意味はソースタイプによって異なります。 |
| content.resource | string | ソースモジュールまたは名前。例: LOG、TRACING、EVENTS、RUM。 |
| content.repeatType | string | 自動検出された問題の重複タイプ。new、repeat、regression を指定でき、手動作成時は空の場合があります。 |
| content.subIdentify | string | ソース定義の関連サブ識別子。手動作成時は通常空です。 |
| content.resolveAt | integer | 最後に Resolved または Closed に設定された時間、Unix 秒。一度も復旧していない場合は -1 です。再オープンしてもこの履歴時間は自動的にクリアされません。 |
| content.eventCount | integer | 関連イベントの記録数。 |
| content.eventCountUpdateAt | integer | 関連イベント数の最終更新時間、Unix 秒。未記録の場合は -1 です。 |
| content.triggerRecord | object | 後方互換フィールド。通知トリガーの制御パラメータとしては使用されません。 |
| content.extend | object | 拡張内容。リクエストではオブジェクト {} を渡し、null を渡さないでください。メンバー、チャンネル、担当者などの構造はパラメータ表を参照してください。 |
| content.extend.text | string | 長さチェックに使用するプレーンテキスト。最大 3000 文字です。 |
| content.extend.channels | array<object> |
説明で参照されたチャンネル。uuid、name、type、exists を含みます。返却時、exists は現在のリソース存在性に基づいて更新されます。 |
| content.extend.channels[].uuid | string | チャンネル UUID。 |
| content.extend.channels[].name | string または null | 表示名。 |
| content.extend.channels[].type | string | チャンネル参照マーカー #。 |
| content.extend.channels[].exists | boolean | 返却時に該当チャンネルが存在するかどうか。 |
| content.extend.members | array<object> |
説明で @ されたメンバー参照。uuid、name、type、exists を含みます。 |
| content.extend.members[].uuid | string | メンバーアカウント UUID。 |
| content.extend.members[].name | string または null | 表示名。 |
| content.extend.members[].type | string | メンバー参照マーカー @。 |
| content.extend.members[].exists | boolean | 返却時に該当アカウントが存在するかどうか。 |
| content.extend.manager | array<string> |
担当者識別子配列。Issue でのみ使用されます。メンバー/チーム/通知先/メールアドレスなどは有効性に応じて正規化されます。 |
| content.extend.manager[] | string | 単一の担当者識別子。 |
| content.extend.linkList | array<object> |
業務参考リンク。 |
| content.extend.linkList[].name | string | リンク表示名。 |
| content.extend.linkList[].link | string | 業務 URL。 |
| content.extend.sourceLink | string | ソースページリンク。存在する場合はクライアントが入力します。 |
| content.extend.extra | object | サードパーティ連携の表示情報。API の実際の認証 ID は変更しません。 |
| content.extend.extra.creator | object | サードパーティ作成者の表示情報。name、email を含めることができます。 |
| content.extend.extra.creator.name | string | 作成者表示名。 |
| content.extend.extra.creator.email | string | 作成者表示メールアドレス。 |
| content.extend.extra.updator | object | サードパーティ更新者の表示情報。name、email を含めることができます。 |
| content.extend.extra.updator.name | string | 更新者表示名。 |
| content.extend.extra.updator.email | string | 更新者表示メールアドレス。 |
| content.extend.extra.managerInfos | object | 担当者メールアドレスをキーとする表示情報マップ。Issue でのみ使用されます。 |
| content.extend.extra.managerInfos.邮箱.name | string | 対応するメールアドレス担当者の表示名。 |
| content.extend のその他のフィールド | JSON | クライアントが保存するその他の拡張情報。すべてが業務動作をトリガーするわけではありません。 |
| content.declaration | object または null | ワークスペースの共通宣言。content のこの階層にのみ付加されます。 |
{
"code": 200,
"content": {
"id": null,
"uuid": "issue_example",
"workspaceUUID": "wksp_example",
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785430800,
"updateAt": 1785430800,
"deleteAt": -1,
"name": "checkout-api 延迟异常",
"level": "system_level_1",
"statusType": 10,
"statusTypeUpdateRecord": [],
"description": "定位生产接口延迟,记录处理过程。",
"resourceType": "",
"resourceUUID": "",
"resource": "",
"repeatType": "",
"subIdentify": "",
"extend": {},
"resolveAt": -1,
"eventCount": 0,
"eventCountUpdateAt": -1,
"triggerRecord": {},
"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 オブジェクトを送信します。 |
| 406 | ft.IssueLevelNotExists | level が現在のワークスペースの有効なレベル集合に属していない | レベル設定が存在しない | 先に有効なレベル一覧を照会し、返された uuid を取得します。レベルを設定しない場合はパラメータ説明に従って空文字列を渡せます。 |
| 406 | ft.ExceedMaxLengthLimit | extend.text の長さが 3000 文字を超えている | テキストの最大長制限を超過 | プレーンテキストフィールドを短縮し、大容量の診断資料は添付ファイルとしてアップロードします。 |
| 400 | ft.UnsupportFreeIssueManager | 制限されたワークスペースプランで、本ワークスペースのメンバーではない外部メールアドレスを担当者として使用 | 無料プランワークスペースでは、インシデントの担当者を外部メールアドレスにすることはできません | 本ワークスペースのメンバーを選択するか、外部メールアドレス担当者をサポートするプランか確認します。 |
| 404 | ft.NotFoundChannel | 現在のワークスペースに利用可能なデフォルトチャンネルがない | 指定チャンネルが見つかりません | コンソールでチャンネル設定を確認し、デフォルトチャンネルを復元してから再試行します。 |
| 500 | ft.InternalServerError | レベルまたは設定の保存、監査、その他の内部処理に失敗 | 内部エラー | 先に現在のレベルまたは設定を読み取って結果を確認してから再試行を判断します。継続的に失敗する場合は traceId を提供してください。 |
| 503 | ft.QueryServiceUnavailable | viewer の単一ソース照会時に、上流のクエリサービスが 503 を返す | クエリサービスは一時的に利用できません。しばらくしてから再試行してください | content.retryable が true の場合はバックオフして再試行します。Issue が既に作成されていないか先に確認し、重複を避けてください。 |
| 406 | ft.KodoRequestDeadlineExceeded | viewer ソースのデータクエリがタイムアウト | データクエリがタイムアウトしました。原因として、データ量が多すぎる、ネットワーク遅延、サーバー負荷が高すぎるなどが考えられます。以下の方法で解決できます: 1. フィルター条件を追加するか時間範囲を狭めてから再度クエリを実行します。 2. しばらく待ってから再度クエリを試行します。 |
ソースレコードと sourceLink 内の doc_time を確認して再試行します。継続的に失敗する場合は traceId を提供してください。 |
| 406 | ft.KodoTooManyRows | viewer ソースのデータクエリが上限を超過 | クエリ対象のデータ量が最大数制限を超えています。フィルター条件を追加するか時間範囲を縮小してから再度クエリを実行してください。 | 単一ソースの resourceUUID と doc_time を確認し、無関係なデータのヒットを減らします。 |
| 429 | ft.KodoServerOverloaded | viewer ソースのデータクエリサービスが混雑している | 現在のリクエストが多すぎます。しばらくしてから再試行してください。 | バックオフして再試行し、先に Issue が既に作成されていないか確認します。 |