本文介绍图像搜索服务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( "cn-shanghai", "ImageSearch", "imagesearch.cn-shanghai.aliyuncs.com");
  2. 创建Profile。生成IClientProfile的对象profile，该对象存放AccessKeyID、AccessKeySecret和地域信息。
    
// 阿里云账号AccessKey拥有所有API的访问权限，建议您使用RAM用户进行API访问或日常运维。
// 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里，否则可能导致AccessKey泄露，威胁您账号下所有资源的安全。
// 本示例以将AccessKey ID和AccessKey Secret保存在环境变量为例说明。您也可以根据业务需要，保存到配置文件里。
IClientProfile profile = DefaultProfile.getProfile("<region>", System.getenv("CC_AK_ENV"), System.getenv("CC_SK_ENV");
  3. 创建Client。从IClientProfile类中再生成IAcsClient的对象client，后续获得response都需要从IAcsClient中获得。
    IAcsClient client = new DefaultAcsClient(profile);

新增图片

新增图片代码示例如下。
import com.aliyuncs.DefaultAcsClient;import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.imagesearch.model.v20190325.AddImageRequest;
import com.aliyuncs.imagesearch.model.v20190325.AddImageResponse;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.profile.IClientProfile;
import org.apache.commons.codec.binary.Base64;
import java.io.*;

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();
    }

查询图片

  • 根据图片搜索图片
    import com.aliyuncs.DefaultAcsClient;import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.imagesearch.model.v20190325.SearchImageRequest;
import com.aliyuncs.imagesearch.model.v20190325.SearchImageResponse;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.profile.IClientProfile;
import org.apache.commons.codec.binary.Base64;
import java.io.*;

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）搜索图片
    import com.aliyuncs.DefaultAcsClient;import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.imagesearch.model.v20190325.SearchImageRequest;
import com.aliyuncs.imagesearch.model.v20190325.SearchImageResponse
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.profile.IClientProfile;

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();
    }

删除图片

删除图片代码示例如下。
import com.aliyuncs.DefaultAcsClient;import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.imagesearch.model.v20190325.DeleteImageRequest;
import com.aliyuncs.imagesearch.model.v20190325.DeleteImageResponse
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.profile.IClientProfile;

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下载使用示例。