本文介紹Image Search服務Java SDK的使用方法及樣本。

介面列表

介面名稱 介面說明
Add 增加圖片。
SearchImageByPic 使用圖片進行搜尋。
SearchImageByName 指定名稱,使用已入庫的圖片進行搜尋。
Delete 刪除圖片。

準備工作

  • 在安裝和使用阿里雲SDK前,確保您已經註冊阿里雲帳號並產生存取金鑰(AccessKey)。詳情請參見t1938336.html#task968
  • 將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. 設定Image Search服務訪問的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();
    // 必填,Image Search執行個體名稱。
    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();
        // 必填,Image Search執行個體名稱。
        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();
        // 必填,Image Search執行個體名稱。
        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();
    // 必填,Image Search執行個體名稱。
    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下載使用樣本。