Help Center/ KooDrive/ API Reference/ API/ File Management/ Retrieving Files Using Search Engine Capabilities

Updated on 2025-08-28 GMT+08:00

View PDF

Retrieving Files Using Search Engine Capabilities

Function

Search for files in a space by conditions such as search scope, parent directory, file name, file size range, update time range, and owner. Common users and department administrators can search for their individual and team space. Tenant administrators can search for all team spaces of the tenant.

URI

POST /koodrive/ose/v1/files/search

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
X-Traceid	No	String	Message log trace ID. The value contains 58 bits.
Authorization	Yes	String	Access token. Token authentication is used to call KooDrive APIs. A token indicates the permission. When an API is called, the token is added to the request header to obtain the operation permission. For details about how to obtain an access token, see the corresponding developer guide. The format is Bearer+{access_token}.
X-User-Id	Yes	String	User ID, which is used for app authentication.
X-Date	Yes	String	Date, which is used for app authentication.
Host	Yes	String	Address, which is used for app authentication.
language	No	String	Language code, which complies with the internationalization specifications. For example, en-US indicates English (United States). English (United States) is used by default.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
searchType	Yes	String	Query type. personal: individual space team: team space
pageInfo	Yes	pageInfo object	Pagination information.
filter	No	filter object	Filter.
sortInfo	No	sortInfo object	Sorting information.
recycled	No	Boolean	Whether to query the recycle bin. The default value is false. The options are as follows: true: Queries files in the recycle bin. false: Queries other files in the space.
recursived	No	Boolean	Whether files in sub-directories are queried recursively. Default value: false.
imageProcess	No	String	Image operation, which can be used to specify the thumbnail size.

**Table 3** pageInfo
Parameter	Mandatory	Type	Description
pageSize	Yes	Integer	Size of each page. The value ranges from 1 to 100.
pageCursor	Yes	String	Start cursor. If this parameter is null, the query starts from the first page.

**Table 4** filter
Parameter	Mandatory	Type	Description
keyWord	No	String	File name. Fuzzy match is supported. The value contains up to 80 characters.
containerId	No	String	Space ID. This parameter is mandatory when the parent directory is specified.
parentFolder	No	String	Parent directory.
fileType	No	String	File type. Enumerated values: /** * Folder / FOLDER("10"), /* * Smart folder (available only to whitelisted users) / SMART_FOLDER("11"), /* * Image / PICTURE("15"), /* * Video / VIDEO("20"), /* * Word file / WORD("26"), /* * Excel file / EXCEL("27"), /* * PowerPoint file / PPT("28"), /* * Audio / AUDIO("30"), /* * Compressed file / ARCHIVE("35"), /* * Application / APPLICATION("40"), /* * Other */ OTHER("45");
updateTimeRange	No	String	Update time range.
ownerId	No	String	File owner.
updateStartTime	No	String	Last update start time, in the format of 2024-11-19T16:00:00.000Z.
updateEndTime	No	String	Last update end time, in the format of 2025-05-20T15:59:59.999Z.
fileSuffixList	No	Array of strings	List of file name extensions to be filtered. A maximum of 100 file name extensions are supported.

**Table 5** sortInfo
Parameter	Mandatory	Type	Description
sortType	No	String	Enumerated values: fileName: file name. size: file size. updateTime: update time. createTime: creation time. recycledTime: deletion time. fileSuffix: file sub-category. - type: file format.
sortDirection	No	String	Enumerated values: desc: descending order. asc: ascending order.

Response Parameters

Status code: 200

**Table 6** Response body parameters
Parameter	Type	Description
code	Integer	Response code. 0 indicates success. Other values indicate failure.
msg	String	Success and error information.
files	Array of files objects	Search results
total	Integer	Total number of records.
nextPageCursor	String	Start cursor of the next page. It is null for the last page.

**Table 7** files
Parameter	Type	Description
id	String	File ID.
fileSuffix	String	File suffix.
fileName	String	File name.
fileType	String	File type.
size	String	File size.
updateTime	String	Update time.
namePath	String	Full name path.
idPath	String	Full ID path.
downloadLinks	Array of downLoadLinks objects	Thumbnail link, which is returned for an image.
teamName	String	Department name or group space name returned for the team space.
teamId	String	Group ID, that is, department ID or group ID.
containerId	String	Space ID.
containerType	String	0: department space; 1: individual space; 2: group space.
favorite	Boolean	Whether the file returned by the individual space or team space is added to favorites by the current user.
owner	String	Owner name returned for the team space.
attachments	Attachment object	Attachment.
createTime	String	Creation time.
editeTime	String	Editing time.
lastEditor	User object	Last editor.
mimeType	String	Content type.
ownerId	String	Owner ID.
owners	Array of User objects	Owner.
parentFolder	Array of strings	List of the parent directory IDs. Currently, only the first ID is used.
properties	Map<String,String>	Common user-defined attributes of the file. The number of key-value pairs cannot exceed 30. A single key-value pair can contain up to 124 characters.
recycled	Boolean	Whether the file is moved to the recycle bin.
sha256	String	sha256
userCapabilities	userCapabilities object	User permissions.
userProperties	Array of FileListPrivateProperties objects	Extended user attributes.

**Table 8** downLoadLinks
Parameter	Type	Description
usage	String	Usage. The value can be thumbnail or content.
downloadLink	String	Image address.

**Table 9** Attachment
Parameter	Type	Description
usage	String	Default usage: content or thumbnail. This parameter is customizable.
assetId	String	Asset ID
length	Long	File size.
versionId	String	Asset version ID.
mimeType	String	MIME type.
hash	String	Hash of the resource associated with the asset.
sha256	String	SHA256 of the resource associated with the asset.
createdTime	String	Time when the data is created.
modifiedTime	String	Time when the data is last modified.
attributes	Map<String,Object>	Type attributes.
asset	Asset object	Asset.

**Table 10** Asset
Parameter	Type	Description
id	String	Asset ID
versionId	String	Asset version ID.
version	Long	Version number.
mimeType	String	MIME type
keepPolicy	Integer	Storage policy of historical versions. 0: automatic clearance. Two versions are retained. The earliest version is deleted when the third version is added. (This prevents obtaining failures in concurrent scenarios.) 1: permanent storage.
state	Integer	Data status. 0: available. 1: unavailable. 2: temporary. 3: retained (flash upload unsupported). 4: to be cut over.
createdTime	String	Time when the data is created.
modifiedTime	String	Time when the data is last modified.
lastModifyingUser	String	UPID of the user that last modifies the data.
resource	Resource object	Resource.
cipher	Cipher object	Cipher.
attributes	Map<String,Object>	Type attributes. A key consists of letters and digits and starts with a letter. A value cannot contain emojis. The size of an attribute is not limited, but the total size cannot exceed 16 KB. Attribute options: pictureMetadata: image attribute data. For details, see the definition of PictureMetadata. videoMetadata: video attribute data. For details, see the definition of VideoMetadata. audioMetadata: audio attribute data. For details, see the definition of AudioMetadata. contentDisposition: used when response-content-disposition is not specified for the downloaded attachment (valid when resource.type is set to 12).
properties	Map<String,String>	Extended attributes.

**Table 11** Resource
Parameter	Type	Description
id	String	ID of the file resource.
hash	String	Hash of the file resource.
length	Long	Size of the file resource.
sha256	String	SHA256 of the file (used for integrity check).
type	Integer	Resource type. 0: ciphertext multipart file. 3: plaintext multipart file. 12: plaintext single-part file.
state	Integer	Data status. 0: available. 1: unavailable. 2: temporary. 3: retained (flash upload unsupported). 4: to be cut over.
sliceSize	Long	Part size.
hfek	String	Hash of the FEK of the encrypted file. This parameter is applicable when type is set to 0.
iv	String	IV of the encrypted file. This parameter is applicable when type is set to 0.
createdTime	String	Time when the data is created.
modifiedTime	String	Time when the data is last modified.
objects	Array of SliceObject objects	Part object, which is applicable when type is set to 0 or 3.
attributes	Map<String,Object>	Type attributes.
properties	Map<String,String>	Extended attributes.

**Table 12** SliceObject
Parameter	Type	Description
id	String	Part ID.
number	Integer	Part No., starting from 0. This parameter is not applicable when type is set to 12.
start	Long	Start position of a part, which is not applicable when type is set to 12.
sha256	String	SHA256 of the part (or SHA256 of the ciphertext if the part is encrypted.)
length	Long	Part length (or ciphertext length if the part is encrypted).
bucket	String	OBS bucket information.
createdTime	String	Time when the data is created.
modifiedTime	String	Time when the data is last modified.
uploadUrl	EndpointURL object	Upload URL.
downloadUrl	EndpointURL object	Download URL.
uploadId	String	Multipart upload ID. This parameter is applicable when type is set to 12 and uploadMode is set to multipart.
attributes	Map<String,Object>	Type attributes.
properties	Map<String,String>	Extended attributes.
images	Array of Images objects	Thumbnail.

**Table 13** EndpointURL
Parameter	Type	Description
url	String	URL
method	String	http method
headers	Map<String,String>	http headers
forms	Map<String,String>	Form parameter, which is applicable when type is set to 12 and uploadMode is set to post.
partId	String	Multipart parameter, which is applicable when type is set to 12 and uploadMode is set to multipart.

**Table 14** Images
Parameter	Type	Description
process	String	File resource name.
downloadUrl	EndpointURLMetadata object	URL structure for file upload or download.

**Table 15** EndpointURLMetadata
Parameter	Type	Description
url	String	URL
method	String	http method

**Table 16** Cipher
Parameter	Type	Description
algorithm	String	Encryption algorithm.
hfek	String	Hash of the FEK of the encrypted file. This parameter is applicable when type is set to 0 or 4.
iv	String	IV of the encrypted file. This parameter is applicable when type is set to 0 or 4.
dataType	Integer	Data type. 11: sync drive.
keychains	Array of Keychain objects	Keychain.

**Table 17** Keychain
Parameter	Type	Description
id	String	Key UUID.
type	Integer	Key type. 1: efek. 2: zfek. 3: sfek.
algorithm	String	Encryption algorithm.
ekey	String	Encrypted key.

**Table 18** User
Parameter	Type	Description
category	String	Type. The value is drive#user.
userId	String	Huawei user ID.
displayName	String	Display name of the user.
me	Boolean	Whether you are the user.
permissionId	String	Permission ID.

**Table 19** userCapabilities
Parameter	Type	Description
addChildNodePermission	Boolean	Whether the user can add sub-directories or sub-files.
copyPermission	Boolean	Whether the user can copy files.
deletePermission	Boolean	Whether the user can delete files.
downloadPermission	Boolean	Whether the use can download content.
editPermission	Boolean	Whether the user can edit files.
listChildNodePermission	Boolean	Whether the user can list sub-directories or sub-files.
removeChildNodePermission	Boolean	Whether the user can move sub-directories.
renameFilePermission	Boolean	Whether the user can rename files.
shareFilePermission	Boolean	Whether the user can share files.
uploadPermission	Boolean	Whether the user can upload files.
viewPermission	Boolean	Whether the user can preview files.

**Table 20** FileListPrivateProperties
Parameter	Type	Description
properties	Map<String,String>	Extended attributes (The size of a single attribute is not limited, but the total size cannot exceed 16 KB.)

Example Requests

Example request for searching for a file.

POST /koodrive/ose/v1/files/search

Authorization:Bearer+10f88*********4791e9ff
{
  "searchType" : " personal/team",
  "pageInfo" : {
    "pageSize" : 100,
    "pageCursor" : 1
  },
  "filter" : {
    "keyWord" : "Material",
    "containerId" : "123456",
    "parentFolder" : "1",
    "fileType" : "1",
    "sizeRang" : "1024,2048",
    "updateTimeRange" : "2023-11-02,2023-11-21",
    "ownerId" : "Owner ID"
  }
}

Example Responses

Status code: 200

Search results

{
  "files" : [ {
    "id" : "Fu2A5BQZ1qUk3h1tU6ZlAS66swzlN9mnJ",
    "sha256" : "57eafb818ad716aa11b443fb9fc2c1f23875f0c8da49035a8ca98136e4525632",
    "fileName" : "KooDrive Service Overview.docx",
    "fileSuffix" : "docx",
    "fileType" : "26",
    "size" : "705395",
    "updateTime" : "2024-12-25T06:41:22.873Z",
    "idPath" : "DFcz6PEuDwIArootIAAFWbRXM-jxLg8CA1578177668157825025",
    "downloadLinks" : [ {
      "usage" : "content",
      "downloadLink" : "https://b10-obs-ykj-uat-01.obs.cidc-rp-2006.joint.cmecloud.cn/18ad967c9af047fd8b909ed163c0fdb6086?response-content-disposition=attachment%3B%20filename%2A%3DUTF-8%27%27KooDrive%25E6%259C%258D%25E5%258A%25A1%25E4%25BB%258B%25E7%25BB%258D.docx&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250103T023324Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=MKRISPBZAJWFHNBJ5WLB%2F20250103%2Fcidc-rp-2006%2Fs3%2Faws4_request&X-Amz-Signature=e518a982307ef9b6d6e4bd8788e421d3488f58f3ed79eb3ab42702ac5c3d7513"
    }, {
      "usage" : "thumbnail",
      "downloadLink" : "https://b10-obs-ykj-uat-01.obs.cidc-rp-2006.joint.cmecloud.cn/18ad967c9af047fd8b909ed163c0fdb6086?x-image-process=image%2Fresize%2Cm_lfit%2Ch_128%2Cw_128&response-content-disposition=attachment%3B%20filename%2A%3DUTF-8%27%27KooDrive%25E6%259C%258D%25E5%258A%25A1%25E4%25BB%258B%25E7%25BB%258D.docx&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250103T023324Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=MKRISPBZAJWFHNBJ5WLB%2F20250103%2Fcidc-rp-2006%2Fs3%2Faws4_request&X-Amz-Signature=ad55a09e66ddd32c6f9b3cce08c7c9a867c7a579a41200f415fb2918de1ab473"
    } ],
    "teamName" : "fdsgdsf",
    "teamId" : "1578175198769733633",
    "containerId" : "IAAFWbRXM-jxLg8CA1578177668157825025",
    "containerType" : "0",
    "favorite" : false,
    "owner" : "hid42638091",
    "ownerId" : "1568722386902108288",
    "properties" : {
      "localCreatedAt" : "",
      "localUpdatedAt" : "",
      "createUser" : "1568722386902108288",
      "lastEditUser" : "1568722386902108288",
      "auditResult" : "{\"auditDetail\":\"{}\",\"auditLevel\":10,\"auditResult\":1}"
    },
    "attachments" : [ {
      "assetId" : "1584078561541652992",
      "asset" : {
        "id" : "1584078561541652992",
        "versionId" : "1584078561541652993",
        "version" : 49923,
        "mimeType" : "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "state" : 0,
        "createdTime" : "2024-12-25T06:41:20.050Z",
        "modifiedTime" : "2024-12-25T06:41:20.050Z",
        "resource" : {
          "id" : "1584078561810055808",
          "length" : 705395,
          "sha256" : "57eafb818ad716aa11b443fb9fc2c1f23875f0c8da49035a8ca98136e4525632",
          "object" : {
            "id" : "18ad967c9af047fd8b909ed163c0fdb6086",
            "start" : 0,
            "downloadUrl" : {
              "url" : "https://b10-obs-ykj-uat-01.obs.cidc-rp-2006.joint.cmecloud.cn/18ad967c9af047fd8b909ed163c0fdb6086?response-content-disposition=attachment%3B%20filename%2A%3DUTF-8%27%27KooDrive%25E6%259C%258D%25E5%258A%25A1%25E4%25BB%258B%25E7%25BB%258D.docx&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250103T023324Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=MKRISPBZAJWFHNBJ5WLB%2F20250103%2Fcidc-rp-2006%2Fs3%2Faws4_request&X-Amz-Signature=e518a982307ef9b6d6e4bd8788e421d3488f58f3ed79eb3ab42702ac5c3d7513",
              "method" : "GET"
            },
            "images" : [ {
              "process" : "image/resize,m_lfit,h_128,w_128",
              "downloadUrl" : {
                "url" : "https://b10-obs-ykj-uat-01.obs.cidc-rp-2006.joint.cmecloud.cn/18ad967c9af047fd8b909ed163c0fdb6086?x-image-process=image%2Fresize%2Cm_lfit%2Ch_128%2Cw_128&response-content-disposition=attachment%3B%20filename%2A%3DUTF-8%27%27KooDrive%25E6%259C%258D%25E5%258A%25A1%25E4%25BB%258B%25E7%25BB%258D.docx&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250103T023324Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=MKRISPBZAJWFHNBJ5WLB%2F20250103%2Fcidc-rp-2006%2Fs3%2Faws4_request&X-Amz-Signature=ad55a09e66ddd32c6f9b3cce08c7c9a867c7a579a41200f415fb2918de1ab473",
                "method" : "GET"
              }
            } ]
          }
        },
        "attributes" : {
          "fileName" : "KooDrive Service Overview.docx",
          "localCreatedAt" : "",
          "createdBy" : "667706171d1c4ef2a4d7464f3656066c",
          "resource" : {
            "id" : "1584078561810055808",
            "object" : {
              "bucket" : "b10-obs-ykj-uat-01",
              "objectId" : "18ad967c9af047fd8b909ed163c0fdb6086"
            }
          },
          "localUpdatedAt" : ""
        }
      },
      "versionId" : "1584078561541652993",
      "attributes" : {
        "fileName" : "KooDrive Service Overview.docx",
        "localCreatedAt" : "",
        "createdBy" : "667706171d1c4ef2a4d7464f3656066c",
        "resource" : {
          "id" : "1584078561810055808",
          "object" : {
            "bucket" : "b10-obs-ykj-uat-01",
            "objectId" : "18ad967c9af047fd8b909ed163c0fdb6086"
          }
        },
        "localUpdatedAt" : ""
      },
      "hash" : "57eafb818ad716aa11b443fb9fc2c1f23875f0c8da49035a8ca98136e4525632",
      "length" : 705395,
      "mimeType" : "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "usage" : "content",
      "sha256" : "57eafb818ad716aa11b443fb9fc2c1f23875f0c8da49035a8ca98136e4525632",
      "createdTime" : "2024-12-25T06:41:20.050Z",
      "modifiedTime" : "2024-12-25T06:41:20.050Z"
    } ],
    "createdTime" : "2024-12-25T06:41:19.794Z",
    "editedTime" : "2024-12-25T06:41:22.873Z",
    "lastEditor" : {
      "category" : "drive#user",
      "me" : true,
      "permissionId" : "1570905506917367936",
      "userId" : "NDEzMDA4NjAwMDAwMjc0MTY2NS02Njc3MDYxNzFkMWM0ZWYyYTRkNzQ2NGYzNjU2MDY2Yw",
      "displayName" : "hid42638091"
    },
    "mimeType" : "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "owners" : [ {
      "category" : "drive#user",
      "me" : true,
      "permissionId" : "1570905506917367936",
      "userId" : "NDEzMDA4NjAwMDAwMjc0MTY2NS02Njc3MDYxNzFkMWM0ZWYyYTRkNzQ2NGYzNjU2MDY2Yw"
    } ],
    "parentFolder" : [ "DFcz6PEuDwIArootIAAFWbRXM-jxLg8CA1578177668157825025" ],
    "recycled" : false,
    "userProperties" : {
      "properties" : {
        "hidden" : "false"
      }
    },
    "userCapabilities" : {
      "addChildNodePermission" : true,
      "copyPermission" : true,
      "deletePermission" : true,
      "downloadPermission" : true,
      "editPermission" : true,
      "listChildNodePermission" : true,
      "removeChildNodePermission" : true,
      "renameFilePermission" : true,
      "shareFilePermission" : true,
      "uploadPermission" : true,
      "viewPermission" : true
    }
  } ],
  "total" : 1,
  "code" : 0,
  "msg" : "Successful."
}