コンテンツにスキップ

変更



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 で再送信します。リクエストがタイムアウトした場合は、まず対象の状態を確認します。

ダウンストリームがバージョン条件の不一致を報告した場合のレスポンス

{
  "code": 424,
  "content": {
    "upstreamStatus": 412,
    "upstreamPath": "/v1/notes",
    "responseBody": {
      "message": "ETag が一致しません"
    }
  },
  "errorCode": "ft.NbookDBApiError",
  "message": "ノートサービスの呼び出しに失敗しました",
  "success": false,
  "traceId": "TRACE-EXAMPLE"
}

フィードバック

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