コンテンツにスキップ

返信の作成



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 を提供してください。

フィードバック

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