This topic describes how to upload images to Alibaba Cloud Image Search.

Background information

Image Search allows you to use the following methods to upload images: Use the Image Search API or the SDK, or use the OSSImport tool.

  • If you need to upload only a small number of images, we recommend that you use the Image Search API or SDK. For more information, see Add images.
  • If you are an enterprise user or need to upload a large number of images, we recommend that you use the OSSImport tool. For more information, see Procedure.

Introduction to the OSSImport tool

OSSImport is a tool that is provided by Alibaba Cloud Object Storage Service (OSS) to migrate data to OSS buckets. You can deploy OSSImport on your Elastic Compute Service (ECS) instance in the cloud or on your local server to migrate data that is stored locally or in another cloud storage system to OSS.

The OSSImport tool offers the following advantages in terms of image uploads:
  • Provides a quick method for you to update images to the image search engine.
  • Allows the same OSS bucket to be used by different projects, such as development projects and online projects.
  • Provides an easy method for you to organize and manage different image sources based on your business requirements.
  • Provides an effective method for you to manage complex projects, such as development projects and user acceptance testing (UAT) projects.
  • Allows you to upload a large number of images at a time. The uploaded images can be reused in different scenarios. This makes full use of the network bandwidth.
  • Allows you to standardize the management of image search services.

Image limits

  • The size of each image to be uploaded cannot exceed 2 MB.
  • The length and width of each image must range from 100 pixels to 4,096 pixels.

Procedure

  1. Step 1: Download the OSSImport tool
  2. Step 2: Activate the OSS service
  3. Step 3: Create an OSS bucket
  4. Step 4: Import the images that are specified in the increment.meta file
  5. Step 5: Grant Image Search the permission to access OSS
  6. Step 6: Upload images

Step 1: Download the OSSImport tool

You can deploy the tool in standalone mode or distributed mode:
  • If the size of the data to be migrated is smaller than 30 TB, we recommend that you use the standalone mode. You can deploy OSSImport on a machine that can access the data to be migrated and can access the OSS service. You can use the following link to download the OSSImport tool: OSSImport.
  • If the size of the data to be migrated is larger than 30 TB, we recommend that you use the distributed mode. You can deploy OSSImport on multiple machines that can access the data to be migrated and can access the OSS service. You can use the following link to download the OSSImport tool: OSSImport.
Note To reduce the time that is required to migrate large amounts of data, we recommend that you deploy OSSImport on the ECS instances in the region where your OSS bucket resides. You can also use an Express Connect circuit to connect the server that stores the source data to an Alibaba Cloud virtual private cloud (VPC). This way, data is migrated from ECS instances to OSS over an Alibaba Cloud VPC. This improves data migration efficiency.

Step 2: Activate the OSS service

For more information, see Activate OSS.

Step 3: Create an OSS bucket

For more information, see Create buckets.
Note The OSS bucket must be deployed in the same region as the Image Search instance to which you want to upload images.

Step 4: Import the images that are specified in the increment.meta file

Create the increment.meta file in the path where the images are stored in OSS. This file is used to store information about batch tasks.
Note The increment.meta file and the images that are involved in the increment.meta file must be stored in the same path. Otherwise, batch operations fail.
The following example of the increment.meta file is provided for your reference:
{"OperationType": "ADD","ProductId": "1000","PicName": "girl_cloth1.jpg","CategoryId": 0,"IntAttr": 0,"StrAttr": "value1","CustomContent": "k1:v1,k2:v2,k3:v3","Region": "20,40,60,80"}
{"OperationType": "ADD","ProductId": "1000","PicName": "girl_cloth2.jpg","CategoryId": 0,"IntAttr": 0,"StrAttr": "value2","CustomContent": "k1:v1,k2:v2,k3:v3","Region": "20,40,60,80"}
{"OperationType": "ADD","ProductId": "1001","PicName": "girl_cloth3.jpg","CategoryId": 1,"CustomContent": "k1:v1,k2:v2,k3:v3"}
{"OperationType": "ADD","ProductId": "1002","PicName": "girl_cloth4.jpg","CategoryId": 0,"CustomContent": "k1:v1,k2:v2,k3:v3","Crop": false}
{"OperationType": "ADD","ProductId": "1003","PicName": "girl_cloth7.jpg","CustomContent": "https://www.aliyun.com/imagesearch/girl_cloth7.jpg"}
{"OperationType": "ADD","ProductId": "1003","PicName": "girl_cloth6.jpg","CustomContent": "k1:v1,k2:v2,k3:v3"}
{"OperationType": "DELETE","ProductId": "1004","PicName": "fengyi.jpg"}
{"OperationType": "DELETE","ProductId": "1005"}
In this file, information about each image is encoded in JSON format. The following table describes the parameters in the file.
Parameter Type Required Description
OperationType String Yes The type of the operation. Valid values:
  • ADD: Add images.
  • DELETE: Delete images.
ProductId String Yes The unique ID of the image.
PicName String Yes The name of the image. The name of the image that is stored in the OSS bucket.
Note Each row contains at most one image name. If one image ID corresponds to multiple image names, you must write multiple rows.
CategoryId Integer No The category of the image. For more information, see Category reference.
  • For product image searches, if you specify a category for an image, the specified category prevails. The specified category must be within the category reference scope. Otherwise, the image fails to be imported to the image gallery in Image Search. If you do not specify a category for an image, the system predicts the category, and returns the result of category prediction in the response.
  • For cloth, brand, and generic image searches, the system sets the category ID to 88888888, regardless of whether you specify a category for an image.
CustomContent String Yes The user-defined content. The value can be up to 4,096 characters in length.
IntAttr Integer No The integer attribute. The attribute can be used to filter images when you search for images.
StrAttr String No The string attribute. The value can be up to 128 characters in length. The attribute can be used to filter images when you search for images.
Crop Boolean No Specifies whether to recognize the subject in the image and search for images based on the recognized subject. Valid values: true and false. Default value: true.
  • true: The system recognizes the subject in the image and searches for images based on the recognized subject.
  • false: The system does not recognize the subject in the image, and searches for images based on the entire image.
Note For cloth image searches, this parameter does not take effect. By default, the system searches for images based on the entire image.
Region String No The subject area in the image. The subject area is in the format of x1,x2,y1,y2. x1 and y1 represent the upper-left corner pixel. x2 and y2 represent the lower-right pixel.
Note
  • If you specify this parameter, the Crop parameter does not take effect.
  • For cloth image searches, this parameter does not take effect. By default, the system searches for images based on the entire image.

Step 5: Grant Image Search the permission to access OSS

Image Search provides the batch operation feature based on OSS. You must use Security Token Service (STS) to grant your Image Search account permissions to access OSS.

  1. Create a RAM role.
    1. Log on to the RAM console.
    2. In the left-side navigation pane, choose RAM Roles > Create RAM Role.
      Batch operation - Create RAM Role
    3. In the Create RAM Role pane, select Alibaba Cloud Service for the Trusted entity type parameter, and then click Next.
      Batch operation - Alibaba Cloud Service
    4. Configure role information.
      • Role Type: Select Normal Service Role.
      • RAM Role Name: Enter a RAM role name. The role name is imagesearch-test in this example.
      • Select Trusted Service: Select Image Search from the drop-down list.
      Batch operation - Create RAM Role
  2. Create a policy.
    1. In the left-side navigation pane, choose Permissions > Policies.
    2. On the Policies page, click Create Policy.
      Batch operation - Create Policy
    3. Edit the policy content.
      • Enter a policy name.
      • Set the Configuration Mode parameter to Script. In the following example, the policy content is provided.
        {
          "Version": "1",
          "Statement": [
            {
              "Effect": "Allow",
              "Action": [
                "oss:GetObject"
              ],
              "Resource": [
                "acs:oss:*:*:${bucket}/${path}/*"
              ]
            }
          ]
        }
        • ${bucket}: the bucket that you create in OSS to store your images, for example, imagesearch-increment
        • ${path}: the path where your increment.meta file is stored, for example, /increment
      Batch operation - Create Policy
  3. Grant permissions.
    1. In the left-side navigation pane of the RAM console, click RAM Roles.
    2. Click the name of the RAM role that you create.
      Grant permissions
    3. On the Permissions tab, click Add Permissions.
      Add permissions
    4. In the Add Permissions pane, click Custom Policy and select the policy that you create.
      Batch operation - Grant permissions
    5. Go back to the Permissions tab. You can view the custom policy that is attached to the RAM role.
      View the custom policy

Step 6: Upload images

  1. Log on to the Image Search console.
  2. Select the service type and click the name of your instance.
  3. Click the Batch Operation tab.
    Batch Operation
  4. Click Create Batch Task.
    Create Batch Task
  5. Specify the following parameters for the batch task:
    • ARN
      The following figure shows the location where you can view the value of the ARN parameter. Batch Operation - ARN
    • Bucket Name
      This parameter specifies the name of the bucket that you create in OSS.
      Note Make sure that your OSS instance and Image Search instance reside in the same region.
    • Path
      This parameter specifies the path where the images to be uploaded and the increment.meta file are stored.
      Note The path must start with a forward slash (/), for example, /imagesearch.
      Batch Operation - Path

Result

After the import task is completed, you can click the instance ID and check the status of the import task.
  • If the import task is in the Failed state, click Show Import History to view the details. For more information, see General.Failed uploads
  • If the images are uploaded as expected, click the instance ID. On the page that appears, click the Search by Image tab. On this tab, perform an image search test.Successful uploads