1# Querying Assets (ArkTS) 2 3## Available APIs 4 5You can use [query(query: AssetMap)](../../reference/apis-asset-store-kit/js-apis-asset.md#assetquery), an asynchronous API, and [querySync(query: AssetMap)](../../reference/apis-asset-store-kit/js-apis-asset.md#assetquerysync12), a synchronous API, to query assets. 6 7The following table describes the attributes of **AssetMap** for querying an asset. 8>**NOTE** 9> 10>In the following table, the attributes starting with **DATA_LABEL** are custom asset attributes reserved for services. These attributes are not encrypted. Therefore, do not put personal data in these attributes. 11 12| Attribute Name (Tag) | Value | Mandatory | Description | 13| --------------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 14| ALIAS | Type: Uint8Array<br>Length: 1-256 bytes | No | Asset alias, which uniquely identifies an asset. | 15| ACCESSIBILITY | Type: number<br>Value range: see [Accessibility](../../reference/apis-asset-store-kit/js-apis-asset.md#accessibility)| No | Access control based on the lock screen status. | 16| 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. | 17| AUTH_TYPE | Type: number<br>Value range: see [AuthType](../../reference/apis-asset-store-kit/js-apis-asset.md#authtype)| No | Type of user authentication required for accessing the asset. | 18| SYNC_TYPE | Type: number<br>Value range: see [SyncType](../../reference/apis-asset-store-kit/js-apis-asset.md#synctype)| No | Type of sync supported by the asset. | 19| 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. | 20| DATA_LABEL_CRITICAL_1 | Type: Uint8Array<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service with integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 21| DATA_LABEL_CRITICAL_2 | Type: Uint8Array<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service with integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 22| DATA_LABEL_CRITICAL_3 | Type: Uint8Array<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service with integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 23| DATA_LABEL_CRITICAL_4 | Type: Uint8Array<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service with integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 24| DATA_LABEL_NORMAL_1 | Type: Uint8Array<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service without integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 25| DATA_LABEL_NORMAL_2 | Type: Uint8Array<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service without integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 26| DATA_LABEL_NORMAL_3 | Type: Uint8Array<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service without integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 27| DATA_LABEL_NORMAL_4 | Type: Uint8Array<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service without integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 28| DATA_LABEL_NORMAL_LOCAL_1<sup>12+</sup> | Type: Uint8Array<br>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.| 29| DATA_LABEL_NORMAL_LOCAL_2<sup>12+</sup> | Type: Uint8Array<br>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.| 30| DATA_LABEL_NORMAL_LOCAL_3<sup>12+</sup> | Type: Uint8Array<br>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.| 31| DATA_LABEL_NORMAL_LOCAL_4<sup>12+</sup> | Type: Uint8Array<br>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.| 32| RETURN_TYPE | Type: number<br>Value range: see [ReturnType](../../reference/apis-asset-store-kit/js-apis-asset.md#returntype)| No | Type of the asset query result to return. | 33| RETURN_LIMIT | Type: number | No | Maximum number of asset records returned. | 34| RETURN_OFFSET | Type: number<br>Value range: 1-65536 | No | Offset of the asset query result.<br>**NOTE**: This parameter specifies the starting asset record to return in batch asset query. | 35| RETURN_ORDERED_BY | Type: number<br>Value: asset.Tag.DATA_LABEL_xxx. | No | How the query results are sorted. Currently, the results can be sorted only by **DATA_LABEL**.<br>**NOTE**: By default, assets are returned in the order in which they are added.| 36| REQUIRE_ATTR_ENCRYPTED<sup>14+</sup> | 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**.| 37| GROUP_ID<sup>18+</sup> | Type: Uint8Array<br>Length: 7-127 bytes| No| Group to which the asset to be queried belongs. By default, this parameter is not specified.| 38 39## Constraints 40 41Assets 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. 42 43## Example 44 45> **NOTE** 46> 47> The **asset** module provides an asynchronous API and a synchronous API for querying assets. The following uses the asynchronous API as an example. For more information about the APIs, see [Asset Store Service](../../reference/apis-asset-store-kit/js-apis-asset.md). 48> 49> For details about how to query the plaintext of an asset in a group, see [Querying the Plaintext of an Asset in a Group](asset-js-group-access-control.md#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](asset-js-group-access-control.md#querying-the-attributes-of-an-asset-in-a-group). 50 51### Querying the Plaintext of an Asset 52 53Query the plaintext of asset **demo_alias**. 54 55```typescript 56import { asset } from '@kit.AssetStoreKit'; 57import { util } from '@kit.ArkTS'; 58import { BusinessError } from '@kit.BasicServicesKit'; 59 60function stringToArray(str: string): Uint8Array { 61 let textEncoder = new util.TextEncoder(); 62 return textEncoder.encodeInto(str); 63} 64 65function arrayToString(arr: Uint8Array): string { 66 let textDecoder = util.TextDecoder.create("utf-8", { ignoreBOM: true }); 67 let str = textDecoder.decodeToString(arr, { stream: false }) 68 return str; 69} 70 71let query: asset.AssetMap = new Map(); 72query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); // Specify the alias of the asset to query. 73query.set(asset.Tag.RETURN_TYPE, asset.ReturnType.ALL); // Return all asset information, including attributes and asset plaintext. 74try { 75 asset.query(query).then((res: Array<asset.AssetMap>) => { 76 for (let i = 0; i < res.length; i++) { 77 // Parse the secret. 78 let secret: Uint8Array = res[i].get(asset.Tag.SECRET) as Uint8Array; 79 // Convert uint8array to string 80 let secretStr: string = arrayToString(secret); 81 } 82 }).catch ((err: BusinessError) => { 83 console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`); 84 }); 85} catch (error) { 86 let err = error as BusinessError; 87 console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`); 88} 89``` 90 91### Querying Attributes of an Asset 92 93Query attributes of asset **demo_alias**. 94 95```typescript 96import { asset } from '@kit.AssetStoreKit'; 97import { util } from '@kit.ArkTS'; 98import { BusinessError } from '@kit.BasicServicesKit'; 99 100function stringToArray(str: string): Uint8Array { 101 let textEncoder = new util.TextEncoder(); 102 return textEncoder.encodeInto(str); 103} 104 105let query: asset.AssetMap = new Map(); 106query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); // Specify the alias of the asset to query. 107query.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. 108try { 109 asset.query(query).then((res: Array<asset.AssetMap>) => { 110 for (let i = 0; i < res.length; i++) { 111 // Parse the attributes. 112 let accessibility: number = res[i].get(asset.Tag.ACCESSIBILITY) as number; 113 } 114 }).catch ((err: BusinessError) => { 115 console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`); 116 }); 117} catch (error) { 118 let err = error as BusinessError; 119 console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`); 120} 121``` 122 123### Querying Attributes of Assets 124 125Query attributes of assets with tag 1 of **demo_label** and return a total of 10 records sorted by **DATA_LABEL_NORMAL_1** starting from the fifth record that matches the search criteria. 126 127```typescript 128import { asset } from '@kit.AssetStoreKit'; 129import { util } from '@kit.ArkTS'; 130import { BusinessError } from '@kit.BasicServicesKit'; 131 132function stringToArray(str: string): Uint8Array { 133 let textEncoder = new util.TextEncoder(); 134 return textEncoder.encodeInto(str); 135} 136 137let query: asset.AssetMap = new Map(); 138query.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. 139query.set(asset.Tag.DATA_LABEL_NORMAL_1, stringToArray('demo_label')); 140query.set(asset.Tag.RETURN_OFFSET, 5); // Return results from the fifth asset that matches the search criteria. 141query.set(asset.Tag.RETURN_LIMIT, 10); // Return information about 10 assets that match the search criteria. 142query.set(asset.Tag.RETURN_ORDERED_BY, asset.Tag.DATA_LABEL_NORMAL_1); // Sort the query results by DATA_LABEL_NORMAL_1. 143try { 144 asset.query(query).then((res: Array<asset.AssetMap>) => { 145 for (let i = 0; i < res.length; i++) { 146 // Parse the attributes. 147 let accessibility: number = res[i].get(asset.Tag.ACCESSIBILITY) as number; 148 } 149 }).catch ((err: BusinessError) => { 150 console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`); 151 }); 152} catch (error) { 153 let err = error as BusinessError; 154 console.error(`Failed to query Asset. Code is ${err.code}, message is ${err.message}`); 155} 156``` 157