# Java SDK
本章节介绍人证核身服务Java SDK，您可以参考本章节进行快速集成开发。
 #### 准备工作
- [注册华为账号并开通华为云](https://support.huaweicloud.com/usermanual-account/account_id_001.html)，并完成实名认证，账号不能处于欠费或冻结状态。
- 已开通人证核身服务。如未开通，请登录[人证核身管理控制台](https://console.huaweicloud.com/ivs)开通所需服务。
- 已具备开发环境，支持Java JDK 1.8 及其以上版本。
- 登录"[我的凭证](https://console.huaweicloud.com/iam/#/myCredential) \> 访问密钥"页面，获取Access Key（AK）和Secret Access Key（SK）。
  图1获取AK、SK   
  ![](https://support.huaweicloud.com/sdkreference-ivs/zh-cn_image_0000001778552877.png "点击放大") 
- 登录"[我的凭证](https://console.huaweicloud.com/iam/#/myCredential)"页面，获取"IAM用户名""、账号名"以及待使用区域的"项目ID"。调用服务时会用到这些信息，请提前保存。
  本样例以"华北-北京四"区域为例，获取对应的项目ID（project_id）。
  图2我的凭证   
  ![](https://support.huaweicloud.com/sdkreference-ivs/zh-cn_image_0000001779240861.png "点击放大") 
 
#### 安装SDK
推荐您通过Maven方式获取和安装SDK，首先需要在您的操作系统中[下载](https://maven.apache.org/download.cgi)并[安装Maven](https://maven.apache.org/install.html)，安装完成后您只需要在Java项目的pom.xml文件中加入相应的依赖项即可。
使用SDK前，需要安装"huaweicloud-sdk-core"和"huaweicloud-sdk-ivs"依赖项。请在[SDK中心](https://sdkcenter.developer.huaweicloud.com/?language=java)获取最新的sdk包版本，替换代码中版本。
```
// Maven配置，指定使用IVS服务所需的“huaweicloud-sdk-core”和“huaweicloud-sdk-ivs”依赖项
<dependency>
    <groupId>com.huaweicloud.sdk</groupId>
    <artifactId>huaweicloud-sdk-core</artifactId>
    <version>3.1.44</version>
</dependency>
<dependency>
    <groupId>com.huaweicloud.sdk</groupId>
    <artifactId>huaweicloud-sdk-ivs</artifactId>
    <version>3.1.44</version>
</dependency>
```
![](https://support.huaweicloud.com/sdkreference-ivs/public_sys-resources/note_3.0-zh-cn.png)
当出现第三方库冲突的时，如Jackson，okhttp3版本冲突等。可以引入如下bundle包(3.0.40-rc版本后)，该包包含所有支持的服务和重定向了SDK依赖的第三方软件，避免和业务自身依赖的库产生冲突：
```
<dependency>
    <groupId>com.huaweicloud.sdk</groupId>
    <artifactId>huaweicloud-sdk-bundle</artifactId>
    <version>[3.0.40-rc, 3.1.0)</version>
</dependency>
```
jackson版本要求请见[pom.xml](https://github.com/huaweicloud/huaweicloud-sdk-java-v3/blob/master/pom.xml)。SDK常见报错请参考[代码运行报错]。
#### 开始使用SDK
1. 导入依赖模块
   ```
   import com.huaweicloud.sdk.core.auth.ICredential;
   // 对用户身份进行认证
   import com.huaweicloud.sdk.core.auth.BasicCredentials;
   // 请求异常类
   import com.huaweicloud.sdk.core.exception.ConnectionException;
   import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
   import com.huaweicloud.sdk.core.exception.ServiceResponseException;
   // 导入ivs sdk
   import com.huaweicloud.sdk.ivs.v2.region.IvsRegion;
   import com.huaweicloud.sdk.ivs.v2.*;
   import com.huaweicloud.sdk.ivs.v2.model.*;
   ```
   
2. 配置认证信息
   配置AK、SK信息。华为云通过AK识别用户的身份，通过SK对请求数据进行签名验证，用于确保请求的机密性、完整性和请求者身份的正确性。AK、SK获取方法请参见[准备工作]。
   ```
   // 创建AK、SK认证凭据
   public static ICredential getCredential(String ak, String sk) {
       return new BasicCredentials()
               .withAk(ak)
               .withSk(sk);
   }
   ```
   初始化认证信息：
   ```
   String ak = System.getenv("HUAWEICLOUD_SDK_AK");
   String sk = System.getenv("HUAWEICLOUD_SDK_SK");
   ICredential credential = getCredential(ak, sk);
   ```
   ![](https://support.huaweicloud.com/sdkreference-ivs/public_sys-resources/caution_3.0-zh-cn.png)
   - 认证用的 ak 和sk 硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全。
   
   - 本示例以 ak 和 sk 保存在环境变量中来实现身份验证为例，运行本示例前请先在本地环境中设置环境变量HUAWEICLOUD_SDK_AK和HUAWEICLOUD_SDK_SK。
    
   图3Windows环境新建环境变量   
   ![](https://support.huaweicloud.com/sdkreference-ivs/zh-cn_image_0000001778638665.png "点击放大") 
3. 初始化客户端 指定region方式
   ```
   public static IvsClient getClient(Region region, ICredential auth) {
       // 初始化客户端
       return IvsClient.newBuilder()
               .withCredential(auth)
               .withRegion(region)
               .build();
   }
   ```
   华北-北京四region获取：IvsRegion.CN_NORTH_4
   华北-北京一region获取：IvsRegion.CN_NORTH_1
   
4. 发送请求并查看响应
   ```
   // 以调用标准版（三要素）DetectStandardByIdCardImage 接口为例
   DetectStandardByIdCardImageRequest request = new DetectStandardByIdCardImageRequest();
   DetectStandardByIdCardImageResponse response = client.detectStandardByIdCardImage(request);
   System.out.println(response.toString());
   ```
   
5. 异常处理
   表1异常处理 
   | 一级分类                     | 一级分类说明  | 二级分类                     | 二级分类说明                      |
   |:---|:---|:---|:---|
   | ConnectionException      | 连接类异常   | HostUnreachableException | 网络不可达、被拒绝。                  |
   | ConnectionException      | 连接类异常   | SslHandShakeException    | SSL认证异常。                    |
   | RequestTimeoutException  | 响应超时异常  | CallTimeoutException     | 单次请求，服务器处理超时未返回。            |
   | RequestTimeoutException  | 响应超时异常  | RetryOutageException     | 在重试策略消耗完成后，仍无有效的响应。         |
   | ServiceResponseException | 服务器响应异常 | ServerResponseException  | 服务端内部错误，Http响应码：\[500,\]。   |
   | ServiceResponseException | 服务器响应异常 | ClientRequestException   | 请求参数不合法，Http响应码：\[400, 500) |
      
   ```
   // 捕获和处理不同类型的异常
   DetectStandardByIdCardImageRequest request = new DetectStandardByIdCardImageRequest();
   try {
       DetectStandardByIdCardImageResponse response = client.detectStandardByIdCardImage(request);
       System.out.println(response.toString());
   } catch (ConnectionException e) {
       e.printStackTrace();
   } catch (RequestTimeoutException e) {
       e.printStackTrace();
   } catch (ServiceResponseException e) {
       e.printStackTrace();
       System.out.println(e.getHttpStatusCode());
       System.out.println(e.getErrorCode());
       System.out.println(e.getErrorMsg());
   }
   ```
   
 
![](https://support.huaweicloud.com/sdkreference-ivs/public_sys-resources/note_3.0-zh-cn.png)
使用异步客户端，配置日志等操作请参见[SDK中心](https://sdkcenter.developer.huaweicloud.com/)、[Java SDK使用指导](https://github.com/huaweicloud/huaweicloud-sdk-java-v3/blob/master/README_CN.md)、[Java SDK使用视频](https://res-static.hc-cdn.cn/cloudbu-site/china/zh-cn/support/sdk-video/1620783979754083351.mp4)。
#### SDK demo代码解析
**人证核身标准版（三要素）**
- 方式一：使用身份证图片、人像图片进行校验
  ```
  DetectStandardByIdCardImageRequest request = new DetectStandardByIdCardImageRequest();
  IvsStandardByIdCardImageRequestBody body = new IvsStandardByIdCardImageRequestBody();
  List<ReqDataByIdCardImage> listIvsStandardByIdCardImageRequestBodyDataReqData = new ArrayList<>();
  listIvsStandardByIdCardImageRequestBodyDataReqData.add(
      new ReqDataByIdCardImage()
          .withIdcardImage1("身份证人像面图像数据,使用base64编码")
          .withIdcardImage2("身份证国徽面图像数据,使用base64编码")
          .withFaceImage("现场人像图像数据,使用base64编码,")
  );
  IvsStandardByIdCardImageRequestBodyData databody = new IvsStandardByIdCardImageRequestBodyData();
  databody.withReqData(listIvsStandardByIdCardImageRequestBodyDataReqData);
  Meta metabody = new Meta();
  metabody.withUuid("唯一标识此次请求的ID,用户自定义,不超过64位。例如10eb0091-887f-4839-9929-cbc884f1e20e");
  body.withData(databody);
  body.withMeta(metabody);
  request.withBody(body);
  try {
      DetectStandardByIdCardImageResponse response = client.detectStandardByIdCardImage(request);
      System.out.println(response.toString());
  } catch (ConnectionException e) {
      e.printStackTrace();
  } catch (RequestTimeoutException e) {
      e.printStackTrace();
  } catch (ServiceResponseException e) {
      e.printStackTrace();
      System.out.println(e.getHttpStatusCode());
      System.out.println(e.getErrorCode());
      System.out.println(e.getErrorMsg());
  }
  ```
  
- 方式二：使用身份证姓名、身份证号码文本，人像图片进行校验
  ```
  DetectStandardByNameAndIdRequest request = new DetectStandardByNameAndIdRequest();
  IvsStandardByNameAndIdRequestBody body = new IvsStandardByNameAndIdRequestBody();
  List<StandardReqDataByNameAndId> listIvsStandardByNameAndIdRequestBodyDataReqData = new ArrayList<>();
  listIvsStandardByNameAndIdRequestBodyDataReqData.add(
      new StandardReqDataByNameAndId()
          .withVerificationName("被验证人的姓名")
          .withVerificationId("被验证人的身份证号码")
          .withFaceImage("现场人像图像数据,使用base64编码")
  );
  IvsStandardByNameAndIdRequestBodyData databody = new IvsStandardByNameAndIdRequestBodyData();
  databody.withReqData(listIvsStandardByNameAndIdRequestBodyDataReqData);
  Meta metabody = new Meta();
  metabody.withUuid("唯一标识此次请求的ID,用户自定义,不超过64位。例如10eb0091-887f-4839-9929-cbc884f1e20e");
  body.withData(databody);
  body.withMeta(metabody);
  request.withBody(body);
  try {
      DetectStandardByNameAndIdResponse response = client.detectStandardByNameAndId(request);
      System.out.println(response.toString());
  } catch (ConnectionException e) {
      e.printStackTrace();
  } catch (RequestTimeoutException e) {
      e.printStackTrace();
  } catch (ServiceResponseException e) {
      e.printStackTrace();
      System.out.println(e.getHttpStatusCode());
      System.out.println(e.getErrorCode());
      System.out.println(e.getErrorMsg());
  }
  ```
  
- 方式三：使用身份证姓名、身份证号码文本和现场拍摄的人像视频数据，实现活体人证核身
  ```
  DetectStandardByVideoAndNameAndIdRequest request = new DetectStandardByVideoAndNameAndIdRequest();
  IvsStandardByVideoAndNameAndIdRequestBody body = new IvsStandardByVideoAndNameAndIdRequestBody();
  List<StandardReqDataByVideoAndNameAndId> listDataReqData = new ArrayList<>();
  listDataReqData.add(new StandardReqDataByVideoAndNameAndId()
      .withVerificationName("被验证人的姓名")
      .withVerificationId("被验证人的身份证号码")
      .withVideo("现场拍摄人像视频数据,使用base64编码")
      .withActions("动作代码顺序列表"));
  IvsStandardByVideoAndNameAndIdRequestBodyData databody = new IvsStandardByVideoAndNameAndIdRequestBodyData();
  databody.withReqData(listDataReqData);
  Meta metabody = new Meta();
  metabody.withUuid("唯一标识此次请求的ID,用户自定义,不超过64位。例如10eb0091-887f-4839-9929-cbc884f1e20e);
  body.withData(databody);
  body.withMeta(metabody);
  request.withBody(body);
  try {
      DetectStandardByVideoAndNameAndIdResponse response = client.detectStandardByVideoAndNameAndId(request);
      System.out.println(response.toString());
  } catch (ConnectionException e) {
      e.printStackTrace();
  } catch (RequestTimeoutException e) {
      e.printStackTrace();
  } catch (ServiceResponseException e) {
      e.printStackTrace();
      System.out.println(e.getHttpStatusCode());
      System.out.println(e.getRequestId());
      System.out.println(e.getErrorCode());
      System.out.println(e.getErrorMsg());
  }
  ```
  
- 方式四：使用现场拍摄的人像视频数据，实现活体人证核身
  ```
  DetectStandardByVideoAndIdCardImageRequest request = new DetectStandardByVideoAndIdCardImageRequest();
  IvsStandardByVideoAndIdCardImageRequestBody body = new IvsStandardByVideoAndIdCardImageRequestBody();
  List<ReqDataByVideoAndIdCardImage> listDataReqData = new ArrayList<>();
  listDataReqData.add(
      new ReqDataByVideoAndIdCardImage()
          .withIdcardImage1("身份证人像面图像数据,使用base64编码")
          .withIdcardImage2("身份证国徽面图像数据,使用base64编码")
          .withVideo("现场拍摄人像视频数据,使用base64编码")
          .withActions("动作代码顺序列表")
  );
  IvsStandardByVideoAndIdCardImageRequestBodyData databody = new IvsStandardByVideoAndIdCardImageRequestBodyData();
  databody.withReqData(listDataReqData);
  Meta metabody = new Meta();
  metabody.withUuid("唯一标识此次请求的ID,用户自定义,不超过64位。例如10eb0091-887f-4839-9929-cbc884f1e20e");
  body.withData(databody);
  body.withMeta(metabody);
  request.withBody(body);
  try {
      DetectStandardByVideoAndIdCardImageResponse response = client.detectStandardByVideoAndIdCardImage(request);
      System.out.println(response.toString());
  } catch (ConnectionException e) {
      e.printStackTrace();
  } catch (RequestTimeoutException e) {
      e.printStackTrace();
  } catch (ServiceResponseException e) {
      e.printStackTrace();
      System.out.println(e.getHttpStatusCode());
      System.out.println(e.getRequestId());
      System.out.println(e.getErrorCode());
      System.out.println(e.getErrorMsg());
  }
  ```
  
**人证核身证件版（二要素）**
- 方式一：使用身份证图片进行校验
  ```
  DetectExtentionByIdCardImageRequest request = new DetectExtentionByIdCardImageRequest();
  IvsExtentionByIdCardImageRequestBody body = new IvsExtentionByIdCardImageRequestBody();
  List<ExtentionReqDataByIdCardImage> listIvsExtentionByIdCardImageRequestBodyDataReqData = new ArrayList<>();
  listIvsExtentionByIdCardImageRequestBodyDataReqData.add(
      new ExtentionReqDataByIdCardImage()
          .withIdcardImage1("身份证人像面图像数据,使用base64编码")
          .withIdcardImage2("身份证国徽面图像数据,使用base64编码")
  );
  IvsExtentionByIdCardImageRequestBodyData databody = new IvsExtentionByIdCardImageRequestBodyData();
  databody.withReqData(listIvsExtentionByIdCardImageRequestBodyDataReqData);
  Meta metabody = new Meta();
  metabody.withUuid("唯一标识此次请求的ID,用户自定义,不超过64位。例如10eb0091-887f-4839-9929-cbc884f1e20e");
  body.withData(databody);
  body.withMeta(metabody);
  request.withBody(body);
  try {
      DetectExtentionByIdCardImageResponse response = client.detectExtentionByIdCardImage(request);
      System.out.println(response.toString());
  } catch (ConnectionException e) {
      e.printStackTrace();
  } catch (RequestTimeoutException e) {
      e.printStackTrace();
  } catch (ServiceResponseException e) {
      e.printStackTrace();
      System.out.println(e.getHttpStatusCode());
      System.out.println(e.getErrorCode());
      System.out.println(e.getErrorMsg());
  }
  ```
  
- 方式二：使用身份证姓名、身份证号码文本进行校验
  ```
  DetectExtentionByNameAndIdRequest request = new DetectExtentionByNameAndIdRequest();
  IvsExtentionByNameAndIdRequestBody body = new IvsExtentionByNameAndIdRequestBody();
  List<ExtentionReqDataByNameAndId> listIvsExtentionByNameAndIdRequestBodyDataReqData = new ArrayList<>();
  listIvsExtentionByNameAndIdRequestBodyDataReqData.add(
      new ExtentionReqDataByNameAndId()
          .withVerificationName("被验证人的姓名")
          .withVerificationId("被验证人的身份证号码")
  );
  IvsExtentionByNameAndIdRequestBodyData databody = new IvsExtentionByNameAndIdRequestBodyData();
  databody.withReqData(listIvsExtentionByNameAndIdRequestBodyDataReqData);
  Meta metabody = new Meta();
  metabody.withUuid("唯一标识此次请求的ID,用户自定义,不超过64位。例如10eb0091-887f-4839-9929-cbc884f1e20e");
  body.withData(databody);
  body.withMeta(metabody);
  request.withBody(body);
  try {
      DetectExtentionByNameAndIdResponse response = client.detectExtentionByNameAndId(request);
      System.out.println(response.toString());
  } catch (ConnectionException e) {
      e.printStackTrace();
  } catch (RequestTimeoutException e) {
      e.printStackTrace();
  } catch (ServiceResponseException e) {
      e.printStackTrace();
      System.out.println(e.getHttpStatusCode());
      System.out.println(e.getErrorCode());
      System.out.println(e.getErrorMsg());
  }
  ```
  
 
#### 代码示例自动生成
[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/sdk?product=IVS&api=DetectStandardByIdCardImage)提供API检索及平台调试，支持全量快速检索、可视化调试、帮助文档查看和在线咨询。
您只需要在API Explorer中修改接口参数，即可自动生成对应的代码示例。同时，可在集成开发环境CloudIDE中完成代码的构建、调试和运行等操作。
图4API Explorer   
![](https://support.huaweicloud.com/sdkreference-ivs/zh-cn_image_0000001208378105.png "点击放大")
 #### 代码运行报错
- **java.lang.NoClassDefFoundError: Could not initialize class com.huaweicloud.sdk.core.http.HttpConfig at com.huaweicloud.sdk.core.ClientBuilder.build(ClientBuilder.java:98)**
  HttpConfig 这个类在sdk-core 包里面找不到，造成原因为用户使用的sdk版本太老导致，建议使用[最新版本](https://sdkcenter.developer.huaweicloud.com/?language=java)的华为云java sdk，运行代码再具体定位。
  
- **java.lang.NoSuchFieldError: ALLOW_LEADING_DECIMAL_POINT_FOR_NUMBERS**
  这个字段是 jackson-core 里面用来标识解析json格式数据是否支持前导小数点的字段，这个报错的意思是找不到这个字段，很可能是因为用户使用的jackson 版本太老导致。
  建议客户本地将jackson 版本升级到和华为云 java sdk一致，jackson版本要求请见[pom.xml](https://github.com/huaweicloud/huaweicloud-sdk-java-v3/blob/master/pom.xml)。
  引用华为云java sdk的[bundle包](https://github.com/huaweicloud/huaweicloud-sdk-java-v3/blob/master/README_CN.md)来解决 jackson 版本冲突的问题。
  ```
  <dependency>
      <groupId>com.huaweicloud.sdk</groupId>
      <artifactId>huaweicloud-sdk-bundle</artifactId>
      <version>[3.0.40-rc, 3.1.0)</version>
  </dependency>
  ```
  
- **java.lang.ClassNotFoundException: com.fasterxml.jackson.datatype.jsr310.JavaTimeModule**
  用户本地工程引入了jackson 框架，和 华为云sdk引入的jackson 框架冲突了，导致会报找不到某个类，建议 客户在本地引入[bundle包](https://github.com/huaweicloud/huaweicloud-sdk-java-v3/blob/master/README_CN.md)来避免出现依赖冲突。
  ```
  <dependency>
      <groupId>com.huaweicloud.sdk</groupId>
      <artifactId>huaweicloud-sdk-bundle</artifactId>
      <version>[3.0.40-rc, 3.1.0)</version>
  </dependency>
  ```
  
- **java.lang.ClassNotFoundException: okhttp3/Interceptor**
  用户本地引入的Okhttp3 版本和 华为云冲突，okhttp版本要求请见[pom.xml](https://github.com/huaweicloud/huaweicloud-sdk-java-v3/blob/master/pom.xml)。
  
- **INFO com.huaweicloud.sdk.core.HcClient - project id of region 'cn-north-4' not found in BasicCredentials, trying to obtain project id from IAM service: https://iam.myhuaweicloud.com**
  调用服务对应终端节点下的项目ID没有生成。
  在"[我的凭证](https://console.huaweicloud.com/iam/#/myCredential)"页面中查看对应终端节点的项目ID，确认系统中没有生成。在[IVS控制台](https://console.huaweicloud.com/ivs)将终端节点切换至调用服务所在的终端节点，之后前往"我的凭证"页面，即可查看到已生成对应的项目ID。