コンテンツにスキップ

作成



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 が既に作成されていないか確認します。

フィードバック

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