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