1# 查询需要用户认证的关键资产(ArkTS) 2 3## 接口介绍 4 5可通过API文档查看此功能的相关接口： 6 7| 异步接口 | 同步接口 | 说明 | 8| ----- | ------ | ------- | 9| [preQuery(query: AssetMap)](../../reference/apis-asset-store-kit/js-apis-asset.md#assetprequery) | [preQuerySync(query: AssetMap)](../../reference/apis-asset-store-kit/js-apis-asset.md#assetprequerysync12) | 查询预处理。| 10| [query(query: AssetMap)](../../reference/apis-asset-store-kit/js-apis-asset.md#assetquery) | [querySync(query: AssetMap)](../../reference/apis-asset-store-kit/js-apis-asset.md#assetquerysync12) | 查询关键资产。| 11| [postQuery(handle: AssetMap)](../../reference/apis-asset-store-kit/js-apis-asset.md#assetpostquery) | [postQuerySync(handle: AssetMap)](../../reference/apis-asset-store-kit/js-apis-asset.md#assetpostquerysync12) | 查询后置处理。 | 12 13在查询需要用户认证的关键资产时，关键资产属性的内容（AssetMap）参数如下表所示： 14 15>**注意：** 16> 17>下表中名称包含“DATA_LABEL”的关键资产属性，用于存储业务自定义信息，其内容不会被加密，请勿存放个人数据。 18 19- **preQuery参数列表** 20 21 | 属性名称（Tag） | 属性内容（Value） | 是否必选 | 说明 | 22 | --------------------- | ---------------------------| -------- | -------------------------- | 23 | ALIAS | 类型为Uint8Array，长度为1-256字节。 | 可选 | 关键资产别名，每条关键资产的唯一索引。 | 24 | ACCESSIBILITY | 类型为number，取值范围详见[Accessibility](../../reference/apis-asset-store-kit/js-apis-asset.md#accessibility)。 | 可选 | 基于锁屏状态的访问控制。 | 25 | REQUIRE_PASSWORD_SET | 类型为boolean。 | 可选 | 是否仅在设置了锁屏密码的情况下，可访问关键资产。 | 26 | AUTH_TYPE | 类型为number，取值范围详见[AuthType](../../reference/apis-asset-store-kit/js-apis-asset.md#authtype)。 | 可选 | 访问关键资产所需的用户认证类型。 | 27 | AUTH_VALIDITY_PERIOD | 类型为number，取值范围：1-600，单位为秒。 | 可选 | 用户认证的有效期，默认值为60。 | 28 | SYNC_TYPE | 类型为number，取值范围详见[SyncType](../../reference/apis-asset-store-kit/js-apis-asset.md#synctype)。 | 可选 | 关键资产支持的同步类型。 | 29 | IS_PERSISTENT | 类型为boolean。 | 可选 | 在应用卸载时是否需要保留关键资产。 | 30 | DATA_LABEL_CRITICAL_1 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且有完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 31 | DATA_LABEL_CRITICAL_2 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且有完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 32 | DATA_LABEL_CRITICAL_3 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且有完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 33 | DATA_LABEL_CRITICAL_4 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且有完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 34 | DATA_LABEL_NORMAL_1 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且无完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 35 | DATA_LABEL_NORMAL_2 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且无完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 36 | DATA_LABEL_NORMAL_3 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且无完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 37 | DATA_LABEL_NORMAL_4 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且无完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 38 | DATA_LABEL_NORMAL_LOCAL_1<sup>12+</sup> | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属的本地信息，内容由业务自定义且无完整性保护，该项信息不会进行同步。 | 39 | DATA_LABEL_NORMAL_LOCAL_2<sup>12+</sup> | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属的本地信息，内容由业务自定义且无完整性保护，该项信息不会进行同步。 | 40 | DATA_LABEL_NORMAL_LOCAL_3<sup>12+</sup> | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属的本地信息，内容由业务自定义且无完整性保护，该项信息不会进行同步。 | 41 | DATA_LABEL_NORMAL_LOCAL_4<sup>12+</sup> | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属的本地信息，内容由业务自定义且无完整性保护，该项信息不会进行同步。 | 42 | REQUIRE_ATTR_ENCRYPTED<sup>14+</sup> | 类型为boolean。 | 可选 | 是否查询业务自定义附属信息被加密的数据，默认值为false，即查询业务附属信息不加密的数据。| 43 | GROUP_ID<sup>18+</sup> | 类型为Uint8Array，长度为7-127字节。 | 可选 | 待查询的关键资产所属群组，默认查询不属于任何群组的关键资产。| 44 45- **query参数列表** 46 47 | 属性名称（Tag） | 属性内容（Value） | 是否必选 | 说明 | 48 | --------------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------ | 49 | ALIAS | 类型为Uint8Array，长度为1-256字节。 | 必选 | 关键资产别名，每条关键资产的唯一索引。 | 50 | AUTH_CHALLENGE | 类型为Uint8Array，长度为32字节。 | 必选 | 用户认证的挑战值。 | 51 | AUTH_TOKEN | 类型为Uint8Array，长度为148字节。 | 必选 | 用户认证通过的授权令牌。 | 52 | RETURN_TYPE | 类型为number，asset.ReturnType.ALL。 | 必选 | 关键资产查询返回的结果类型。 | 53 | ACCESSIBILITY | 类型为number，取值范围详见[Accessibility](../../reference/apis-asset-store-kit/js-apis-asset.md#accessibility)。 | 可选 | 基于锁屏状态的访问控制。 | 54 | REQUIRE_PASSWORD_SET | 类型为boolean。 | 可选 | 是否仅在设置了锁屏密码的情况下，可访问关键资产。 | 55 | AUTH_TYPE | 类型为number，取值范围详见[AuthType](../../reference/apis-asset-store-kit/js-apis-asset.md#authtype)。 | 可选 | 访问关键资产所需的用户认证类型。 | 56 | SYNC_TYPE | 类型为number，取值范围详见[SyncType](../../reference/apis-asset-store-kit/js-apis-asset.md#synctype)。 | 可选 | 关键资产支持的同步类型。 | 57 | IS_PERSISTENT | 类型为boolean。 | 可选 | 在应用卸载时是否需要保留关键资产。 | 58 | DATA_LABEL_CRITICAL_1 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且有完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 59 | DATA_LABEL_CRITICAL_2 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且有完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 60 | DATA_LABEL_CRITICAL_3 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且有完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 61 | DATA_LABEL_CRITICAL_4 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且有完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 62 | DATA_LABEL_NORMAL_1 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且无完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 63 | DATA_LABEL_NORMAL_2 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且无完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 64 | DATA_LABEL_NORMAL_3 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且无完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 65 | DATA_LABEL_NORMAL_4 | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属信息，内容由业务自定义且无完整性保护。<br/>**说明：** API12前长度为1-512字节。 | 66 | DATA_LABEL_NORMAL_LOCAL_1<sup>12+</sup> | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属的本地信息，内容由业务自定义且无完整性保护，该项信息不会进行同步。 | 67 | DATA_LABEL_NORMAL_LOCAL_2<sup>12+</sup> | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属的本地信息，内容由业务自定义且无完整性保护，该项信息不会进行同步。 | 68 | DATA_LABEL_NORMAL_LOCAL_3<sup>12+</sup> | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属的本地信息，内容由业务自定义且无完整性保护，该项信息不会进行同步。 | 69 | DATA_LABEL_NORMAL_LOCAL_4<sup>12+</sup> | 类型为Uint8Array，长度为1-2048字节。 | 可选 | 关键资产附属的本地信息，内容由业务自定义且无完整性保护，该项信息不会进行同步。 | 70 | REQUIRE_ATTR_ENCRYPTED<sup>14+</sup> | 类型为boolean。 | 可选 | 是否查询业务自定义附属信息被加密的数据，默认值为false，即查询业务附属信息不加密的数据。| 71 | GROUP_ID<sup>18+</sup> | 类型为Uint8Array，长度为7-127字节。 | 可选 | 待查询的关键资产所属群组，默认查询不属于任何群组的关键资产。| 72 73- **postQuery参数列表** 74 75 | 属性名称（Tag） | 属性内容（Value） | 是否必选 | 说明 | 76 | ------------------- | ------------------------------ | -------- | -------------------- | 77 | AUTH_CHALLENGE | 类型为Uint8Array，长度为32字节。 | 必选 | 用户认证的挑战值。 | 78 | GROUP_ID<sup>18+</sup> | 类型为Uint8Array，长度为7-127字节。 | 可选 | 待清理关键资产所属群组，默认清理内存中不属于任何群组的关键资产。| 79 80## 代码示例 81 82> **说明：** 83> 84> 本模块提供了异步和同步两套接口，以下为异步接口的使用示例，同步接口详见[API文档](../../reference/apis-asset-store-kit/js-apis-asset.md)。 85 86查询别名是demo_alias且需要用户认证的关键资产。示例中引入的@ohos.userIAM.userAuth用法详见[userAuth文档](../../reference/apis-user-authentication-kit/js-apis-useriam-userauth.md#start10)。 87 88```typescript 89import { asset } from '@kit.AssetStoreKit'; 90import { util } from '@kit.ArkTS'; 91import userAuth from '@ohos.userIAM.userAuth'; 92import { BusinessError } from '@kit.BasicServicesKit'; 93 94function stringToArray(str: string): Uint8Array { 95 let textEncoder = new util.TextEncoder(); 96 return textEncoder.encodeInto(str); 97} 98 99function arrayToString(arr: Uint8Array): string { 100 let textDecoder = util.TextDecoder.create("utf-8", { ignoreBOM: true }); 101 let str = textDecoder.decodeToString(arr, { stream: false }) 102 return str; 103} 104 105async function userAuthenticate(challenge: Uint8Array): Promise<Uint8Array> { 106 return new Promise((resolve, reject) => { 107 const authParam: userAuth.AuthParam = { 108 challenge: challenge, 109 authType: [userAuth.UserAuthType.PIN], 110 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 111 }; 112 const widgetParam: userAuth.WidgetParam = { title: '请输入锁屏密码' }; 113 try { 114 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 115 userAuthInstance.on('result', { 116 onResult(result) { 117 if (result.result == userAuth.UserAuthResultCode.SUCCESS) { 118 console.info(`User identity authentication succeeded.`); 119 resolve(result.token); 120 } else { 121 console.error(`User identity authentication failed.`); 122 reject(); 123 } 124 } 125 }); 126 userAuthInstance.start(); 127 } catch (error) { 128 let err = error as BusinessError; 129 console.error(`User identity authentication failed. Code is ${err.code}, message is ${err.message}`); 130 reject(); 131 } 132 }) 133} 134 135function preQueryAsset(): Promise<Uint8Array> { 136 return new Promise((resolve, reject) => { 137 try { 138 let query: asset.AssetMap = new Map(); 139 query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 140 asset.preQuery(query).then((challenge: Uint8Array) => { 141 resolve(challenge); 142 }).catch(() => { 143 reject(); 144 }) 145 } catch (error) { 146 let err = error as BusinessError; 147 console.error(`Failed to pre-query Asset. Code is ${err.code}, message is ${err.message}`); 148 reject(); 149 } 150 }); 151} 152 153async function postQueryAsset(challenge: Uint8Array) { 154 let handle: asset.AssetMap = new Map(); 155 handle.set(asset.Tag.AUTH_CHALLENGE, challenge); 156 try { 157 await asset.postQuery(handle); 158 console.info(`Succeeded in post-querying Asset.`); 159 } catch (error) { 160 let err = error as BusinessError; 161 console.error(`Failed to post-query Asset. Code is ${err.code}, message is ${err.message}`); 162 } 163} 164 165async function queryAsset() { 166 // step1. 调用asset.preQuery获取挑战值 167 preQueryAsset().then(async (challenge: Uint8Array) => { 168 try { 169 // step2. 传入挑战值，拉起用户认证框 170 let authToken: Uint8Array = await userAuthenticate(challenge); 171 // step3 用户认证通过后，传入挑战值和授权令牌，查询关键资产明文 172 let query: asset.AssetMap = new Map(); 173 query.set(asset.Tag.ALIAS, stringToArray('demo_alias')); 174 query.set(asset.Tag.RETURN_TYPE, asset.ReturnType.ALL); 175 query.set(asset.Tag.AUTH_CHALLENGE, challenge); 176 query.set(asset.Tag.AUTH_TOKEN, authToken); 177 let res: Array<asset.AssetMap> = await asset.query(query); 178 for (let i = 0; i < res.length; i++) { 179 // parse the secret. 180 let secret: Uint8Array = res[i].get(asset.Tag.SECRET) as Uint8Array; 181 // parse uint8array to string 182 let secretStr: string = arrayToString(secret); 183 } 184 // step4. 关键资产明文查询成功后，需要调用asset.postQuery进行查询的后置处理。 185 postQueryAsset(challenge); 186 } catch (error) { 187 // step5. preQuery成功，后续操作失败，也需要调用asset.postQuery进行查询的后置处理。 188 postQueryAsset(challenge); 189 } 190 }).catch ((err: BusinessError) => { 191 console.error(`Failed to pre-query Asset. Code is ${err.code}, message is ${err.message}`); 192 }) 193} 194``` 195