Upload images - Image Search - Alibaba Cloud Documentation Center

This topic describes how to upload images to Image Search.

Background information

Image Search provides two methods for you to upload images. You can upload images by calling API operations or using Image Search SDKs. You can also upload multiple images from Object Storage Service (OSS) to Image Search at a time by using the batch operation feature.

If you want to upload only a small number of images, we recommend that you use the Image Search API or Image Search SDK. For more information, see AddImage.
If you are an enterprise user or want to upload multiple images that are not stored in an OSS bucket at a time, you can use ossimport to import images to OSS and then upload images to Image Search. For more information, see the Procedure section of this topic.
If you are an enterprise user or want to upload multiple images that are stored in an OSS bucket at a time, you can use the batch operation feature. For more information, see Perform batch operations.
Important
Before you use the batch operation feature of Image Search, make sure that your OSS bucket and Image Search instance reside in the same region.

Introduction to ossimport

Ossimport is a tool that is provided by OSS for migrating data to OSS. You can deploy ossimport on on-premises machines or Elastic Compute Service (ECS) instances to migrate data from your server or other cloud storage systems to OSS.

Ossimport has the following benefits in terms of image upload:

Images can be quickly updated to the image search engine.
The same OSS bucket can be used by different projects, such as development projects and online projects.
You can organize and manage different image sources based on your business requirements.
You can manage complex projects with ease, such as development projects and User Acceptance Testing (UAT) projects.
You can upload a large number of images at a time. The uploaded images can be reused in different scenarios. This takes full advantage of the network bandwidth.
You can standardize the management of image search services.

Limits on images

An image can be up to 4 MB in size.
The length and width of an image must be greater than 100 pixels but smaller than or equal to 4,096 pixels.

Procedure

Step 1: Download ossimport
Step 2: Activate OSS
Step 3: Create an OSS bucket
Step 4: Create an increment.meta file
Step 5: Authorize Image Search to access OSS
Step 6: Upload images

Step 1: Download ossimport

ossimport supports the standalone and distributed deployment modes.

Standalone deployment is suitable for the migration of data smaller than 30 TB in size. You can deploy ossimport on a machine that can access the data that you want to migrate and the OSS bucket to which you want to migrate the data. To deploy ossimport in standalone mode, download the standalone package.
Distributed deployment is suitable for the migration of data larger than 30 TB in size. You can deploy ossimport on multiple machines that can access the data that you want to migrate and the OSS bucket to which you want to migrate the data. To deploy ossimport in distributed mode, download the distributed package.

Note

To reduce the amount of time that is required to migrate large amounts of data, we recommend that you deploy ossimport on ECS instances that reside in the same region as your OSS bucket. Then, you can use an Express Connect circuit to connect the server that stores the source data to a Virtual Private Cloud (VPC). Migration efficiency is greatly improved when data is migrated from ECS instances to OSS over internal networks.

Step 2: Activate OSS

For more information, see Activate OSS.

Step 3: Create an OSS bucket

For more information, see Create buckets.

Note

Make sure that your OSS bucket and Image Search instance reside in the same region.

Step 4: Create an increment.meta file

Create an increment.meta file in the OSS bucket in which the images are stored. The file is used to store the details of the images to be processed in a batch task.

Note

The increment.meta file and the images specified in the increment.meta file must be stored in the same bucket. Otherwise, your batch operation fails.
The name of the increment.meta file is fixed and Image Search reads the details of the images to be processed in a batch task based on the file name. Do not modify the file name. Otherwise, your batch operation fails.
The batch operation feature of Image Search can process images that are stored in different paths in the same bucket. For example, the increment.meta file is stored in the root directory of a bucket named imagesearch, and an image named girl_cloth8.jpg is stored in a directory named girlCloth in the bucket. For the image, the PicName parameter must be specified as "PicName":"girlCloth/girl_cloth8.jpg" in the increment.meta file. Take note that no forward slash (/) can be added before girlCloth or after girl_cloth8.jpg. This logic also applies to multi-level directories.
You must append a file name extension to the names of the images stored in OSS. For example, if an image is named girl_cloth10.jpg, you must specify the PicName parameter as "PicName":"girl_cloth10.jpg" instead of "PicName":"girl_cloth10". Otherwise, your batch operation fails.
In the increment.meta file, you can specify only one image in a single row. If you specify multiple images in a single row, your batch operation fails.

The following sample code provides an example on how to specify images in the increment.meta file:

{"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": "ADD","ProductId": "1006","PicName": "girlCloth/girl_cloth10.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 the 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: the operation to import the image to Image Search. DELETE: the operation to delete the image from Image Search.
ProductId	String	Yes	The unique ID of the image. The ID can be up to 512 characters in length.
PicName	String	Yes	The name of the image that is stored in the OSS bucket. The name can be up to 512 characters in length. Important In the increment.meta file, each row contains at most one image name. If an image ID corresponds to multiple image names, you must write a row for each of the image names. You must append a file name extension to the image name. For example, for the girl_cloth.jpg image, write the name as girl_cloth.jpg instead of girl_cloth. Otherwise, your batch operation fails. If you import an image whose product ID and image name are the same as those of an existing image, the newly imported image overwrites the existing image. The image to be imported must meet the following requirements: The file size of the image cannot exceed 4 MB. The image is in one of the following formats: PNG, JPG, JPEG, BMP, GIF, WebP, TIFF, and PPM. The transmission timeout period cannot exceed 5 seconds. For product image searches, generic image searches, furniture and household supply image searches, and industrial hardware image searches, the length and width of the image must range from 100 pixels to 4,096 pixels. The image cannot contain rotation settings.
CategoryId	Integer	No	The category of the image. For more information about categories, 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 scope described in the "Category reference" topic. Otherwise, Image Search is unable to import the image to the image gallery. If you do not specify a category for an image, the system predicts the category, and returns the prediction result in the response. For generic image searches, copyrighted image searches, industrial hardware image searches, and furniture and household supply image searches, only 88888888 is returned for this parameter in the response regardless of whether a category is specified.
CustomContent	String	Yes	The user-defined content. The value can be up to 4,096 characters in length. Note The user-defined content of the image is automatically returned in the search results. You can add information such as the image URL and image description by using this parameter.
IntAttr	Integer	No	An integer-type attribute. This attribute can be used to filter images when you search for images. Note When you search for images, you can specify the Integer Attribute parameter and filter conditions to filter images. For more information, see Search for images by specifying filter conditions.
StrAttr	String	No	A string-type attribute. The value can be up to 128 characters in length. This attribute can be used to filter images when you search for images. Note When you search for images, you can specify the String Attribute parameter and filter conditions to filter images. For more information, see Search for images by specifying filter conditions.
Crop	Boolean	No	Specifies whether to identify the subject in the image and search for images based on the identified subject. Default value: true. Valid values: true: The system identifies the subject in the image and searches for the image based on the identified subject. false: The system does not identify the subject in the image, and searches for the image based on the entire image.
Region	String	No	The subject area of the image. The subject area is displayed in the format of `x1,x2,y1,y2`. x1 and y1 represent the upper-left point. x2 and y2 represent the lower-right point. Note If you specify this parameter, the Crop parameter does not take effect.

Step 5: Authorize Image Search to access OSS

To implement the batch operation feature in Image Search, you must use Image Search together with OSS. The first time you use the batch operation feature, authorize your Image Search account to access OSS. If your account is authorized, skip this step.

Step 6: Upload images

Log on to the Image Search console.
Select the service type and click the name of the Image Search instance that you want to manage.
Click the Batch Operation tab.
Click Create Batch Task.

Configure the following parameters for the batch task:

Region
This parameter specifies the region in which the Image Search instance resides.
Bucket Name
This parameter specifies the name of the bucket that you created in OSS.
Important
Make sure that your OSS bucket and Image Search instance reside in the same region.
Path
This parameter specifies the path in which the images and the increment.meta file are stored.
META files
This parameter specifies the file used to store the details of the images to be processed. The file is named increment.meta. You can click the Refresh icon on the right of the field to check whether the file exists.

Call backs after the operation completes

This parameter specifies the callback URL. The URL must start with HTTP or HTTPS.

{
  "finishTime": "2021-05-19 17:50:00",
  "instanceId": "imagesearch-cn-xxxx",
  "instanceName": "instanceName",
  "message": "success",
  "processResultUrl": "https://image-search-task-info.oss-cn-shanghai.aliyuncs.com/yyyyyyyyyy",
  "status": "NORMAL",
  "taskId": 111
}

Parameter	Description
finishTime	The time when the batch task is complete. The time is accurate to the second.
instanceName	The name of the Image Search instance.
instanceId	The ID of the Image Search instance.
status	The result of the batch task. A value of NORMAL indicates that the batch task is complete. A value of FAIL indicates that the batch task fails.
taskId	The ID of the batch task.
message	The description of the task result. A value of success indicates that the task is complete.
processResultUrl	The URL used to download the failure information.

Verify the results

After the upload task is complete, you can click the instance ID and check the status of the upload task.

If the images fail to be uploaded, click Show Import History to view the details. For more information, see the What may cause an OSS import request failure? section of the "FAQ" topic.
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.