コンテンツにスキップ

作成



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 を保持し、その後、具体的な原因に応じて再試行するか管理者に連絡してください。

フィードバック

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