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