All Products
Search

This Product

    Drive and Photo Service:Query files

    Document Center

    Drive and Photo Service:Query files

    Last Updated:Jan 22, 2025

    Note

    Photo and Drive Service (PDS) provides two data storage modes for a domain: standard mode and hosting mode. File querying is supported only for the standard mode. You can call the /file/search operation to query files in a drive on which you have the file query permissions. You cannot call the /file/search operation to query files in the recycle bin.

    Request syntax

    POST /v2/file/search

    Request parameters

    Parameter

    Position

    Type

    Required

    Description

    Authorization

    Header

    STRING

    Yes

    The access token.

    drive_id

    Body

    STRING

    No

    The ID of the drive in which files are to be queried.

    drive_id_list

    Body

    STRING ARRAY

    No

    The IDs of the drives in which files are to be queried. Example: ["1","2"].

    query

    Body

    STRING

    Yes

    The query string. For more information, see the following content of this topic. The value of this parameter can be up to 4,096 characters in length.

    order_by

    Body

    STRING

    Yes

    The rules for sorting the query results. For more information, see the following content of this topic. The value of this parameter can be up to 128 characters in length.

    limit

    Body

    INTEGER (INT32)

    No

    The maximum number of entries to be returned. Valid values: 1 to 100. Default value: 50.

    marker

    Body

    STRING

    No

    The start identifier of the query. If you specify the marker parameter, the value of the query parameter is ignored.

    url_expire_sec

    Body

    INTEGER (INT64)

    No

    The validity period of the URL to be returned. Unit: seconds. Valid values: 10 to 14400.

    Note

    You must specify one of the drive_id and drive_id_list parameters. If the drive_id parameter is specified, the value of the drive_id_list parameter is ignored.  

    Rules for specifying the query parameter:

    1. Supported data types:

      a. Basic data types: LONG, STRING, BOOLEAN, and DOUBLE.

      b. Composite data types: ARRAY and DATE. Values of the DATE type must be in the yyyy-MM-ddTHH:mm:ss format in the UTC+0 time zone and must be enclosed in double quotation marks (") or single quotation marks ('). Example: "2006-01-02T00:00:00".

    2. Operators for querying data of the basic data types:

      a. LONG: =, <, >, <=, and >=.

      b. STRING: =, prefix, and match. The = operator is used for exact match. prefix is used for prefix-based match and cannot be used to query files based on the name parameter. match is used for fuzzy match and can be used to query files only based on the name parameter.

      c. BOOLEAN: =.

      d. DOUBLE: =, <, >, <=, and >=.

    3. Operators for querying data of the composite data types:

      a. ARRAY: IN for queries based on multiple conditions.

      b. DATE: =, <, >, <=, and >=.

    4. Supported logical operators: NOT, AND, and OR.

    5. Brackets are supported. The query priority is Brackets > NOT > AND > OR.

    Examples:

    1. Query a file based on exact match

      // Query a file named Report.ppt.
name = "Report.ppt"

    2. Query files by specifying a range

      // Query files created before January 14, 2019. The time must be in UTC+0.
created_at < "2019-01-14T00:00:00"

    3. Query files based on fuzzy match

      // Query files whose name contains Report.
name match "Report"

    4. Query files by using a logical operator

      // Query files created on January 14, 2019. The time must be in UTC+0.
created_at > "2019-01-14T00:00:00" and created_at < "2019-01-15T00:00:00"

    5. Query files based on multiple conditions

      // Query files whose size is greater than 1,024 bytes, value of the hidden parameter is false, and value of the file_extension parameter is not mp4.
size > 1024 and hidden = false and not file_extension = 'mp4'

    6. Query an array

      // Query files whose name is suffixed with .jpg, .png, or .gif.
file_extension in ["jpg", "png", "gif"]

    Rules for specifying the order_by parameter:

    • Valid values: ASC and DESC. ASC indicates ascending order, and DESC indicates descending order.

    • Syntax: Parameter ASC or Parameter DESC.

    • Separate multiple sorting rules with commas (,).

    • Multiple sorting rules are applied based on the sequence in which they are specified.

    Examples:

    1. Sort results based on a single rule in ascending order

      // Sort results based on the name parameter in ascending order.
name ASC

    2. Sort results based on a single rule in descending order

      // Sort results based on the created_at parameter in descending order.
created_at DESC

    3. Sort results based on multiple rules

      // Sort results based on the created_at parameter in descending order. If the value of the created_at parameter is the same among results, sort the results based on the name parameter in ascending order.
created_at DESC,name ASC

    Parameters based on which files can be queried or the query results can be sorted

    Parameter

    Type

    Query

    Sort

    Description

    parent_file_id

    STRING

    ✔️

    N/A

    The ID of the parent folder. Subfolders are not searched when you use this parameter to query files.

    name

    STRING

    ✔️

    ✔️

    The name of the file, which can be used for fuzzy match.

    type

    STRING

    ✔️

    ✔️

    The type of the file. Valid values: file and folder.

    file_extension

    STRING

    ✔️

    N/A

    The file name extension.

    description

    STRING

    ✔️

    N/A

    The description of the file. The value of this parameter can be split into terms for term match.

    mime_type

    STRING

    ✔️

    N/A

    The Multipurpose Internet Mail Extensions (MIME) type of the file.

    starred

    BOOLEAN

    ✔️

    N/A

    Indicates whether the file is added to favorites.

    created_at

    DATE

    ✔️

    ✔️

    The time when the file was created.

    updated_at

    DATE

    ✔️

    ✔️

    The time when the file was last modified.

    status

    STRING

    ✔️

    N/A

    The state of the file.

    hidden

    BOOLEAN

    ✔️

    N/A

    Indicates whether the file is hidden.

    size

    LONG

    ✔️

    ✔️

    The size of the file.

    image_time

    DATE

    ✔️

    ✔️

    The time when the photo was taken.

    last_access_at

    DATE

    ✔️

    ✔️

    The time when the file was last accessed.

    category

    STRING

    ✔️

    N/A

    The category of the file. Valid values: image, video, doc, audio, app, and others.

    label

    STRING

    ✔️

    N/A

    The name of the system tag.

    face_group_id

    STRING

    ✔️

    N/A

    The ID of the face group, which can be used to query images in the face group. You can obtain the ID by calling the ListFacegroups operation.

    address

    STRING

    ✔️

    N/A

    The address information of the file, including country, province, city, district, and sub-district.

    • LONG: stores signed 64-bit integers.

    • BOOLEAN: stores true or false values.

    • DATE: stores date and time combinations. Values of the DATE type must be in the yyyy-MM-ddTHH:mm:ss format in the UTC+0 time zone and must be enclosed in double quotation marks (") or single quotation marks ('). Example: "2006-01-02T00:00:00".

    • STRING: stores strings.

    Response parameters

    • The response parameters are the same as those of the ListFile operation.