服务端集成

集成须知

服务端需要集成的两个接口

InitFaceVerify-发起认证请求

每次开始认证前通过调用本接口获取用于浏览器进行实人认证的认证链接CertifyUrl和每次认证的唯一CertifyId。

须将此接口的请求封装为开始认证的业务接口，供网页端调用。

{
    "appVersion": "1",
    "bioMetaInfo": "4.1.0:1150****,0",
    "appName": "com.aliyun.antcloudauth",
    "deviceType": "ios",
    "osVersion": "iOS 10.3.2",
    "apdidToken": "",
    "deviceModel": "iPhone9,1"
}

DescribeFaceVerify-获取认证详细数据

当您收到回调通知之后，可以在服务端通过该接口获取相应的认证状态和认证资料。

{
  "number": "610***********1110",
  "name": "王先生",
  "verifyName": "王先"
}

SDK调用示例

阿里云提供了OpenAPI门户，可以使用网页或命令行方式预先验证接口，您可以通过下面的链接进入调试：

• InitFaceVerify调试入口

• DescribeFaceVerify调试入口

SDK集成

Java语言为例，要求JDK 1.8及以上版本。

1. 在pom.xml中添加如下依赖，即可在Maven工程中使用SDK。

   • Java SDK依赖。以下依赖版本仅供参考，建议在实际配置时获取最新依赖版本。

     <dependency>
      <groupId>com.aliyun</groupId>
      <artifactId>cloudauth20190307</artifactId>
      <version>2.7.2</version>
     </dependency>

   • 身份验证依赖。请查看ChangeLog.txt获取所有已发布的版本列表（建议使用最新的版本）。

     <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>credentials-java</artifactId>
        <version>LATEST</version>
     </dependency>

     说明

     本示例通过阿里云Credentials工具从环境变量中读取AccessKey，来实现API访问的身份验证。您需要提前在系统配置环境变量，具体操作，请参见身份验证配置。

2. 接口调用示例。

   调用示例中仅设定了必要参数，详细参数请参见InitFaceVerify-发起认证请求和DescribeFaceVerify-获取认证详细数据。

   重要

   代码示例仅展示最基础的接口调用能力，实际使用时请根据业务需求情况加以优化和重构。

   例如，代码中变量名为credentialClient、config、client等通用对象在实际使用时，建议根据业务需求情况优化为单例模式，以提升性能。这些对象在示例代码中标有建议使用单例模式的字样。

   InitFaceVerify接口调用示例

   import java.util.Arrays;
   import java.util.List;
   
   import com.aliyun.cloudauth20190307.Client;
   import com.aliyun.cloudauth20190307.models.*;
   import com.aliyun.teaopenapi.models.Config;
   import com.aliyun.teautil.models.RuntimeOptions;
   
   public class InitFaceVerify {
      // 使用单例模式优化性能
       private static com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
   
       public static void main(String[] args) throws Exception {
   
           InitFaceVerifyRequest request = new InitFaceVerifyRequest();
           // 场景ID+L。
           request.setSceneId(100000xxxxL);
           // 设置商户请求的唯一标识。
           request.setOuterOrderNo("xxxx");
           // 认证方案。
           request.setProductCode("ID_PRO");
           // 模式。
           request.setModel("LIVENESS");
           request.setCertType("IDENTITY_CARD");
           request.setCertName("张先生");
           request.setCertNo("xxxx");
           // MetaInfo环境参数，此参数应由前端js获取并传入。
           request.setMetaInfo("{}");
           //业务页面回跳的目标地址。
           request.setReturnUrl("https://www.aliyundoc.com");
   
           InitFaceVerifyResponse response = initFaceVerifyAutoRoute(request);
   
           response.getBody().getRequestId();
           response.getBody().getResultObject().getCertifyId();
           System.out.println(response.getBody().getRequestId());
           System.out.println(response.getBody().getCode());
           System.out.println(response.getBody().getMessage());
           System.out.println(response.getBody().getResultObject() == null ? null
                   : response.getBody().getResultObject().getCertifyId());
       }
   
       private static InitFaceVerifyResponse initFaceVerifyAutoRoute(InitFaceVerifyRequest request) {
           // 第一个为主区域Endpoint，第二个为备区域Endpoint。
           List<String> endpoints = Arrays.asList("cloudauth.cn-shanghai.aliyuncs.com", "cloudauth.cn-beijing.aliyuncs.com");
           InitFaceVerifyResponse lastResponse = null;
           for (int i=0; i<endpoints.size(); i++) {
               try {
                   InitFaceVerifyResponse response = initFaceVerify(endpoints.get(i), request);
                   lastResponse = response;
   
                   // 服务端错误，切换到下个区域调用。
                   if(response != null){
                       if(500 == response.getStatusCode()){
                           continue;
                       }
                       if(response.getBody() != null){
                           if("500".equals(response.getBody().getCode())){
                               continue;
                           }
                       }
                   }
   
                   // 正常返回
                   return lastResponse;
               }catch (Exception e) {
                   e.printStackTrace();
                   if(i == endpoints.size()-1){
                       throw new RuntimeException(e);
                   }
               }
           }
   
           return lastResponse;
       }
   
       private static InitFaceVerifyResponse initFaceVerify(String endpoint, InitFaceVerifyRequest request)
               throws Exception {
           // 阿里云账号AccessKey拥有所有API的访问权限，建议您使用RAM用户进行API访问或日常运维。
           // 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里，否则可能导致AccessKey泄露，威胁您账号下所有资源的安全。
           // 本示例通过阿里云Credentials工具从环境变量中读取AccessKey，来实现API访问的身份验证。如何配置环境变量，请参见https://help.aliyun.com/document_detail/378657.html。
           // 建议使用单例模式
           Config config = new Config();
           config.setCredential(credentialClient);
           config.setEndpoint(endpoint);
           // 设置http代理。
           //config.setHttpProxy("http://xx.xx.xx.xx:xxxx");
           // 设置https代理。
           //config.setHttpsProxy("https://xx.xx.xx.xx:xxxx");
           // 建议使用单例模式
           Client client = new Client(config);
   
           // 创建RuntimeObject实例并设置运行参数。
           RuntimeOptions runtime = new RuntimeOptions();
           runtime.readTimeout = 10000;
           runtime.connectTimeout = 10000;
   
           return client.initFaceVerifyWithOptions(request, runtime);
       }
   
   }

   DescribeFaceVerify接口调用示例

   import java.util.Arrays;
   import java.util.List;
   
   import com.aliyun.cloudauth20190307.Client;
   import com.aliyun.cloudauth20190307.models.DescribeFaceVerifyRequest;
   import com.aliyun.cloudauth20190307.models.DescribeFaceVerifyResponse;
   import com.aliyun.teaopenapi.models.Config;
   import com.aliyun.teautil.models.RuntimeOptions;
   
   public class DescribeFaceVerify {
       // 使用单例模式优化性能
       private static com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
   
       public static void main(String[] args) throws Exception {
           
           // 创建API请求并设置参数。
           DescribeFaceVerifyRequest request = new DescribeFaceVerifyRequest(); 
           // 场景ID+L。
           request.setSceneId(0L); 
           // CertifyId在InitFaceVerify接口的返回值中。
           request.setCertifyId("xxxx");
      
           DescribeFaceVerifyResponse response = describeFaceVerifyAutoRoute(request);
   
           System.out.println(response.getBody().getRequestId());
           System.out.println(response.getBody().getCode());
           System.out.println(response.getBody().getMessage());
           System.out.println(
                   response.getBody().getResultObject() == null ? null : response.getBody().getResultObject().getPassed());
           System.out.println(
                   response.getBody().getResultObject() == null ? null : response.getBody().getResultObject().getSubCode());
           System.out.println(
                   response.getBody().getResultObject() == null ? null
                           : response.getBody().getResultObject().getIdentityInfo());
           System.out.println(
                   response.getBody().getResultObject() == null ? null
                           : response.getBody().getResultObject().getDeviceToken());
           System.out.println(
                   response.getBody().getResultObject() == null ? null
                           : response.getBody().getResultObject().getMaterialInfo());
       }
   
       private static DescribeFaceVerifyResponse describeFaceVerifyAutoRoute(DescribeFaceVerifyRequest request) {
           // 第一个为主区域Endpoint，第二个为备区域Endpoint。
           List<String> endpoints = Arrays.asList("cloudauth.cn-shanghai.aliyuncs.com", "cloudauth.cn-beijing.aliyuncs.com");
           DescribeFaceVerifyResponse lastResponse = null;
           for (int i = 0; i < endpoints.size(); i++) {
               try {
                   DescribeFaceVerifyResponse response = describeFaceVerify(endpoints.get(i), request);
                   lastResponse = response;
   
                   // 服务端错误，切换到下个区域调用。
                   if (response != null) {
                       if (500 == response.getStatusCode()) {
                           continue;
                       }
                       if (response.getBody() != null) {
                           if ("500".equals(response.getBody().getCode())) {
                               continue;
                           }
                       }
                   }
   
                   return lastResponse;
               } catch (Exception e) {
                   if (i == endpoints.size() - 1) {
                       throw new RuntimeException(e);
                   }
               }
           }
   
           return lastResponse;
       }
   
       private static DescribeFaceVerifyResponse describeFaceVerify(String endpoint, DescribeFaceVerifyRequest request)
               throws Exception {
           // 阿里云账号AccessKey拥有所有API的访问权限，建议您使用RAM用户进行API访问或日常运维。
           // 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里，否则可能导致AccessKey泄露，威胁您账号下所有资源的安全。
           //本示例通过阿里云Credentials工具从环境变量中读取AccessKey，来实现API访问的身份验证。如何配置环境变量，请参见https://help.aliyun.com/document_detail/378657.html。
           // 建议使用单例模式
           Config config = new Config();
           config.setCredential(credentialClient);
           config.setEndpoint(endpoint);
           
           // 建议使用单例模式
           Client client = new Client(config);
           
           RuntimeOptions runtime = new RuntimeOptions();
           runtime.readTimeout = 10000;
           runtime.connectTimeout = 10000;
   
           return client.describeFaceVerifyWithOptions(request, runtime);
       }
   }