作成¶
POST /api/v1/notes_v2/create
概要¶
新しいバージョンのノートを作成し、Markdown 本文を保存します。
呼び出し前の準備と使用手順¶
ノート管理権限を持つ Key を使用します。タイトルと Markdown 文字列を送信すると、新しいノートが作成されます。レスポンスの noteUUID と etag を保存してください。本文は新版ノート詳細で読み取れます。リクエストがタイムアウトした場合は、まず一覧で新しいノートが既に存在しないか確認してから、再試行するかどうかを判断します。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| title | string | Y | ノートのタイトル。 null 許可: False 例: 生产巡检说明取得または入力方法: ノートのタイトルに表示する文字列を入力します。 |
| content | string | Y | 完全な Markdown 本文文字列。 null 許可: False 例: "# 生产巡检\n\n先查看服务可用性,再核对最近告警。"取得または入力方法: 保存する Markdown テキストを入力します。JSON 文字列の改行はエスケープを使用します。 |
| tags | array | 通常タグの文字列配列。 null 許可: False 例: ["ops"]取得または入力方法: 既存ノートの tags からコピーするか、グループ化/フィルタリングに使用するタグ名を直接入力します。 |
|
| tagKV | json | キーと値のタグオブジェクト。文字列のキーと値の使用を推奨します。 null 許可: False 例: {"service": "checkout"}取得または入力方法: 既存ノートの tagKV からコピーするか、業務上の取り決めに従ってキーと値を入力します。 |
|
| isPublic | int | 数値 1 は公開、0 は非公開です。省略時は公開がデフォルトです。 null 許可: False 例: 1取得または入力方法: ノート詳細の isPublic から現在値を取得するか、対象の可視範囲に応じて設定します。 |
|
| extend | json | クライアント拡張情報オブジェクト。 null 許可: False 例: {}取得または入力方法: 既存ノートの extend から取得し、業務要件に応じて完全な値を指定します。 |
|
| noteType | string | 指定しない場合は normal を使用します。 null 許可: False 選択可能な値: ['normal', 'runbook', 'statuspages'] 例: runbook取得または入力方法: 用途に応じて normal(通常)、runbook(操作マニュアル)、statuspages(ステータスページノート)を選択します。 |
パラメータ補足説明¶
この API は JSON を受け取り、content フィールドに Markdown テキストを入力します。作成すると新しい noteUUID が生成されます。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/notes_v2/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"title":"生产巡检说明","content":"# 生产巡检\n\n先查看服务可用性,再核对最近告警。","tags":["ops"],"tagKV":{"service":"checkout"},"noteType":"runbook"}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer | ノートレコード番号。 |
| content.uuid | string | Studio ノート識別子。noteUUID と同じです。 |
| content.noteUUID | string | 詳細、変更、削除パスで使用するノート UUID。 |
| content.title | string | ノートのタイトル。 |
| content.name | string | title と同じエンティティフィールド。 |
| content.workspaceUUID | string | ノートが属するワークスペース UUID。 |
| content.isPublic | integer | 1 は公開、0 は非公開。 |
| content.tags | array<string> |
通常タグ。 |
| content.tagKV | object | キーと値のタグ。 |
| content.extend | object | 業務拡張設定。 |
| content.createdSource | string | 作成元。例: manual または ai。 |
| content.noteType | string | normal、runbook、または statuspages。 |
| content.etag | string | 現在の ETag。変更または削除時に ifMatch として使用できます。 |
| content.version | integer | 現在のコンテンツバージョン番号。 |
| content.nbookETag | string | etag と同じエンティティフィールド。 |
| content.nbookVersion | integer | version と同じエンティティフィールド。 |
| content.lastSyncAt | integer | 最終同期時刻。Unix 秒。 |
| content.syncStatus | string | コンテンツ同期状態。例: synced。 |
| content.syncError | string | 同期エラーの説明。同期済みの場合は通常空です。 |
| content.status | integer | ノートの状態。 |
| content.isFavourited | boolean | 現在のアイデンティティでお気に入りに登録されているか。 |
| content.creator | string | 作成者の ID 識別子。 |
| content.updator | string | 最終更新者の ID 識別子。 |
| content.createAt | number | 作成時刻。Unix 秒。 |
| content.updateAt | number | 更新時刻。Unix 秒。新規作成時は -1 の場合があります。 |
| content.deleteAt | number | 削除時刻。Unix 秒。未削除の場合は -1。 |
| content.declaration | object または null | ワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": 42,
"uuid": "nbnote_example",
"noteUUID": "nbnote_example",
"title": "生产巡检说明",
"name": "生产巡检说明",
"workspaceUUID": "wksp_example",
"isPublic": 1,
"tags": [
"ops"
],
"tagKV": {
"service": "checkout"
},
"extend": {},
"createdSource": "manual",
"noteType": "runbook",
"etag": "etag-example-1",
"version": 1,
"nbookETag": "etag-example-1",
"nbookVersion": 1,
"lastSyncAt": 1785427200,
"syncStatus": "synced",
"syncError": "",
"status": 0,
"isFavourited": false,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては、共通エラー定義を参照してください。
HTTP 424 を受信した場合、content.upstreamStatus はダウンストリームが返したステータスです。接続異常時は 0 の場合があります。content.upstreamPath は該当する失敗リクエストのパス、content.responseBody はダウンストリームのエラー内容です。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータの解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON 構文は有効だが、リクエストのトップレベルがオブジェクトではない | 一部の json ファイルの形式エラー | パラメータを JSON オブジェクト内に配置してください。 |
| 406 | ft.MissingParameterValue | タイトルが必須であり、かつ空である | パラメータ title がありません | 空でないタイトルを入力して再試行してください。 |
| 424 | ft.NbookDBApiError | ノートサービスへのリクエスト失敗、レスポンス異常、またはサービス利用不可 | ノートサービスの呼び出しに失敗しました | まず content.upstreamStatus とレスポンス内容を確認してください。traceId を保持し、その後、具体的な原因に応じて再試行するか管理者に連絡してください。 |