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. | 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. | 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 to return. | 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 customized asset attribute information that is encrypted. By default, the unencrypted, customized asset attribute information is queried.| 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 41The assets queried are transmitted to the service through an IPC channel. Due to the limitation of the IPC buffer size, the maximum number of assets to be queried at a time cannot exceed 40. 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