変更¶
POST /api/v1/notes_v2/{note_uuid}/modify
概要¶
新版ノートのタイトル、本文、または設定を更新します。
呼び出し前の準備と使用手順¶
まず新版ノートの詳細で本文と etag を読み取ります。変更が必要なフィールドのみを送信でき、省略した場合は元の値が保持されます。content を送信すると本文全体が置き換えられ、空文字列を指定するとクリアできます。tags、tagKV、extend は空のコレクションを送信するとクリアできます。同時更新によって他のユーザーの変更を上書きしないよう、ifMatch を付与することを推奨します。プライベートノートは作成者 ID によって更新され、アクティブなステータスページに関連付ける場合はステータスページの設定権限も必要です。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| note_uuid | string | Y | 新版ノートの UUID。 例: nbnote_example取得または入力方法: 新版ノート一覧の content.data[].noteUUID、または作成結果の content.noteUUID からコピーします。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| title | string | ノートのタイトル。 null を許可: False 例: 本番環境の定期点検の説明取得または入力方法: ノートのタイトルに表示する文字列を入力します。 |
|
| content | string | 完全な 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 から現在値を取得するか、目的の公開範囲に合わせて設定します。 |
|
| ifMatch | string | オプションのバージョン検証。更新または削除前にこのバージョンと比較し、省略した場合は条件を付加しません。 null を許可: False 例: etag-example-1取得または入力方法: 新版ノートの詳細の content.etag から取得し、そのまま渡します。 |
|
| extend | json | クライアント拡張情報オブジェクト。 null を許可: False 例: {}取得または入力方法: 既存ノートの extend から取得し、業務要件に応じて完全な値を指定します。 |
パラメータ補足説明¶
メタデータのみを変更する場合でも、元の本文が再保存されます。新しい本文を読み取る必要がある場合は、引き続き詳細を参照してください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/notes_v2/nbnote_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"content":"# 本番環境の定期点検\n\nまずサービスの可用性を確認し、その後、最近のアラートを確認します。\n\n点検が完了しました。","ifMatch":"etag-example-1"}'
レスポンス¶
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 | 書き込み結果は false です。実際のお気に入り状態は一覧または詳細から読み取ります。 |
| 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-2",
"version": 2,
"nbookETag": "etag-example-2",
"nbookVersion": 2,
"lastSyncAt": 1785427320,
"syncStatus": "synced",
"syncError": "",
"status": 0,
"isFavourited": false,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427320,
"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 オブジェクト内に配置します。 |
| 404 | ft.NotFoundNote | アクティブなノートが存在しない、現在のワークスペースに属していない、または削除済みである | 指定されたノートが見つかりません | 現在のワークスペース、対象の noteUUID、および操作が成功したかどうかを確認します。 |
| 403 | ft.ForbiddenOperationResource | 呼び出し元 ID が他者のプライベートノートを変更または削除しようとした、または対象がアクティブなステータスページに関連付けられていて statusPage.configManage が不足している | 操作権限がありません | 対象の公開範囲とステータスページの関連付けを確認し、必要な権限を持つ呼び出し元 ID に切り替えます。 |
| 424 | ft.NbookDBApiError | ノートサービスが書き込みまたは削除を拒否した、バージョン条件が一致しない、またはリクエストが失敗した | ノートサービスの呼び出しに失敗しました | まず content.upstreamStatus を確認します。バージョン競合の場合は、新版ノートの詳細で本文と ETag を読み直し、マージ後に新しい ifMatch で再送信します。リクエストがタイムアウトした場合は、まず対象の状態を確認します。 |
ダウンストリームがバージョン条件の不一致を報告した場合のレスポンス