本文介绍图像搜索服务Java SDK的使用方法及示例。

接口列表

接口名称 接口说明
Add 增加图片。
SearchImageByPic 使用图片进行搜索。
SearchImageByName 指定名称,使用已入库的图片进行搜索。
Delete 删除图片。

准备工作

  • 在安装和使用阿里云SDK前,确保您已经注册阿里云账号并生成访问密钥(AccessKey)。详情请参见创建AccessKey
  • 将SDK添加到项目中
    引入ImageSearch SDK依赖,通过Maven二方库依赖的方式将ImageSearch的SDK加入到自己的项目中。
    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-imagesearch</artifactId>
        <version>2.0.0</version>
    </dependency>
    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-core</artifactId>
        <version>[4.3.2,5.0.0)</version>
    </dependency>
    以下二方库可根据具体情况选择添加:
    <dependency>
        <groupId>commons-codec</groupId>
        <artifactId>commons-codec</artifactId>
        <version>1.9</version>
    </dependency>
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
        <version>4.5.3</version>
    </dependency>
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.8.2</version>
    </dependency>

创建Client

  1. 设置图像搜索服务访问的EndPoint,假定实例是在上海区域。
    DefaultProfile.addEndpoint( "<region>", "ImageSearch", "imagesearch.<region>.aliyuncs.com");
    说明 EndPoint请参见请求结构
  2. 创建Profile。生成IClientProfile的对象profile,该对象存放AccessKeyID、AccessKeySecret和地域信息。
    IClientProfile profile = DefaultProfile.getProfile("<region>", "<your-access-key-id>", "<your-access-key-secret>");
  3. 创建Client。从IClientProfile类中再生成IAcsClient的对象client,后续获得response都需要从IAcsClient中获得。
    IAcsClient client = new DefaultAcsClient(profile);

新增图片

新增图片代码示例如下。
AddImageRequest request = new AddImageRequest();
    // 必填,图像搜索实例名称。
    request.setInstanceName("demo");
    // 必填,商品id,最多支持 512个字符。
    // 一个商品可有多张图片。
    request.setProductId("test");
    // 必填,图片名称,最多支持 512个字符。
    // 1. ProductId + PicName唯一确定一张图片。
    // 2. 如果多次添加图片具有相同的ProductId + PicName,以最后一次添加为准,前面添加的图片将被覆盖。
    request.setPicName("test");
    // 选填,图片类目。
    // 1. 对于商品搜索:若设置类目,则以设置的为准;若不设置类目,将由系统进行类目预测,预测的类目结果可在Response中获取 。
    // 2. 对于布料、商标、通用搜索:不论是否设置类目,系统会将类目设置为88888888。
    request.setCategoryId(1);
    byte[] bytes2 = getBytes("/home/admin/demo.jpg");
    Base64 base64 = new Base64();
    String encodePicContent = base64.encodeToString(bytes2);
    // 必填,图片内容,Base64编码。
    // 最多支持 2MB大小图片以及5s的传输等待时间。当前仅支持jpg和png格式图片;
    // 对于商品、商标、通用图片搜索,图片长和宽的像素必须都大于等于200,并且小于等于1024;
    // 对于布料搜索,图片长和宽的像素必须都大于等于448,并且小于等于1024;
    // 图像中不能带有旋转信息。
    request.setPicContent(encodePicContent);

    // 选填,是否需要进行主体识别,默认为true。
    // 1.为true时,由系统进行主体识别,以识别的主体进行搜索,主体识别结果可在Response中获取。
    // 2. 为false时,则不进行主体识别,以整张图进行搜索。
    // 3.对于布料图片搜索,此参数会被忽略,系统会以整张图进行搜索。
    request.setCrop(true);
    // 选填,图片的主体区域,格式为 x1,x2,y1,y2, 其中 x1,y1 是左上角的点,x2,y2是右下角的点。
    // 若用户设置了Region,则不论Crop参数为何值,都将以用户输入Region进行搜索。
    // 对于布料图片搜索,此参数会被忽略,系统会以整张图进行搜索。
    request.setRegion("280,486,232,351");

    // 选填,整数类型属性,可用于查询时过滤,查询时会返回该字段。
    //  例如不同的站点的图片/不同用户的图片,可以设置不同的IntAttr,查询时通过过滤来达到隔离的目的
    request.setIntAttr(0);
    // 选填,字符串类型属性,最多支持 128个字符。可用于查询时过滤,查询时会返回该字段。
    request.setStrAttr("demo");
    // 选填,用户自定义的内容,最多支持 4096个字符。
    // 查询时会返回该字段。例如可添加图片的描述等文本。
    request.setCustomContent("1");

    try {
        AddImageResponse response = client.getAcsResponse(request)
    } catch (ClientException e) {
        // 抛出异常,例如参数无效,或者实例不可用等情况
        e.printStackTrace();
    }

查询图片

  • 根据图片搜索图片
    SearchImageRequest request = new SearchImageRequest();
        // 必填,图像搜索实例名称。
        request.setInstanceName("demo");
        // 选填,搜索类型,取值范围:
        // 1. SearchByPic(默认):根据图片搜索相似图片。
        // 2. SearchByName,根据已添加的图片搜索相似图片。
        // request.setType("SearchByPic");
    
        byte[] bytes2 = getBytes("/home/admin/demo.jpg");
        Base64 base64 = new Base64();
        String encodePicContent = base64.encodeToString(bytes2);
        // 图片内容,Base64编码。最多支持 2MB大小图片以及5s的传输等待时间。当前仅支持jpg和png格式图片;
        // 对于商品、商标、通用图片搜索,图片长和宽的像素必须都大于等于200,并且小于等于1024;
        // 对于布料搜索,图片长和宽的像素必须都大于等于448,并且小于等于1024;
        // 图像中不能带有旋转信息。
        // 1. Type=SearchByPic时,必填
        // 2. Type=SearchByName时,无需填写。
        request.setPicContent(encodePicContent);
    
        // 选填,商品类目。
        // 1. 对于商品搜索:若设置类目,则以设置的为准;若不设置类目,将由系统进行类目预测,预测的类目结果可在Response中获取 。
        // 2. 对于布料、商标、通用搜索:不论是否设置类目,系统会将类目设置为88888888。
        request.setCategoryId(1);
    
        // 选填,是否需要进行主体识别,默认为true。
    // 1.为true时,由系统进行主体识别,以识别的主体进行搜索,主体识别结果可在Response中获取。
        // 2. 为false时,则不进行主体识别,以整张图进行搜索。
        // 3.对于布料图片搜索,此参数会被忽略,系统会以整张图进行搜索。
        request.setCrop(false);
    
        // 选填,图片的主体区域,格式为 x1,x2,y1,y2, 其中 x1,y1 是左上角的点,x2,y2是右下角的点。
        // 若用户设置了Region,则不论Crop参数为何值,都将以用户输入Region进行搜索。
        // 3.对于布料图片搜索,此参数会被忽略,系统会以整张图进行搜索。
        request.setRegion("280,486,232,351");
    
        // 选填,返回结果的数目。取值范围:1-100。默认值:10。
        request.setNum(2);
        // 选填,返回结果的起始位置。取值范围:0-499。默认值:0。
        request.setStart(1);
    
        // 选填,过滤条件
        // int_attr支持的操作符有>、>=、<、<=、=,str_attr支持的操作符有=和!=,多个条件之支持AND和OR进行连接。
        // 示例:
        //  1. 根据IntAttr过滤结果,int_attr>=100
        //  2. 根据StrAttr过滤结果,str_attr!="value1"
        //  3. 根据IntAttr和StrAttr联合过滤结果,int_attr=1000 AND str_attr="value1"
        request.setFilter("int_attr=1");
    
        try {
            SearchImageResponse response = client.getAcsResponse(request);
        } catch (ClientException e) {
            e.printStackTrace();
        }
  • 根据已入库的图片(ProductId+PicName)搜索图片
    SearchImageRequest request = new SearchImageRequest();
        // 必填,图像搜索实例名称。
        request.setInstanceName("demo");
    
        // 选填,搜索类型,取值范围:
        // 1. SearchByPic(默认):根据图片搜索相似图片。
        // 2. SearchByName,根据已添加的图片搜索相似图片。
         request.setType("SearchByName");
    
        // 商品id。
        // 1. Type=SearchByPic时,无需填写
        // 2. Type=SearchByName时,必填,已添加图片的ProductId。
        request.setProductId("test");
    
        // 图片名称。
        // 1. Type=SearchByPic时,无需填写
        // 2. Type=SearchByName时,必填,已添加图片的PicName。
        request.setPicName("test");
    
        // 选填,商品类目。
        // 1. 对于商品搜索:若设置类目,则以设置的为准;若不设置类目,将由系统进行类目预测,预测的类目结果可在Response中获取 。
        // 2. 对于布料、商标、通用搜索:不论是否设置类目,系统会将类目设置为88888888。
        request.setCategoryId(1);
    
        // 选填,是否需要进行主体识别,默认为true。
        // 1.为true时,由系统进行主体识别,以识别的主体进行搜索,主体识别结果可在Response中获取。
    // 2. 为false时,则不进行主体识别,以整张图进行搜索。
        // 对于布料图片搜索,此参数会被忽略,系统会以整张图进行搜索。
        request.setCrop(false);
        // 选填,图片的主体区域,格式为 x1,x2,y1,y2, 其中 x1,y1 是左上角的点,x2,y2是右下角的点。
        // 若用户设置了Region,则不论Crop参数为何值,都将以用户输入Region进行搜索。
        // 对于布料图片搜索,此参数会被忽略,系统会以整张图进行搜索。
        request.setRegion("280,486,232,351");
    
        // 选填,返回结果的数目。取值范围:1-100。默认值:10。
        request.setNum(2);
        // 选填,返回结果的起始位置。取值范围:0-499。默认值:0。
        request.setStart(1);
    
        // 选填,过滤条件
        // int_attr支持的操作符有>、>=、<、<=、=,str_attr支持的操作符有=和!=,多个条件之支持AND和OR进行连接。
        // 示例:
        //  1. 根据IntAttr过滤结果,int_attr>=100
        //  2. 根据StrAttr过滤结果,str_attr!="value1"
        //  3. 根据IntAttr和StrAttr联合过滤结果,int_attr=1000 AND str_attr="value1"
        request.setFilter("int_attr=1");
    
        try {
            SearchImageResponse response = client.getAcsResponse(request);
        } catch (ClientException e) {
            e.printStackTrace();
        }

删除图片

删除图片代码示例如下。
DeleteImageRequest request = new DeleteImageRequest();
    // 必填,图像搜索实例名称。
    request.setInstanceName("demo");

    // 必填,商品id。
    request.setProductId("test");

    // 选填,图片名称。若不指定本参数,则删除ProductId下所有图片;若指定本参数,则删除ProductId+PicName指定的图片。
    request.setPicName("test");

    try {
        DeleteImageResponse response = client.getAcsResponse(request);
    } catch (ClientException e) {
        e.printStackTrace();
    }

附录

获取图片二进制数组方法如下。
private static byte[] getBytes(String filePath) {
        byte[] buffer = null;
        try {
            File file = new File(filePath);
            FileInputStream fis = new FileInputStream(file);
            // picture max size is 2MB
            ByteArrayOutputStream bos = new ByteArrayOutputStream(2000 * 1024);
            byte[] b = new byte[1000];
            int n;
            while ((n = fis.read(b)) != -1) {
                bos.write(b, 0, n);
            }
            fis.close();
            bos.close();
            buffer = bos.toByteArray();
        } catch (FileNotFoundException e) {
            e.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }
        return buffer;
    }

SDK示例下载

单击Java SDK下载使用示例。