作成¶
POST /api/v1/channel/add
概要¶
インシデントチャンネルを作成し、通知先とエスカレーション通知を設定します。
呼び出し前の確認と使用手順¶
まずチャンネル簡易リストで名前を確認します。作成に最低限必要なのは name のみです。名前に default は使用しないでください。通知を送信する場合は、実際の通知先 UUID を事前に準備してください。例ではチャンネルのみを作成しており、通知を設定する際はパラメータ表に従って完全なフィールドを別途送信します。チャンネルとエスカレーショントリガー設定は段階的に保存されます。タイムアウトまたはエラーが発生した場合は、まずチャンネルの状態を確認してから再試行するフィールドを決定し、重複作成を避けてください。エスカレーション通知は、ルールを有効化または更新した後に新規作成され、まだ終了しておらず担当者がいない Issue を対象とします。triggerTime を超えると定期タスクによってチェックされるため、正確なカウントダウンではありません。このタスクは、ワークスペース内で有効な担当者なしエスカレーション通知ポリシーにも依存します。メッセージを受信しない場合は、通知ポリシー、通知先、およびサイトのタスクスイッチを確認してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| notifyTarget[*] | string | 単一の通知先 UUID。 例: notify_example取得または入力方法: 通知先リストを使用して同一ワークスペース内に設定済みの通知先を検索し、content.data[].uuid を取得します。 |
|
| notifyUpgradeCfg.notifyTarget[*] | string | 単一のエスカレーション通知先 UUID。 例: notify_example取得または入力方法: 通知先リストを使用して同一ワークスペース内に設定済みの通知先を検索し、content.data[].uuid を取得します。 |
|
| description | string | チャンネルの説明。最大 256 文字。 空文字列を許可: True null を許可: False 最大長: 256 例: 生产异常协作频道取得または入力方法: チャンネルの用途に応じて入力します。空文字列を渡すとクリアできます。 |
|
| name | string | Y | チャンネル名。最大 256 文字。 null を許可: False 最大長: 256 例: 生产异常取得または入力方法: チャンネル簡易リストで既存の名前を確認し、このワークスペース内で未使用の名前を選択します。 |
| notifyTarget | array | 通知先 UUID の完全な配列。[] を渡すと設定をクリアします。 null を許可: False 例: ["notify_example"]取得または入力方法: 通知先リストを使用して同一ワークスペース内に設定済みの通知先を検索し、content.data[].uuid を取得します。 |
|
| notifyUpgradeCfg | json | エスカレーション通知の完全な設定。このオブジェクトを渡す場合は、triggerTime と notifyTarget を同時に指定する必要があります。 null を許可: False 例: {"triggerTime": 300, "notifyTarget": ["notify_example"]}取得または入力方法: 業務上の待機時間に応じて秒数を選択し、実際の通知先 UUID を使用します。 |
|
| notifyUpgradeCfg.notifyTarget | array | 条件付き必須 | エスカレーション通知先 UUID の完全なリスト。triggerTime=0 と組み合わせて無効化します。 null を許可: False 例: ["notify_example"]取得または入力方法: 通知先リストを使用して同一ワークスペース内に設定済みの通知先を検索し、content.data[].uuid を取得します。 |
| notifyUpgradeCfg.triggerTime | integer | 条件付き必須 | エスカレーション通知を待機する秒数。0 以外の場合は、ルールを有効化するために少なくとも 1 つの通知先も必要です。 null を許可: False 例: 300取得または入力方法: 正の整数の秒数を入力します。たとえば 300 は 5 分間の待機を意味します。無効化する場合は、空の notifyTarget 配列とともに 0 を渡します。 |
パラメータの補足説明¶
notifyUpgradeCfg は、0 以外の triggerTime と空でない notifyTarget を同時に指定した場合にのみ、エスカレーショントリガー設定を作成します。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/channel/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"生产异常","description":"生产异常协作频道"}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | データベースレコード番号。作成時は永続化前にレスポンスを構築するため null になる可能性があります。リソースの操作には uuid を使用してください。 |
| content.uuid | string | チャンネル UUID。変更、削除、または購読に使用します。 |
| content.workspaceUUID | string | チャンネルが属するワークスペース。 |
| content.name | string | チャンネル名。default はデフォルトチャンネルを表します。 |
| content.description | string | チャンネルの説明。 |
| content.notifyTarget | array<string> |
このチャンネルに直接設定された通知先 UUID。 |
| content.notifyTarget[] | string | 単一の通知先 UUID。 |
| content.notifyUpgradeCfg | object | エスカレーション通知設定。未設定の場合は空のオブジェクトです。 |
| content.notifyUpgradeCfg.triggerTime | integer | エスカレーション通知をトリガーするまでの待機時間(秒)。 |
| content.notifyUpgradeCfg.notifyTarget | array<string> |
エスカレーション通知先 UUID のリスト。 |
| content.notifyUpgradeCfg.notifyTarget[] | string | エスカレーション通知先 UUID。 |
| content.status | integer | レコードのステータス。正常時は 0 です。 |
| content.creator | string | 作成呼び出し元。 |
| content.updator | string | 最終更新呼び出し元。未更新の場合は空文字列になることがあります。 |
| content.createAt | integer | 作成時刻(Unix 秒)。 |
| content.updateAt | integer | 更新時刻(Unix 秒)。未更新の場合は -1 です。 |
| content.deleteAt | integer | 削除時刻(Unix 秒)。未削除の場合は -1 です。 |
| content.declaration | object または null | ワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": null,
"uuid": "chan_example",
"workspaceUUID": "wksp_example",
"name": "生产异常",
"description": "生产异常协作频道",
"notifyTarget": [],
"notifyUpgradeCfg": {},
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"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.ChannelNameRepeat | 同名のチャンネルが存在するか、同名の同時作成が処理中です | チャンネル名が重複しています | まず現在のチャンネルリストを確認してください。同時作成の場合はしばらく待ってから、再試行が必要かどうかを確認してください。 |
| 400 | ft.InvalidChannelName | 作成時に name が default です | default をチャンネル名として使用することはできません | カスタムのチャンネル名に変更してください。 |