コンテンツにスキップ

一覧取得



POST /api/v1/notes_v2/list

概要

条件に基づいて、現在の呼び出し元から参照可能な新バージョンのノートを検索します。

呼び出し前の準備と使用手順

ノートの読み取り権限を持つ Key を使用します。一覧には、公開ノートと現在の呼び出し元のプライベートノートのみが含まれます。お気に入り項目を優先し、それ以外は最終更新日時の降順で並べ、更新されていない場合は作成日時を使用します。デフォルトではメタデータを返します。単一の本文は新バージョンのノート詳細で取得します。本文を一括で読み取る必要がある場合は、includeContent=true、正の整数のページ番号、および 100 以下の pageSize を同時に指定します。

リクエストヘッダー

パラメータ名 型 必須 説明
DF-API-KEY string Y ワークスペースの OpenAPI 認証情報。
例: <DF-API-KEY>
取得・入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。

Body リクエストパラメータ

パラメータ名 型 必須 説明
pageIndex integer 正の整数の pageSize と一緒に指定した場合にページネーションを有効にします。
null 許容: False
例: 1
取得・入力方法: ページ番号は 1 から指定します。
pageSize integer 正の整数のページサイズ。省略した場合、または正の整数のページ番号と一緒に指定しない場合はページネーションを行いません。
null 許容: False
例: 20
取得・入力方法: 1 ページあたりに必要な件数を指定します。本文を読み取る場合は最大 100 です。
search string タイトルと本文の検索に使用します。空でない query が優先されます。
null 許容: False
例: 巡检
取得・入力方法: タイトルまたは Markdown 本文中の語句を指定します。
query string 優先的に使用する全文検索語。
null 許容: False
例: 巡检
取得・入力方法: 検索対象のノートのタイトルまたは本文から検索語を選択します。
tags array 通常タグのフィルター。デフォルトではいずれか 1 つのタグの一致でヒットします。
null 許容: False
例: ["ops"]
取得・入力方法: 返却された tags 配列または既知のタグ名から値を取得します。
tagKV json キーと値のタグのマッチング。tagKVQuery と同じ名前のキーはこのフィールドが優先されます。
null 許容: False
例: {"service": "checkout"}
取得・入力方法: ノートの tagKV の結果から、マッチングが必要なキーと値をコピーします。
tagKVQuery string キーと値のタグのマッチング式。値にスペースが含まれる場合は引用符を使用します。
null 許容: False
例: service:"checkout" AND env:"prod"
取得・入力方法: 実際のキーと値で key:"value" 式を作成します。AND またはスペースで連結できます。
tagMode string 通常タグの組み合わせ方法。デフォルトは or です。
null 許容: False
選択可能な値: ['and', 'or']
例: and
取得・入力方法: すべての通常タグが一致する必要がある場合は and、いずれかが一致すればよい場合は or を使用します。
createdSource string 作成元の完全一致。例: manual、ai。省略時はフィルタリングしません。
null 許容: False
例: manual
取得・入力方法: 詳細の content.createdSource から、フィルタリングする作成元の値を取得します。
noteType string ノートタイプ。
null 許容: False
選択可能な値: ['normal', 'runbook', 'statuspages']
例: runbook
取得・入力方法: 用途に応じて normal(通常)、runbook(操作マニュアル)、statuspages(ステータスページノート)を選択します。
isPublic boolean 公開範囲によるフィルター。省略した場合は、現在の呼び出し元が参照可能なすべての一致レコードを返します。
null 許容: False
例: true
取得・入力方法: 公開ノートを検索する場合は true、現在の呼び出し元自身のプライベートノートを検索する場合は false を指定します。
tagKVRange json キーは英字、数字、アンダースコア、ハイフン、ドットのみをサポートします。gte は下限を含み、lte は上限を含みます。サポートするのはこの 2 つのフィールドのみで、少なくとも 1 つの空でない境界を指定する必要があります。両端を指定する場合、文字列は辞書順で比較され、gte は lte より大きくできません。
null 許容: False
例: {"run_date": {"gte": "2026-07-01", "lte": "2026-07-31"}}
取得・入力方法: 返却された tagKV の中で範囲を限定するキーを選択し、統一形式の文字列境界を指定します。
includeContent boolean デフォルトは false。有効にする場合、pageIndex は 1 以上、pageSize は 1~100 にします。
null 許容: False
例: false
取得・入力方法: Markdown 本文を一括で取得する必要がある場合は true に設定し、ページネーションパラメータを指定します。

パラメータ補足

検索、通常タグ、キーと値のタグの条件は必要に応じて組み合わせられます。tagKVRange は元の文字列でソートされるため、固定幅の日付または数値形式を使用することを推奨します。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/notes_v2/list' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"pageIndex":1,"pageSize":20,"query":"巡检","includeContent":true}'

レスポンス

HTTP 200、application/json。以下の例では、直接読み取れる主要なフィールドを示します。

フィールド 型 説明
content.data array<object> 現在の一覧または単一ページの一致項目。
content.data[].id integer ノートレコード番号。
content.data[].uuid string Studio ノートの識別子。noteUUID と同じです。
content.data[].noteUUID string 詳細、変更、削除のパスに使用するノート UUID。
content.data[].title string ノートのタイトル。
content.data[].name string title と同じエンティティフィールド。
content.data[].workspaceUUID string ノートが属するワークスペースの UUID。
content.data[].isPublic integer 1 は公開、0 はプライベート。
content.data[].tags array<string> 通常タグ。
content.data[].tagKV object キーと値のタグ。
content.data[].extend object ビジネス拡張設定。
content.data[].createdSource string 作成元。例: manual または ai。
content.data[].noteType string normal、runbook、statuspages のいずれか。
content.data[].etag string 現在の ETag。変更または削除時に ifMatch として使用できます。
content.data[].version integer 現在のコンテンツバージョン番号。
content.data[].nbookETag string etag と同じエンティティフィールド。
content.data[].nbookVersion integer version と同じエンティティフィールド。
content.data[].lastSyncAt integer 前回の同期日時。Unix 秒。
content.data[].syncStatus string コンテンツ同期状態。例: synced。
content.data[].syncError string 同期エラーの説明。同期済みの場合は通常空です。
content.data[].status integer ノートのステータス。
content.data[].isFavourited boolean 現在の呼び出し元がお気に入りに登録しているか。
content.data[].creator string 作成者の識別子。
content.data[].updator string 最終更新者の識別子。
content.data[].createAt number 作成日時。Unix 秒。
content.data[].updateAt number 更新日時。Unix 秒。新規作成時は -1 になることがあります。
content.data[].deleteAt number 削除日時。Unix 秒。未削除の場合は -1。
content.data[].creatorInfo object 作成者の追加情報。見つからない場合は空のオブジェクト。
content.data[].updatorInfo object 最終更新者の追加情報。見つからない場合は空のオブジェクト。
content.data[].creatorInfo.uuid string 実際のアイデンティティ情報に基づいて提供されます。識別子。
content.data[].creatorInfo.status integer 実際のアイデンティティ情報に基づいて提供されます。アカウントステータス。
content.data[].creatorInfo.wsAccountStatus integer 実際のアイデンティティ情報に基づいて提供されます。ワークスペースメンバーのステータス。
content.data[].creatorInfo.username string 実際のアイデンティティ情報に基づいて提供されます。アカウントのログイン名。
content.data[].creatorInfo.name string 実際のアイデンティティ情報に基づいて提供されます。表示名。
content.data[].creatorInfo.iconUrl string 実際のアイデンティティ情報に基づいて提供されます。アバター URL。
content.data[].creatorInfo.email string 実際のアイデンティティ情報に基づいて提供されます。アカウントのメールアドレス。API Key のアイデンティティの場合は、その識別子が返されることがあります。
content.data[].creatorInfo.mobile string 実際のアイデンティティ情報に基づいて提供されます。連絡先。
content.data[].creatorInfo.countryCode string 実際のアイデンティティ情報に基づいて提供されます。電話番号の国または地域コード。
content.data[].creatorInfo.acntWsNickname string 実際のアイデンティティ情報に基づいて提供されます。ワークスペースのニックネーム。
content.data[].updatorInfo.uuid string 実際のアイデンティティ情報に基づいて提供されます。識別子。
content.data[].updatorInfo.status integer 実際のアイデンティティ情報に基づいて提供されます。アカウントステータス。
content.data[].updatorInfo.wsAccountStatus integer 実際のアイデンティティ情報に基づいて提供されます。ワークスペースメンバーのステータス。
content.data[].updatorInfo.username string 実際のアイデンティティ情報に基づいて提供されます。アカウントのログイン名。
content.data[].updatorInfo.name string 実際のアイデンティティ情報に基づいて提供されます。表示名。
content.data[].updatorInfo.iconUrl string 実際のアイデンティティ情報に基づいて提供されます。アバター URL。
content.data[].updatorInfo.email string 実際のアイデンティティ情報に基づいて提供されます。アカウントのメールアドレス。API Key のアイデンティティの場合は、その識別子が返されることがあります。
content.data[].updatorInfo.mobile string 実際のアイデンティティ情報に基づいて提供されます。連絡先。
content.data[].updatorInfo.countryCode string 実際のアイデンティティ情報に基づいて提供されます。電話番号の国または地域コード。
content.data[].updatorInfo.acntWsNickname string 実際のアイデンティティ情報に基づいて提供されます。ワークスペースのニックネーム。
content.data[].content string Markdown 本文。一覧では includeContent を有効にした場合にのみ返されます。
content.declaration object または null ワークスペースの共通宣言。
pageInfo object ページネーションを有効にした場合、レスポンスのトップレベルに配置されます。
pageInfo.pageIndex integer 現在のページ番号。
pageInfo.pageSize integer 1 ページあたりのサイズ。
pageInfo.totalCount integer 条件に一致し、参照可能なノートの総数。
{
  "code": 200,
  "content": {
    "data": [
      {
        "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,
        "creatorInfo": {},
        "updatorInfo": {},
        "content": "# 生产巡检\n\n先查看服务可用性,再核对最近告警。"
      }
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE",
  "pageInfo": {
    "pageIndex": 1,
    "pageSize": 20,
    "totalCount": 1
  }
}

エラーレスポンス

認証、レート制限、および共通リクエストエラーについては、共通エラー定義を参照してください。

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 tagKVQuery をキーと値の式として解析できません tagKVQuery の形式エラー key:"value" に変更し、各キーと値を確認してください。
406 ft.InvalidParameter tagKVRange のキー、範囲フィールド、または上限・下限が無効です パラメータ tagKVRange が無効です gte と lte の文字列境界を使用し、少なくとも 1 つを指定してください。
400 ft.ParamsValidateError 一覧の本文を読み取るリクエストで有効なページネーションがない、または pageSize が 100 を超えています パラメータ検証失敗: pageSize 正の整数の pageIndex と 1~100 の pageSize を指定してください。
424 ft.NbookDBApiError ノートサービスのリクエスト失敗、レスポンス異常、またはサービス利用不可 ノートサービスの呼び出しに失敗しました まず content.upstreamStatus とレスポンス内容を確認してください。traceId を保持し、その後、具体的な原因に応じて再試行するか管理者に連絡してください。

フィードバック

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