搜尋整個kintone

跨範圍搜尋應用程式的記錄、主題的貼文等資料。

目錄

HTTP 方法POST
URLhttps://sample.cybozu.com/k/v1/search.json
URL(從所有已參加的訪客空間中搜尋時)https://sample.cybozu.com/k/guest/v1/search.json
URL(從特定訪客空間中搜尋時)https://sample.cybozu.com/k/guest/GUEST_SPACE_ID/v1/search.json
認證 密碼驗證 , 工作階段認證
Content-Typeapplication/json

請求參數

參數名稱 類型 必須 說明
query 陣列 必須 搜尋條件
指定1個以上、20個以下。
指定多個時,返回符合所有條件的資料。
query[].operator 字串 必須 搜尋條件的評估方式
指定以下值之一。
  • AND:返回包含所有搜尋詞的資料
  • OR:返回包含任一搜尋詞的資料
  • NOT:返回不包含搜尋詞的資料
如果query中不含任何使用AND或OR的搜尋條件,搜尋結果將為空。
query[].keywords 陣列 必須 搜尋詞的陣列
指定1個以上、20個以下。
每個搜尋詞指定1個字元以上、50個字元以下。
整個query最多可指定20個搜尋詞。超過時將返回錯誤。
types 陣列 可省略 搜尋目標的資料類型
指定以下值之一。
  • RECORD:記錄
  • RECORD_COMMENT:記錄回覆
  • SPACE:空間
  • THREAD:主題
  • THREAD_COMMENT:主題的回覆
  • PEOPLE_COMMENT:用戶的回覆
  • MESSAGE_COMMENT:訊息的回覆
  • ATTACHMENT:附件
省略時,以所有類型為搜尋目標。
scopes 陣列 可省略 搜尋範圍
指定20個以下。
指定多個時,返回符合任一條件的資料。
scopes[].scope 字串 必須 搜尋範圍的類型
指定以下值之一。
  • APP:應用程式
  • SPACE:空間
  • PEOPLE:用戶
  • MESSAGE:訊息
指定scopes時為必填。
scopes[].ids 陣列 可省略 應用程式ID或空間ID
指定20個以下。
scopes[].scope為APP或SPACE時,可透過指定應用程式ID或空間ID,限定作為搜尋範圍的應用程式或空間。省略時,以所有應用程式或所有空間為搜尋範圍。scopes[].scope為PEOPLE或MESSAGE時,無法指定。
scopes[].codes 陣列 可省略 使用者的登入名稱
指定20個以下。
scopes[].scope為PEOPLE或MESSAGE時,可透過指定用戶的擁有者或訊息對象使用者的登入名稱,限定作為搜尋範圍的用戶或訊息。省略時,以所有用戶或所有訊息為搜尋範圍。scopes[].scope為APP或SPACE時,無法指定。
excludeScopes 陣列 可省略 要排除的搜尋範圍
指定20個以下。
指定多個時,返回符合所有條件的資料。
同時指定scopes和excludeScopes時,返回同時符合兩者條件的資料。因此,兩者範圍重疊時,以excludeScopes為優先。
excludeScopes[].scope 字串 必須 要排除的搜尋範圍的類型
指定以下值之一。
  • APP:應用程式
  • SPACE:空間
  • PEOPLE:用戶
  • MESSAGE:訊息
指定excludeScopes時為必填。
excludeScopes[].ids 陣列 可省略 應用程式ID或空間ID
指定20個以下。
excludeScopes[].scope為APP或SPACE時,可透過指定應用程式ID或空間ID,限定要從搜尋範圍排除的應用程式或空間。省略時,從搜尋範圍排除所有應用程式或所有空間。excludeScopes[].scope為PEOPLE或MESSAGE時,無法指定。
excludeScopes[].codes 陣列 可省略 使用者的登入名稱
指定20個以下。
excludeScopes[].scope為PEOPLE或MESSAGE時,可透過指定用戶的擁有者或訊息對象使用者的登入名稱,限定要從搜尋範圍排除的用戶或訊息。省略時,從搜尋範圍排除所有用戶或所有訊息。excludeScopes[].scope為APP或SPACE時,無法指定。
createdAfter 字串 可省略 建立時間的下限
返回建立時間等於或晚於指定日期與時間的資料。無法指定比createdBefore更晚的日期與時間。
有關日期與時間的格式,請參閱以下頁面。
日期和時間格式
createdBefore 字串 可省略 建立時間的上限
返回建立時間等於或早於指定日期與時間的資料。無法指定比createdAfter更早的日期與時間。
有關日期與時間的格式,請參閱以下頁面。
日期和時間格式
creators 陣列 可省略 建立人的登入名稱
指定20個以下。
includeSynonyms 布林值或字串 可省略 是否連同搜尋詞的異體寫法、縮寫及同義詞一併搜尋
省略時為false。
sort 物件 可省略 排序條件
sort.by 字串 可省略 排序的依據
指定以下值之一。
  • RELEVANCE:與搜尋詞的關聯度
  • CREATED_AT:建立時間
省略時為RELEVANCE。
sort.order 字串 可省略 排序的方向
指定以下值之一。
  • ASC:升序
  • DESC:降序
省略時為DESC。
sort.by為RELEVANCE時,無法指定ASC。
limit 數值或字串 可省略 最大取得筆數
指定1以上、20以下。
省略時為20。
即使仍有符合搜尋條件的資料,也可能在未達最大取得筆數的狀態下返回回應。是否仍有符合搜尋條件的資料,請依回應中nextPageToken屬性是否有值來判斷。
pageToken 字串 可省略 用於取得後續搜尋結果的權杖
首次請求時省略。如果要取得上次搜尋結果的後續內容,請指定上次回應中包含的nextPageToken的值。
權杖的有效期限為發行後30分鐘。指定過期的權杖時將返回錯誤。

應答屬性

屬性名稱 類型 說明
hits 陣列 搜尋結果
hits[].type 字串 搜尋結果的類型
返回以下其中之一。
  • RECORD
  • RECORD_COMMENT
  • SPACE
  • THREAD
  • THREAD_COMMENT
  • PEOPLE_COMMENT
  • MESSAGE_COMMENT
  • ATTACHMENT
hits[].url 字串 URL
此搜尋結果為附件時,為附加目標的URL。
hits[].snippets 陣列 搜尋詞周圍的文字
最多返回3筆。
hits[].record 物件 記錄的資訊
僅在此搜尋結果為記錄,或為附加於記錄的檔案時存在。
hits[].record.appId 字串 應用程式ID
hits[].record.appName 字串 應用程式名稱
hits[].record.recordId 字串 記錄ID
hits[].record.recordTitle 字串 記錄標題
hits[].record.createdAt 字串 建立時間
沒有建立時間欄位的檢視權限時為null。
hits[].record.creator 物件 建立人
沒有建立人欄位的檢視權限時為null。
hits[].record.creator.code 字串 建立人的登入名稱
hits[].record.creator.name 字串 建立人的顯示名稱
hits[].record.matchedFields 陣列 符合搜尋詞的欄位
hits[].record.matchedFields[].code 字串 欄位代碼
hits[].record.matchedFields[].label 字串 欄位名稱
hits[].record.spaceId 字串 空間ID
不是空間內應用程式的記錄時為null。
hits[].record.spaceName 字串 空間名稱
不是空間內應用程式的記錄時為null。
hits[].recordComment 物件 記錄回覆的資訊
僅在此搜尋結果為記錄回覆時存在。
hits[].recordComment.appId 字串 應用程式ID
hits[].recordComment.appName 字串 應用程式名稱
hits[].recordComment.recordId 字串 記錄ID
hits[].recordComment.recordTitle 字串 記錄標題
hits[].recordComment.commentId 字串 回覆ID
hits[].recordComment.createdAt 字串 建立時間
hits[].recordComment.creator 物件 建立人
hits[].recordComment.creator.code 字串 建立人的登入名稱
hits[].recordComment.creator.name 字串 建立人的顯示名稱
hits[].recordComment.spaceId 字串 空間ID
不是空間內應用程式的記錄時為null。
hits[].recordComment.spaceName 字串 空間名稱
不是空間內應用程式的記錄時為null。
hits[].space 物件 空間的資訊
僅在此搜尋結果為空間,或為附加於空間的檔案時存在。
hits[].space.spaceId 字串 空間ID
hits[].space.spaceName 字串 空間名稱
hits[].space.createdAt 字串 建立時間
hits[].space.creator 物件 建立人
hits[].space.creator.code 字串 建立人的登入名稱
hits[].space.creator.name 字串 建立人的顯示名稱
hits[].thread 物件 主題的資訊
僅在此搜尋結果為主題,或為附加於主題的檔案時存在。
hits[].thread.threadId 字串 主題ID
hits[].thread.threadName 字串 主題名稱
hits[].thread.spaceId 字串 空間ID
hits[].thread.spaceName 字串 空間名稱
hits[].thread.createdAt 字串 建立時間
hits[].thread.creator 物件 建立人
hits[].thread.creator.code 字串 建立人的登入名稱
hits[].thread.creator.name 字串 建立人的顯示名稱
hits[].threadComment 物件 主題的回覆的資訊
僅在此搜尋結果為主題的回覆,或為附加於主題回覆的檔案時存在。
hits[].threadComment.commentId 字串 回覆的ID
hits[].threadComment.replyId 字串 回應的ID
此搜尋結果不是回應時為null。
hits[].threadComment.spaceId 字串 空間ID
hits[].threadComment.spaceName 字串 空間名稱
hits[].threadComment.threadId 字串 主題ID
hits[].threadComment.threadName 字串 主題名稱
hits[].threadComment.createdAt 字串 建立時間
hits[].threadComment.creator 物件 建立人
hits[].threadComment.creator.code 字串 建立人的登入名稱
hits[].threadComment.creator.name 字串 建立人的顯示名稱
hits[].peopleComment 物件 用戶的回覆的資訊
僅在此搜尋結果為用戶的回覆,或為附加於用戶回覆的檔案時存在。
hits[].peopleComment.commentId 字串 回覆的ID
hits[].peopleComment.replyId 字串 回應的ID
此搜尋結果不是回應時為null。
hits[].peopleComment.owner 物件 用戶的擁有者
hits[].peopleComment.owner.code 字串 用戶的擁有者的登入名稱
hits[].peopleComment.owner.name 字串 用戶的擁有者的顯示名稱
hits[].peopleComment.createdAt 字串 建立時間
hits[].peopleComment.creator 物件 建立人
hits[].peopleComment.creator.code 字串 建立人的登入名稱
hits[].peopleComment.creator.name 字串 建立人的顯示名稱
hits[].messageComment 物件 訊息的回覆的資訊
僅在此搜尋結果為訊息的回覆,或為附加於訊息回覆的檔案時存在。
hits[].messageComment.commentId 字串 回覆的ID
hits[].messageComment.createdAt 字串 建立時間
hits[].messageComment.creator 物件 建立人
為填寫此回覆的使用者。
hits[].messageComment.creator.code 字串 建立人的登入名稱
hits[].messageComment.creator.name 字串 建立人的顯示名稱
hits[].messageComment.recipient 物件 回覆的接收者
為訊息參加者中,非建立人的另一位使用者。
hits[].messageComment.recipient.code 字串 接收者的登入名稱
hits[].messageComment.recipient.name 字串 接收者的顯示名稱
hits[].attachment 物件 附件的資訊
僅在此搜尋結果為附件時存在。
hits[].attachment.attachedTo 字串 附加目標的類型
返回以下其中之一。
  • RECORD
  • SPACE
  • THREAD
  • THREAD_COMMENT
  • PEOPLE_COMMENT
  • MESSAGE_COMMENT
hits[].attachment.fileKey 字串 檔案金鑰
hits[].attachment.name 字串 檔案名稱
hits[].attachment.createdAt 字串 建立時間
附加於記錄的檔案,在沒有建立時間欄位的檢視權限時為null。
hits[].attachment.creator 物件 建立人
附加於記錄的檔案,在沒有建立人欄位的檢視權限時為null。
hits[].attachment.creator.code 字串 建立人的登入名稱
hits[].attachment.creator.name 字串 建立人的顯示名稱
nextPageToken 字串 用於取得後續搜尋結果的權杖
請求下一頁時,指定於請求參數的pageToken。
不存在下一頁時為null。

所需存取權限

無

以用於認證的使用者具有檢視權限的資料為對象進行搜尋。

範例

1
2
3
4
{
  "X-Cybozu-Authorization": "QWRtaW5pc3RyYXRvcjpjeWJvenU=",
  "Content-Type": "application/json"
}

有關請求頭的詳細資訊,請參閱通用規格。 kintone REST API通用規格

搜尋同時包含abc和def的資料的請求主體範例。

1
2
3
4
5
6
7
8
{
  "query": [
    {
      "operator": "AND",
      "keywords": ["abc", "def"]
    }
  ]
}

搜尋包含abc但不包含def的資料的請求主體範例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "query": [
    {
      "operator": "AND",
      "keywords": ["abc"]
    },
    {
      "operator": "NOT",
      "keywords": ["def"]
    }
  ]
}

從應用程式1和應用程式2中搜尋包含abc的附件的請求主體範例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "query": [
    {
      "operator": "AND",
      "keywords": ["abc"]
    }
  ],
  "types": ["ATTACHMENT"],
  "scopes": [
    {
      "scope": "APP",
      "ids": [1, 2]
    }
  ]
}

從空間1中搜尋包含abc的資料,但排除空間1中應用程式2的資料的請求主體範例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "query": [
    {
      "operator": "AND",
      "keywords": ["abc"]
    }
  ],
  "scopes": [
    {
      "scope": "SPACE",
      "ids": [1]
    }
  ],
  "excludeScopes": [
    {
      "scope": "APP",
      "ids": [2]
    }
  ]
}

依建立時間升序搜尋使用者user1在特定期間內建立的資料的請求主體範例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "query": [
    {
      "operator": "AND",
      "keywords": ["abc"]
    }
  ],
  "creators": ["user1"],
  "createdAfter": "2026-05-01T00:00:00+09:00",
  "createdBefore": "2026-05-31T23:59:59+09:00",
  "sort": {
    "by": "CREATED_AT",
    "order": "ASC"
  }
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
{
  "hits": [
    {
      "type": "RECORD",
      "url": "https://sample.cybozu.com/k/760/show#record=12787",
      "snippets": [
        "以支援業務為目的,重新整備了提案資料的範本。"
      ],
      "record": {
        "appId": "760",
        "appName": "活動報告",
        "recordId": "12787",
        "recordTitle": "提升客戶應對效率",
        "createdAt": "2024-03-28T09:13:00.000Z",
        "creator": {
          "code": "user1",
          "name": "使用者1"
        },
        "matchedFields": [
          {
            "code": "summary",
            "label": "概要"
          }
        ],
        "spaceId": "18",
        "spaceName": "業務本部"
      }
    },
    {
      "type": "ATTACHMENT",
      "url": "https://sample.cybozu.com/k/25929/show#record=329",
      "snippets": [
        "為提升商談管理效率,更新了業務支援系統。"
      ],
      "record": {
        "appId": "25929",
        "appName": "檔案管理",
        "recordId": "329",
        "recordTitle": "329",
        "createdAt": "2025-08-04T06:53:00.000Z",
        "creator": {
          "code": "user2",
          "name": "使用者2"
        },
        "matchedFields": [],
        "spaceId": null,
        "spaceName": null
      },
      "attachment": {
        "attachedTo": "RECORD",
        "fileKey": "20250804065242B76047BB21494FE5BD4FA54590A50984300",
        "name": "預算管理表_2025年度.xlsx",
        "createdAt": "2025-08-04T06:53:00.000Z",
        "creator": {
          "code": "user2",
          "name": "使用者2"
        }
      }
    },
    {
      "type": "PEOPLE_COMMENT",
      "url": "https://sample.cybozu.com/k/#/people/user/user3/347030/182425",
      "snippets": [
        "為提升客戶應對品質,正在重新檢視業務支援體制。"
      ],
      "peopleComment": {
        "commentId": "347030",
        "owner": {
          "code": "user3",
          "name": "使用者3"
        },
        "createdAt": "2015-12-04T06:31:28.000Z",
        "creator": {
          "code": "user4",
          "name": "使用者4"
        },
        "replyId": "182425"
      }
    }
  ],
  "nextPageToken": "e68cc35e9f574dbc9fb7642512a000fb"
}

有關kintone.api()的說明,請參閱以下頁面。 傳送kintone REST API請求

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const body = {
  query: [
    {
      operator: 'AND',
      keywords: ['abc', 'def']
    }
  ]
};

await kintone.api(kintone.api.url('/k/v1/search.json', true), 'POST', body);

根據您的環境,curl的格式可能會有所不同。 有關詳細資訊,請參閱以下頁面。 使用curl命令執行kintone REST API中的3.執行API (日語)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
curl -X POST 'https://sample.cybozu.com/k/v1/search.json' \
  -H 'X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": [
      {
        "operator": "AND",
        "keywords": ["abc", "def"]
      }
    ]
  }'

注意事項

  • 請求URL/k/v1/search.json時,搜尋範圍也包含該使用者已參加的訪客空間內的資訊。但訪客使用者無法請求此URL。
  • 請求URL/k/guest/v1/search.json時,僅搜尋該使用者已參加的訪客空間內的資訊。
  • 請求URL/k/guest/GUEST_SPACE_ID/v1/search.json時,僅搜尋指定訪客空間內的資訊。指定未參加的訪客空間或不存在的訪客空間時,搜尋結果將為空。
  • 由於搜尋處理的改善,搜尋結果中包含的資料、其排列順序及hits[].snippets的內容可能會有所變更。
  • 每個網域每分鐘最多可請求600次。超過上限時,將返回HTTP狀態碼429的錯誤回應。