当您使用SDK进行开发时,无需拼接HTTPS请求或实现签名算法,开发更方便。因此建议您通过SDK方式在服务端集成金融级实人认证。本文为您介绍金融级实人认证提供的Java、Python、PHP、C#、Golang、Node.js和Ruby语言的SDK。
发起认证请求参数说明
发起认证请求时,传入以下参数:
名称 | 类型 | 是否必选 | 描述 | 示例值 |
---|---|---|---|---|
method | String | 是 | 发起认证请求的操作。 取值:init。 | init |
sceneId | String | 是 | 认证场景ID,该ID在控制台创建认证场景后自动生成。关于如何创建认证场景,请参见添加认证场景。 | 1000000006 |
outerOrderNo | String | 是 | 客户服务端自定义的业务唯一标识,用于后续定位排查问题时使用。值最长为32位长度的字母和数字组合,请确保唯一。 | e0c34a77f5ac40a5aa5e6ed20c353888 |
bizCode | String | 是 | 认证场景码和商户发起认证的接入端有关:
| FACE_SDK |
identityType | String | 是 | 身份信息的参数类型,必须传入CERT_INFO。 | CERT_INFO |
certType | String | 是 | 用户证件类型。支持的证件类型,请参见方案概述。 唯一取值:IDENTITY_CARD。 | IDENTITY_CARD |
certNo | String | 是 | 用户身份证件号码。 | 330103xxxxxxxxxxxx |
certName | String | 是 | 用户姓名。 | 张三 |
returnUrl | String | 是 | 商户业务页面回调的目标地址。
| https://www.aliyun.com |
callbackUrl | String | 否 | 认证结果的回调通知地址,必须以HTTPS开头。平台完成认证后会回调该地址,并自动添加certifyId、passed。 | https://www.aliyun.com?certifyId=xxxx&passed=T |
callbackToken | String | 否 | 安全Token,由您自行生成,用于防重复、防篡改校验。如果设置了该值会在回调地址显示CallbackToken字段。 | NMjvQanQgplBSaEI0sL86WnQplB |
encryptType | String | 否 | 加密类型。为空表示不加密。 如开启加密传输,需传入加密算法。目前仅支持SM2国密算法。 如需传入加密算法,需对certName和certNo进行加密,并传入加密后的密文。有关参数加密的更多信息,请参见参数加密说明。 | SM2 |
说明 目前,仅Java语言提供有关开启加密传输的示例代码。更多信息,请参见Java SDK使用说明。
发起认证请求后,您会收到返回信息。返回参数列表如下:
名称 | 类型 | 是否必选 | 描述 | 示例值 |
---|---|---|---|---|
certifyId | String | 是 | 认证ID,刷脸认证的唯一标识。 警告 CertifyId字段为计费统计字段,为了方便后续核对账单,请您在本地留存该字段信息。 初始化接口返回的认证CertifyId在30分钟有效且仅能认证提交一次,请您在有效期内应用,避免重复使用。 | 7eff3ad26a9c7b68c511b9f35eb1**** |
certifyUrl | String | 是 | 认证流程入口Url。 重要 初始化接口返回的认证CertifyUrl在30分钟有效且仅能认证提交一次,请您在有效期内应用,避免重复使用。 | https://picker.antcloudauth.aliyuncs.com/gateway.do?... |
查询认证结果
查询认证结果时,传入以下参数:
名称 | 类型 | 是否必选 | 描述 | 示例值 |
---|---|---|---|---|
method | String | 是 | 查询人脸比对结果的操作。 取值:query。 | query |
certifyId | String | 是 | 认证ID,需与发起认证请求时返回的certifyId保持一致。 | 7eff3ad26a9c7b68c511b9f35eb1**** |
sceneId | String | 是 | 认证场景ID,需与发起认证请求时的sceneId保持一致。 | 100000***** |
发起查询请求后,您会收到返回信息。返回参数列表如下:
名称 | 类型 | 是否必选 | 描述 | 示例值 |
---|---|---|---|---|
passed | String | 是 | 是否通过认证。取值:
| T |
identityInfo | String | 否 | 认证的主体信息,一般的认证场景返回为空。 | "IdentityInfo": "{"cert_type":"IDENTITY_CARD","cert_no":"1******************9","cert_name":"张先生"}" |
materialInfo | String | 否 | 认证主体附件信息,主要为图片类材料,一般的认证场景都是返回空。 | "MaterialInfo": "{\"facial_picture_front\":{\"verify_score\":\"80.107902181204\",\"quality_score\":\"82\",\"FEATURE_FACE\":\"/9j/4AAQSkZJRgABAQAASABIAAD/4QBMRX\"}}" |
Java SDK使用说明
- 下载Java SDK源码:aliyun-openapijava-sdk。
- 配置Maven依赖。
<dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-saf</artifactId> <version>1.0.2</version> </dependency>
推荐Maven依赖仲裁:<dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-core</artifactId> <optional>true</optional> <version>4.5.0</version> </dependency> <dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <version>1.2.83_noneautotype</version> </dependency> <dependency> <groupId>com.google.code.gson</groupId> <artifactId>gson</artifactId> <version>2.8.2</version> </dependency>
说明- 配置Java SDK环境的具体操作请参见阿里云SDK开发指南。
- 您可以通过站点1和站点2获得对应的Maven依赖。
代码示例如下:
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import com.alibaba.fastjson.JSON;
import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.http.MethodType;
import com.aliyuncs.http.ProtocolType;
import com.aliyuncs.profile.DefaultProfile;
public class FaceVerifyTest {
public static void main(String[] args) throws IOException {
DefaultProfile profile = DefaultProfile.getProfile("cn-shanghai", "<your-access-key-id>", "<your-access-key-secret>");
IAcsClient client = new DefaultAcsClient(profile);
CommonRequest request = new CommonRequest();
request.setSysMethod(MethodType.POST);
request.setSysDomain("saf.cn-shanghai.aliyuncs.com");
request.setSysVersion("2017-03-31");
request.setSysAction("ExecuteRequest");
request.setSysProtocol(ProtocolType.HTTPS);
// 业务详细参数。
Map<String, Object> serviceParams = new HashMap<String, Object>();
// 发起认证请求。
serviceParams.put("method", "init");
serviceParams.put("sceneId", "1000000006");
serviceParams.put("outerOrderNo", "e0c34a77f5ac40a5aa5e6ed20c353888");
serviceParams.put("bizCode", "FACE"); // 当用户在iOS或安卓平台发起认证时,认证场景码是FACE_SDK;在小程序中,认证场景码则为FACE。
serviceParams.put("identityType", "CERT_INFO");
serviceParams.put("certType", "IDENTITY_CARD");
serviceParams.put("certNo", "330103xxxxxxxxxxxx");
serviceParams.put("certName", "张三");
serviceParams.put("returnUrl", "https://www.aliyun.com");
serviceParams.put("callbackUrl", "https://www.aliyun.com");
serviceParams.put("callbackToken", "NMjvQanQgplBSaEI0sL86WnQplB");
/*
// 如需开启个人信息加密传输。
serviceParams.put("encryptType", "SM2");
serviceParams.put("certNo", "BMjsstxK3S4b1YH*****Pet8ECObfxmLN92SLsNg==");
serviceParams.put("certName", "BCRD/7ZkNy7Q*****M1BMBezZe8GaYHrLwyJv558w==");
*/
/*
// 查询认证结果。
serviceParams.put("method", "query");
serviceParams.put("certifyId", "7eff3ad26a9c7b68c511b9f35eb1a354");
serviceParams.put("sceneId", "100000000");
*/
request.putBodyParameter("ServiceParameters", JSON.toJSONString(serviceParams));
// 固定值,Service = fin_face_verify。
request.putBodyParameter("Service", "fin_face_verify");
try {
CommonResponse response = client.getCommonResponse(request);
System.out.println(response.getData());
} catch (ServerException e) {
e.printStackTrace();
} catch (ClientException e) {
e.printStackTrace();
}
}
}
Python SDK使用说明
- 下载Python SDK 源码。
- 安装SDK核心库。
- 如果您使用的是Python 2.x,执行以下命令,安装阿里云SDK核心库。
pip install aliyun-python-sdk-core
- 如果您使用的是Python 3.x,执行以下命令,安装阿里云SDK核心库。
pip install aliyun-python-sdk-core-v3
- 如果您使用的是Python 2.x,执行以下命令,安装阿里云SDK核心库。
- 安装云产品SAF SDK。
pip install aliyun-python-sdk-saf
示例代码如下:
from aliyunsdkcore import client
from aliyunsdksaf.request.v20170331 import ExecuteRequestRequest
clt = client.AcsClient('your-access-key-id','your-access-key-secret','cn-shanghai')
# 设置参数。
request = ExecuteRequestRequest.ExecuteRequestRequest()
request.set_accept_format('json')
# 产品Service请参考[公共参数]文档中的Service字段描述。
request.add_query_param('Service', '购买的产品Service')
request.add_query_param('ServiceParameters', '入参JSON字符串')
# 发起请求。
response = clt.do_action_with_exception(request)
print(response)
说明 Python SDK的环境准备、安装和使用,请参见阿里云SDK开发指南。
PHP SDK使用说明
下载PHP SDK。
代码示例如下:
<?php
require __DIR__ . '/vendor/autoload.php';
use AlibabaCloud\Client\AlibabaCloud;
use AlibabaCloud\Client\Exception\ClientException;
use AlibabaCloud\Client\Exception\ServerException;
// 设置一个全局客户端。
// 需要替换AccessKey ID和AccessKey Secret。
AlibabaCloud::accessKeyClient('access-key-id', 'access-key-secret')
->regionId('cn-shanghai')
->asDefaultClient();
// 下述参数依照实际使用的接口做调整,本演示仅针对认证初始化接口。
$serviceParams = array(
"method"=> "init",
"sceneId"=> "1000000006",
"outerOrderNo"=> "e0c34a77f5ac40a5aa5e6ed20c353903",
"bizCode"=> "FACE",
"identityType"=> "CERT_INFO",
"certType"=> "IDENTITY_CARD",
"certNo"=> "330103xxxxxxxxxxxx",
"certName"=> "张三",
"returnUrl"=> "https://www.aliyun.com",
"callbackUrl"=> "https://www.aliyun.com",
"callbackToken"=>"NMjvQanQgplBSaEI0sL86WnQplB"
);
try {
// 下述参数无需调整。
$result = AlibabaCloud::rpcRequest()
->product('saf')
->scheme('https')
->version('2017-03-31')
->action('ExecuteRequest')
->method('POST')
->host('saf.cn-shanghai.aliyuncs.com')
->options([
'query' => [
'Service' => 'fin_face_verify',
'ServiceParameters' => json_encode($serviceParams)
],
])
->request();
echo($result);
} catch (ClientException $exception) {
echo $exception->getMessage() . PHP_EOL;
} catch (ServerException $exception) {
echo $exception->getMessage() . PHP_EOL;
echo $exception->getErrorCode() . PHP_EOL;
echo $exception->getRequestId() . PHP_EOL;
echo $exception->getErrorMessage() . PHP_EOL;
}
?>
说明 PHP SDK的环境准备、安装和使用,请参见阿里云SDK开发指南。
C# SDK使用说明
- 下载 C# SDK 源码。
- 引入SDK依赖。
dotnet add package aliyun-net-sdk-saf --version 3.0.1
代码示例如下:
using System.Text.Json;
using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Exceptions;
using Aliyun.Acs.Core.Profile;
class FaceVerifyTest
{
static void Main(string[] args)
{
// 需要替换AccessKey ID和AccessKey Secret。
IClientProfile profile = DefaultProfile.GetProfile(
"cn-shanghai",
"access-key-id",
"access-key-secret");
DefaultAcsClient client = new DefaultAcsClient(profile);
try
{
// 构造请求
CommonRequest request = new CommonRequest();
request.Protocol = Aliyun.Acs.Core.Http.ProtocolType.HTTPS;
request.Domain = "saf.cn-shanghai.aliyuncs.com";
request.Version = "2017-03-31";
request.Action = "ExecuteRequest";
//固定值,Service = fin_face_verify。
request.AddQueryParameters("Service", "fin_face_verify");
Dictionary<string, string> ServiceParameters = new Dictionary<string, string>();
ServiceParameters.Add("method", "init");
ServiceParameters.Add("sceneId", "100000000");
ServiceParameters.Add("outerOrderNo", "e0c34a77f5ac40a5aa5e6ed20c353888");
ServiceParameters.Add("bizCode", "FACE");
ServiceParameters.Add("identityType", "CERT_INFO");
ServiceParameters.Add("certType", "IDENTITY_CARD");
ServiceParameters.Add("certNo", "330103xxxxxxxxxxxx");
ServiceParameters.Add("certName", "张三");
ServiceParameters.Add("returnUrl", "https://www.aliyun.com");
ServiceParameters.Add("callbackUrl", "https://www.aliyun.com");
ServiceParameters.Add("callbackToken", "NMjvQanQgplBSaEI0sL86WnQplB");
/**
* 查询认证结果。
* map.Add("method", "query");
* map.Add("certifyId", "7eff3ad26a9c7b68c511b9f35eb1a354");
* map.Add("sceneId", "100000000");
*/
request.AddQueryParameters("ServiceParameters", JsonSerializer.Serialize(ServiceParameters));
// 发起请求,并得到Response
CommonResponse response = client.GetCommonResponse(request);
System.Console.WriteLine(response.Data);
}
catch (ServerException ex)
{
System.Console.WriteLine(ex.ToString());
}
catch (ClientException ex)
{
System.Console.WriteLine(ex.ToString());
}
}
}
说明 C# SDK的环境准备、安装和使用,请参见阿里云SDK开发指南。
Golang SDK使用说明
下载Golang SDK。
示例代码:
package main
import (
"encoding/json"
"fmt"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
)
// ResponseContent返回体。
type ResponseContent struct {
Data map[string]string `json:"data"`
RequestID string `json:"requestId"`
Code string `json:"code"`
Message string `json:"message"`
}
func main() {
// 需要替换AccessKey ID和AccessKey Secret。
client, err := sdk.NewClientWithAccessKey(
"cn-shanghai", "access-key-id", "access-key-secret")
request := requests.NewCommonRequest()
// 下述参数无需调整。
request.Domain = "saf.cn-shanghai.aliyuncs.com"
request.Version = "2017-03-31"
request.ApiName = "ExecuteRequest"
request.Scheme = "https"
request.QueryParams["Service"] = "fin_face_verify"
// 下述参数依照实际使用的接口做调整,本演示仅针对认证初始化接口。
serviceParam := map[string]string{
"method": "init",
"sceneId": "1000000006",
"outerOrderNo": "e0c34a77f5ac40a5aa5e6ed20c353900",
"bizCode": "FACE",
"identityType": "CERT_INFO",
"certType": "IDENTITY_CARD",
"certNo": "330103xxxxxxxxxxxx",
"certName": "张三",
"returnUrl": "https://www.aliyun.com",
"callbackUrl": "https://www.aliyun.com",
"callbackToken":"NMjvQanQgplBSaEI0sL86WnQplB"
}
serviceParamByte, err := json.Marshal(serviceParam)
if err != nil {
panic(err)
}
request.QueryParams["ServiceParameters"] = string(serviceParamByte)
response, err := client.ProcessCommonRequest(request)
if err != nil {
panic(err)
}
respContent := ResponseContent{}
err = json.Unmarshal(response.GetHttpContentBytes(), &respContent)
fmt.Printf("response data is %#v\n", respContent.Data)
fmt.Println("end")
}
说明 Golang SDK的环境准备、安装和使用,请参见阿里云SDK开发指南。
Node.js SDK使用说明
- 下载Node.js SDK 源码。
- 执行以下命令安装@alicloud/pop-core模块。
$ npm install @alicloud/pop-core --save
命令中的--save会将模块写入应用的package.json文件中,作为依赖模块。
Node.js 代码示例:
const Core = require('@alicloud/pop-core');
// 需要替换AccessKey ID和AccessKey Secret。
var client = new Core({
accessKeyId: 'access-key-id',
accessKeySecret: 'access-key-secret',
endpoint: 'https://saf.cn-shanghai.aliyuncs.com',
apiVersion: '2017-03-31'
});
// 下述参数依照实际使用的接口做调整,本演示仅针对认证初始化接口。
var serviceParams = {
"method": "init",
"sceneId": "1000000006",
"outerOrderNo": "e0c34a77f5ac40a5aa5e6ed20c353901",
"bizCode": "FACE",
"identityType": "CERT_INFO",
"certType": "IDENTITY_CARD",
"certNo": "330103xxxxxxxxxxxx",
"certName": "张三",
"returnUrl": "https://www.aliyun.com",
"callbackUrl": "https://www.aliyun.com",
"callbackToken":"NMjvQanQgplBSaEI0sL86WnQplB"
}
var params = {
"RegionId": "cn-shanghai",
"Service": "fin_face_verify",
"ServiceParameters": JSON.stringify(serviceParams)
}
var requestOption = {
method: 'POST'
};
client.request('ExecuteRequest', params, requestOption).then((result) => {
console.log(JSON.stringify(result));
}, (ex) => {
console.log(ex);
})
说明 Node.js SDK的环境准备、安装和使用,请参见阿里云SDK开发指南。
Ruby SDK使用说明
- 下载Ruby SDK 源码。
- 执行以下命令安装Alibaba Cloud Core SDK for Ruby。
$ gem install aliyunsdkcore
Ruby代码示例:
require 'aliyunsdkcore'
client = RPCClient.new(
access_key_id: 'your-access-key-id',
access_key_secret: 'your-access-key-secret',
endpoint: 'https://saf.cn-shanghai.aliyuncs.com',
api_version: '2017-03-31'
)
response = client.request(
action: 'ExecuteRequest',
params: {
"RegionId": "cn-shanghai",
# 产品Service请参考[公共参数]文档中的Service字段描述。
"Service": "购买的产品Service",
"ServiceParameters": "入参JSON字符串"
},
opts: {
method: 'POST'
}
)
print response
说明 Ruby SDK的环境准备、安装和使用,请参见阿里云SDK开发指南。