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