集成須知

服務端需要集成的兩個接口

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-獲取認證詳細數據。

   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 {
   
       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訪問的身份驗證。如何配置環境變量，請參見http://bestwisewords.com/document_detail/378657.html。
           com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
           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 {
   
       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訪問的身份驗證。如何配置環境變量，請參見http://bestwisewords.com/document_detail/378657.html。
           com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
           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);
       }
   }