发起认证请求

在传入图片时，您需要上传其对应的HTTP/OSS地址或base64编码。

• HTTP地址：可访问的公网HTTP地址。例如，http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg。
• OSS地址：使用STS功能上传图片到实人认证服务指定的OSS bucket后，所生成的OSS文件地址，格式为oss://<STSToken.bucketName>:<path_to_file>。查看详情。
• base64编码：通过base64编码的图片，格式为base64://<图片 base64 字符串>。

部分场景中，业务方在发起认证请求前已经收集了一部分认证资料，需要传递给实人认证服务，这种情况下就需要使用 Binding扩展参数。目前支持 Binding的认证资料包括：

• Name：姓名。字符串格式，例如，李三。
• IdentificationNumber：身份证号。字符串格式，例如，630546198009090099。
• IdCardFrontPic：身份证人像面照片。字符串格式，具体请参考关于上传图片地址的说明。
• IdCardBackPic：身份证国徽面照片。字符串格式，具体请参考关于上传图片地址的说明。
• FacePic：人像照。字符串格式，具体请参考关于上传图片地址的说明。
• IDPic：二代身份证芯片中存储的头像照片。字符串格式，具体请参考关于上传图片地址的说明。
• FaceRetainedPic： 人像留底照片。字符串格式，具体请参考关于上传图片地址的说明。

业务方在自己的业务流程中已经采集了用户的姓名、身份证号、身份证人像面照片、身份证国徽面照片，而希望使用实人认证服务对用户进行活体检测并确认是本人操作。在这种情况下，就需要在发起认证请求时使用 Binding参数指定这些采集到的数据。该场景下， Binding的内容示例如下：

{
    \"Name\": \"李三\",
    \"IdentificationNumber\": \"584129192830192233\",
    \"IdCardFrontPic\": \"http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg\",
    \"IdCardBackPic\": \"base64:///9j/4AAQSkZJRgABAQEASABIAAD/2...\"
}

为了让业务方能够将图片上传到实人认证服务指定的OSS Bucket中，需要使用OSS提供的安全凭证管理（Security Token Service，简称 STS）功能。STS 能够依据bucket owner指定的访问策略生成一个临时的STS token给业务方，作为临时上传文件使用的凭据。关于STS的更多信息，请参考OSS访问控制。

1. 使用OSS SDK上传图片。
   例如，有一张人脸图片名字为 face.jpg，需要上传到实人认证服务进行比对，可以参考以下流程（Java 语言）：

   String bucketName = uploadToken.bucketName;
   String endpoint = uploadToken.endpoint;
   String accessKeyId = uploadToken.accessKeyId;
   String accessKeySecret = uploadToken.accessSecret;
   String token = uploadToken.token;
   // 初始化客户端
   OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, token);
   String fileKey = uploadToken.path + "face.jpg";  //  c3fef70f36ca4b0d8203a499beaa9f80/face.jpg
   byte[] content = getBytesOf("face.jpg");
   // 上传图片
   ossClient.putObject(bucketName, fileKey, content);
   // 关闭client
   ossClient.shutdown();

2. 使用SubmitMaterials接口上传 OSS 文件给实人认证服务。

   在与 OSS 对接成功上传图片后，获取到图片的文件路径（例如，c3fef70f36ca4b0d8203a499beaa9f80/face.jpg）。然后，需要将此图片的文件路径地址告知实人认证服务端。

   对于已成功上传至 OSS 的图片，传递给实人认证服务端的格式应为oss://<uploadToken.bucketName>:c3fef70f36ca4b0d8203a499beaa9f80/face.jpg。

   将此完整的图片文件名通过SubmitMaterials接口提交给实人认证服务即可。

请求示例

https://cloudauth.aliyuncs.com/?Action=GetVerifyToken
&RegionId=cn-hangzhou
&Biz=RPBasic
&TicketId=39ecf51e-2f81-4dc5-90ee-ff86125be683
&UserData=%7B%22orderId%22%3A+%221391012388%22%7D
&<[公共请求参数]>

请求body
Binding=%7B%22Name%22%3A+%22%E6%9D%8E%E4%B8%89%22%7D

返回示例

• XML格式

  <?xml version='1.0' encoding='UTF-8'?>
  <GetVerifyTokenResponse>
      <Data>
          <StsToken>
              <AccessKeySecret>OSSAccessKeySecret</AccessKeySecret>
              <BucketName>verify-external-image</BucketName>
              <AccessKeyId>OSSAccessKeyID</AccessKeyId>
              <Expiration>2017-09-14T02:28:20Z</Expiration>
              <EndPoint>https://oss-cn-shanghai.aliyuncs.com</EndPoint>
              <Token> CAIS2QJ1q6Ft5B2yfSjIpojNLPyNqehJ4I7dUWLptzMUfs1qvaDDujz2IHpFenBqBuActP8xmWFW5v0Slol5QZFLHhecNZop4pkLoQj8M9fL5Zfq4+Rf0sb6EDafAUZiUXtL7KarIunGc9KBNno2/00amMkGHFfPdlihNoLzxvwDR98LXw6+QCNbDdNNXGVLo9MbMn2jUpTINQXx0FLNEG1iuAd3lRl1i8KFz9ab9wDVgXDj1+YRvP6RGJW/aNR2N5oNfbWZ1edtJK3ay3wSuVoY6qpsjaJVvDrXotyHBVBVphSDOuXZtddlIgEiPfBiSvdIoaSsnqAo5+aNzNv5k00XZr5cDSjVA8KCuJKeQ7P1aI9nKOigaimSgoC1W8Or419+UxUyLxhXftctEHh0BCE3RyvSQq3dowqbPF75FPjfivpojMsrnw6457uQLl3KXK+YzSsI3he3n9aLxnQagAGuwJ7ORAZMwZm0UqNZ9uICFM2L39GX6/H22KDq2BYGO4bMcS49V+CuBuzTK1MEgRE5ELfBq6ttk4/Arah6gUomug6Yi8ZZCl0Zghgl36j5FEHeOYMS/RGnyiLVhRb+biHoncq/PsD/m8bv3VVQIcKQQ9gF71+WzebokSmhSw3A7w==
              </Token>
              <Path>bbff330091de48c585b637f03237a6db/</Path>
          </StsToken>
          <VerifyToken>
              <DurationSeconds>1800</DurationSeconds>
              <Token>bbff330091de48c585b637f03237a6db</Token>
            </VerifyToken>
            <CloudauthPageUrl>https://h5.m.taobao.com/user_verify/cloudauth.html?token=1234567890abcdefg</CloudauthPageUrl>
      </Data>
      <Success>true</Success>
      <Code>1</Code>
  </GetVerifyTokenResponse>

• JSON格式

  {
    "Code": "1",
    "Data": {
      "StsToken": {
        "AccessKeyId": "OSSAccessKeyID",
        "AccessKeySecret": "OSSAccessKeySecret",
        "BucketName": "verify-external-image",
        "EndPoint": "https://oss-cn-shanghai.aliyuncs.com",
        "Expiration": "2017-09-09T13:01:32Z",
        "Path": "92790974cd384f29a949b47f1c4ca3a5/",
        "Token": "CAIS2QJ1q6Ft5B2yfSjIpKaGDuzDqJpP5vWfNhLY1mMPPfxphvPa1Dz2IHpFenBqBuActP8xmWFW5v0SlokiEcAUHR2bMcB8tcQL/1nwatud6sbpsrJdg8GuEDOaVkZoDUsP7aarIunGc9KBNno2/00amMkGHFfPdlihNoLzxvwDR98LXw6+QCNbDdNNXGVLo9MbMn2jUpTINQXx0FLNEG1iuAd3lRl1i8KFz9ab9wDVgXDj1+YRvP6RGJW/aNR2N5oNfbWZ1edtJK3ay3wSuVoY6qpsjaJVvDrXotyHBVBVphSDOuXZtYw1c14hN/dmEKIf/KTyz6xx67CCndioxU9GYepcCC2CA8KCuJKeQ7P1aI9nKOigaimSgoC1W8Or419+UxUyLxhXftctEHh0BCE3RyvSQq3dowqbPF75FPjfivpojMsrnw6457uQLl3KXK+YzSsI3he3n9aLxnQagAGferYB1UMADL0LyW3Bd91xmtePTfJD8QszrYAladv2D7CxsqP7jdBoJ6gRQoE9U0NEibHGjFeNZ3C8VN5kmnU+aY6lnwgcz+7nEXBnrh4hl56ubNXb8Tkx5LDEbfXrZmnfv5LbuUn+79OkvQPQvfmL3xM+7ciWyAzmeBBGTIdf8w=="
      },
      "VerifyToken": {
        "Expire": 1800,
        "Token": "92790974cd384f29a949b47f1c4ca3a5"
      },
      "CloudauthPageUrl": "https://h5.m.taobao.com/user_verify/cloudauth.html?token=1234567890abcdefg"
    },
    "Success": true
  }