返信の作成¶
POST /api/v1/issue/reply/create
概要¶
Issue に通常の返信を作成します。アップロード済みの添付ファイルのバインド、チャンネルの追加、メンバーへの @ を同時に行えます。
呼び出し前の確認と使用手順¶
まず Issue 詳細 で対象の Issue を確認します。issueUUID と extend は必須です。拡張内容がない場合は {} を渡します。添付ファイルは先にアップロードし、返信の作成時に attachmentUuids を送信してバインドします。extend.channels は Issue の既存チャンネルに追加・マージされ、この返信だけにバインドされるわけではありません。members は今回の @ 通知に使用します。成功すると返信の uuid が返され、その後返信一覧を照会できます。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取得または入力方法: 外部システムのメールアドレスを取得します。 |
|
| attachmentUuids | array | 任意のアップロード済み添付ファイル UUID 配列。空でない場合、この返信にバインドまたは再バインドします。省略または [] の場合、既存の添付ファイルは削除されません。 null を許可: True 例: []取得または入力方法: 先に 添付ファイルをアップロード を呼び出し、content.attachmentUuid を保存します。このワークスペースで実際にアップロードされ、利用可能な添付ファイルのみ使用できます。省略または [] の場合は添付ファイルを追加しません。 |
|
| content | string | 返信内容。作成時の最大長は 65535 長さ単位です。ASCII および半角カタカナは 1 文字あたり 1、その他(漢字など)は通常 1 文字あたり 2 として計算されます。空白のみの内容は 0 と計算されます。省略時は空文字列がデフォルトです。 空文字列を許可: True null を許可: True $maxCustomLength: 65535 例: 已定位到数据库慢查询,正在优化。取得または入力方法: 対応状況を入力します。添付ファイルのみの返信では省略するか空文字列を渡せます。 |
|
| extend | json | Y | 必須の拡張オブジェクト。内容がない場合は {} を渡し、null は渡さないでください。 null を許可: True 例: {}取得または入力方法: 拡張内容がない場合は {} を渡します。更新前に元の値を読み取り、完全なオブジェクト内で変更が必要なフィールドを調整します。 |
| issueUUID | string | Y | 返信が属する Issue UUID。必須です。 null を許可: False 例: issue_example取得または入力方法: Issue 一覧 または Issue 詳細 から uuid を取得します。 |
パラメータ補足¶
この API は作成前に安定した「Issue が存在しない」という業務エラーを返しません。対象の Issue が存在することを事前に確認してください。有効な内容や添付ファイルがない空の返信も作成に成功する可能性があります。クライアントは業務要件に応じて確認してください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/issue/reply/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"issueUUID":"issue_example","content":"已定位到数据库慢查询,正在优化。","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 | 作成呼び出しの ID。API Key 識別子、アカウント、またはシステム ID の場合があります。 |
| content.updator | string | 最終更新 ID。未設定の場合は空文字列です。 |
| content.createAt | integer | 作成日時(Unix 秒)。 |
| content.updateAt | integer | 最終更新日時(Unix 秒)。未更新の場合は -1 になることがあります。 |
| content.deleteAt | integer | 削除日時(Unix 秒)。未削除の場合は -1。 |
| content.issueUUID | string | 所属 Issue UUID。 |
| content.content | string または null | 返信または操作記録の内容。 |
| content.type | string | reply は通常の返信、change は操作記録、eventReply は関連イベント返信、autoDiscoveryReply は自動検出返信です。 |
| 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.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": "repim_example",
"workspaceUUID": "wksp_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785430800,
"updateAt": -1,
"deleteAt": -1,
"issueUUID": "issue_example",
"content": "已定位到数据库慢查询,正在优化。",
"type": "reply",
"extend": {},
"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.ExceedMaxLengthLimit | extend.text の長さが 3000 文字を超えている | テキストの最大長制限を超えています | プレーンテキストフィールドを短縮してください。大容量の診断資料は添付ファイルとしてアップロードしてください。 |
| 500 | ft.InternalServerError | レベルの保存、設定の保存、監査、その他の内部処理に失敗 | 内部エラー | まず現在のレベルまたは設定を読み取って結果を確認し、再試行するか判断してください。失敗が続く場合は traceId を提供してください。 |