Querying Assets (ArkTS)

Available APIs

You can use query(query: AssetMap) (asynchronous API) or querySync(query: AssetMap) (synchronous API) to query assets.

The following table describes the attributes of AssetMap for querying an asset.

NOTE

In the following table, the attributes ALIAS and those starting with DATA_LABEL are custom asset attributes reserved for services. These attributes are not encrypted. Therefore, do not put sensitive personal data in these attributes. It takes a long time to query the plaintext of the asset attribute SECRET due to the need of decryption. Therefore, RETURN_TYPE must be set to ALL. For other asset attributes, decryption is not required, so the query takes a short time. Therefore, RETURN_TYPE must be set to ATTRIBUTES.

Attribute Name (Tag)	Value	Mandatory	Description
ALIAS	Type: Uint8Array Length: 1-256 bytes	No	Asset alias, which uniquely identifies an asset.
ACCESSIBILITY	Type: number Value range: see Accessibility	No	Access control based on the lock screen status.
REQUIRE_PASSWORD_SET	Type: Boolean	No	Whether the asset is accessible only when a lock screen password is set. The value true means the asset is accessible only when a lock screen password is set. The value false means that the asset can be accessed regardless of whether a lock screen password is set.
AUTH_TYPE	Type: number Value range: see AuthType	No	Type of user authentication required for accessing the asset.
SYNC_TYPE	Type: number Value range: see SyncType	No	Type of sync supported by the asset.
IS_PERSISTENT	Type: Boolean	No	Whether to retain the asset when the application is uninstalled. The value true means to retain the asset even after the application is uninstalled. The value false means the opposite.
DATA_LABEL_CRITICAL_1	Type: Uint8Array Length: 1-2048 bytes	No	Asset attribute information customized by the service with integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
DATA_LABEL_CRITICAL_2	Type: Uint8Array Length: 1-2048 bytes	No	Asset attribute information customized by the service with integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
DATA_LABEL_CRITICAL_3	Type: Uint8Array Length: 1-2048 bytes	No	Asset attribute information customized by the service with integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
DATA_LABEL_CRITICAL_4	Type: Uint8Array Length: 1-2048 bytes	No	Asset attribute information customized by the service with integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
DATA_LABEL_NORMAL_1	Type: Uint8Array Length: 1-2048 bytes	No	Asset attribute information customized by the service without integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
DATA_LABEL_NORMAL_2	Type: Uint8Array Length: 1-2048 bytes	No	Asset attribute information customized by the service without integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
DATA_LABEL_NORMAL_3	Type: Uint8Array Length: 1-2048 bytes	No	Asset attribute information customized by the service without integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
DATA_LABEL_NORMAL_4	Type: Uint8Array Length: 1-2048 bytes	No	Asset attribute information customized by the service without integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
DATA_LABEL_NORMAL_LOCAL_1¹²⁺	Type: Uint8Array Length: 1-2048 bytes	No	Local attribute information about the asset. The value is assigned by the service without integrity protection and will not be synced.
DATA_LABEL_NORMAL_LOCAL_2¹²⁺	Type: Uint8Array Length: 1-2048 bytes	No	Local attribute information about the asset. The value is assigned by the service without integrity protection and will not be synced.
DATA_LABEL_NORMAL_LOCAL_3¹²⁺	Type: Uint8Array Length: 1-2048 bytes	No	Local attribute information about the asset. The value is assigned by the service without integrity protection and will not be synced.
DATA_LABEL_NORMAL_LOCAL_4¹²⁺	Type: Uint8Array Length: 1-2048 bytes	No	Local attribute information about the asset. The value is assigned by the service without integrity protection and will not be synced.
RETURN_TYPE	Type: number Value range: see ReturnType	No	Type of the asset query result to return.
RETURN_LIMIT	Type: number	No	Maximum number of asset records returned.
RETURN_OFFSET	Type: number Value range: 1-65536	No	Offset of the asset query result. Note: This parameter specifies the starting asset record to return in batch asset query.
RETURN_ORDERED_BY	Type: number Value: asset.Tag.DATA_LABEL_xxx.	No	How the query results are sorted. Currently, the results can be sorted only by DATA_LABEL. Note: By default, assets are returned in the order in which they are added.
REQUIRE_ATTR_ENCRYPTED¹⁴⁺	Type: Boolean	No	Whether to query the encrypted data of service customized supplementary information. The value true means to query the encrypted data of service customized supplementary information; the value false means to query the non-encrypted data of service customized supplementary information. The default value is false.
GROUP_ID¹⁸⁺	Type: Uint8Array Length: 7-127 bytes	No	Group to which the asset to be queried belongs. By default, this parameter is not specified.

Constraints

Assets queried in batches need to be transmitted to services through the IPC channel. Due to the limitation of the IPC buffer size, you are advised to query a maximum of 40 assets at a time.

Example

NOTE

This module provides asynchronous and synchronous APIs. The following uses the asynchronous APIs as an example. For more information about the APIs, see @ohos.security.asset (Asset Store Service).

For details about how to query the plaintext of an asset in a group, see Querying the Plaintext of an Asset in a Group. For details about how to query the attributes of an asset in a group, see Querying the Attributes of an Asset in a Group.

Before querying an asset, ensure that the asset exists. For details about how to add an asset, see Adding an Asset. Otherwise, the NOT_FOUND error (24000002) is reported.

Querying the Plaintext of an Asset

Query the plaintext of asset demo_alias.

Include the header file and define the tool function.

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

function arrayToString(arr: Uint8Array): string {
  let textDecoder = util.TextDecoder.create('utf-8', { ignoreBOM: true });
  let str = textDecoder.decodeToString(arr, { stream: false });
  return str;
}

query_plaintext.ets

Develop the desired feature.

let query: asset.AssetMap = new Map();
query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); // Specify the alias of the asset to query. At most one asset will meet the condition.
query.set(asset.Tag.RETURN_TYPE, asset.ReturnType.ALL); // Return all asset information, including the attributes and asset plaintext. The plaintext needs to be decrypted, so the query takes a long time.
try {
  asset.query(query).then((res: Array<asset.AssetMap>) => {
    for (let i = 0; i < res.length; i++) {
      // Parse the secret.
      let secret: Uint8Array = res[i].get(asset.Tag.SECRET) as Uint8Array;
      // Convert Uint8Array into the string type.
      let secretStr: string = arrayToString(secret);
    }
    // ...
  }).catch((err: BusinessError) => {
    console.error(`Failed to query Asset plaintext. Code is ${err.code}, message is ${err.message}`);
    // ...
  });
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to query Asset plaintext. Code is ${err.code}, message is ${err.message}`);
  // ...
}

query_plaintext.ets

Querying Attributes of an Asset

Query attributes of asset demo_alias.

Include the header file and define the tool function.

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

query_attr.ets

Develop the desired feature.

let query: asset.AssetMap = new Map();
query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); // Specify the alias of the asset to query. At most one asset will meet the condition.
query.set(asset.Tag.RETURN_TYPE, asset.ReturnType.ATTRIBUTES); // Return only the attributes of the asset, that is, the result does not include the asset plaintext.
try {
  asset.query(query).then((res: Array<asset.AssetMap>) => {
    for (let i = 0; i < res.length; i++) {
      // Parse the attributes.
      let accessibility: number = res[i].get(asset.Tag.ACCESSIBILITY) as number;
      console.info(`Succeeded in getting accessibility, which is: ${accessibility}.`);
    }
    // ...
  }).catch((err: BusinessError) => {
    console.error(`Failed to query Asset attribute. Code is ${err.code}, message is ${err.message}`);
    // ...
  });
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to query Asset attribute. Code is ${err.code}, message is ${err.message}`);
  // ...
}

query_attr.ets

Querying Attributes of Assets

Query attributes of assets whose label is demo_label in batches. A total of 10 records that meet the conditions are returned. The results are sorted by the content of the DATA_LABEL_NORMAL_1 attribute.

Include the header file and define the tool function.

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

function stringToArray(str: string): Uint8Array {
  let textEncoder = new util.TextEncoder();
  return textEncoder.encodeInto(str);
}

query_batch_attrs.ets

Develop the desired feature.

let query: asset.AssetMap = new Map();
query.set(asset.Tag.RETURN_TYPE, asset.ReturnType.ATTRIBUTES); // Return only the attributes of the asset, that is, the result does not include the asset plaintext.
query.set(asset.Tag.DATA_LABEL_NORMAL_1, stringToArray('demo_label'));
query.set(asset.Tag.RETURN_LIMIT, 10); // Return information about 10 assets that match the search criteria.
query.set(asset.Tag.RETURN_ORDERED_BY, asset.Tag.DATA_LABEL_NORMAL_1); // Sort the query results by DATA_LABEL_NORMAL_1.
try {
  asset.query(query).then((res: Array<asset.AssetMap>) => {
    for (let i = 0; i < res.length; i++) {
      // Parse the attributes.
      let accessibility: number = res[i].get(asset.Tag.ACCESSIBILITY) as number;
      console.info(`Succeeded in getting accessibility, which is: ${accessibility}.`);
    }
    // ...
  }).catch((err: BusinessError) => {
    console.error(`Failed to query batch Asset attributes. Code is ${err.code}, message is ${err.message}`);
    // ...
  });
} catch (error) {
  let err = error as BusinessError;
  console.error(`Failed to query batch Asset attributes. Code is ${err.code}, message is ${err.message}`);
  // ...
}

query_batch_attrs.ets