Image Search allows you to import and delete images in bulk through batch operations. You define the operations in a manifest file (increment.meta) stored in Object Storage Service (OSS), and Image Search processes them as a single task.
Before you begin
| Prerequisite | Description |
|---|---|
| Activate OSS | If not already activated, activate OSS and create a bucket. OSS is billed separately. For more information, see Billing overview. |
| Same-region requirement | Your OSS bucket and Image Search instance must be in the same region. |
| Upload images | Upload images to the OSS bucket. For more information, see Upload objects. |
| Image requirements | Maximum size: 4 MB. Supported formats: PNG, JPG, JPEG, BMP, GIF, WEBP, TIFF, PPM. Resolution: 100 x 100 to 4096 x 4096 pixels (for product image search and generic image search). The image cannot contain rotation information. Transmission latency must be less than 5 seconds. |
Step 1: Create the increment.meta file
Create a file named increment.meta in your OSS bucket. This manifest file tells Image Search which images to import or delete. Each line contains one JSON object that describes a single operation.
File rules
| Rule | Detail |
|---|---|
| Location | The increment.meta file and the images it references must be in the same bucket. |
| File name | Must be exactly increment.meta. Do not rename it. |
| Format | One JSON object per line. Multiple entries on a single line cause the operation to fail. |
| Image names | Must include file extensions (for example, girl_cloth10.jpg, not girl_cloth10). |
| Subdirectories | Use relative paths without a leading forward slash (for example, girlCloth/girl_cloth8.jpg). |
Example 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"}Parameter reference
Required parameters
| Parameter | Type | Description |
|---|---|---|
| OperationType | String | The operation type. ADD: import the image to Image Search. DELETE: delete the image from Image Search. |
| ProductId | String | The unique ID of the image. The ID can be up to 256 characters in length. |
| PicName | String | The name of the image stored in the OSS bucket. The name can be up to 256 characters in length. Include the file extension and use relative paths for images in subdirectories. |
| CustomContent | String | User-defined content returned in search results. The value can be up to 4,096 characters in length. You can use this field to store metadata such as image URLs or other business-related information. |
Optional parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| CategoryId | Integer | Auto-predicted | The image category. For more information, see Category reference. For product image search, the specified category takes precedence and must be within the valid range described in the category reference topic. If you do not specify a category, the system predicts one and returns the result in the response. For generic image search, this value is set to 88888888 regardless of input. |
| IntAttr | Integer | - | An integer attribute for filtering images in search queries. For more information, see Filter by condition. |
| StrAttr | String | - | A string attribute for filtering images in search queries. The value can be up to 128 characters in length. Special characters such as \, ¥, $, &, and % are not supported. For more information, see Filter by condition. |
| Crop | Boolean | true | Specifies whether to identify the subject in the image and search based on the identified subject. Set to false to search based on the entire image. |
| Region | String | - | The subject area of the image, specified as x1,x2,y1,y2 where x1 and y1 represent the upper-left corner, and x2 and y2 represent the lower-right corner. If specified, this value takes precedence over the Crop parameter.Note If you set this parameter, the `Crop` parameter is ignored. |
Each row in the file can contain only one image name. If a product ID corresponds to multiple image names, add a separate row for each image.
If you import an image with the same
ProductIdandPicNameas an existing image, the new image overwrites the existing one.
Step 2: Authorize Image Search to access OSS
The first time you use batch operations, you must authorize your Image Search account to access OSS. If you have already completed this authorization, skip this step.
Log on to the Image Search console.
Select the service type and click the name of the instance you want to manage.
Click the Batch Operation tab.
Click Create Batch Task. In the dialog box that appears, click Confirm the authorization.
On the Cloud Resource Access Authorization page, click Confirm Authorization Policy.
Step 3: Create a batch task
Log on to the Image Search console.
Select the service type and click the name of the instance you want to manage.
Click the Batch Operation tab.
Click Create Batch Task.
Configure the following parameters:
| Parameter | Description |
|---|---|
| Region | The region where your Image Search instance is deployed. |
| Bucket Name | The name of the OSS bucket. Make sure that the bucket is in the same region as your Image Search instance. |
| Path | The path where the images and the increment.meta file are stored. |
| META files | The increment.meta manifest file. Click the Refresh icon to verify that the file exists. |
| Callbacks after the operation completes | (Optional) A callback URL starting with HTTP or HTTPS. Image Search sends the task result to this URL after the task completes. |
Callback response format
When a callback URL is configured, Image Search sends the following JSON payload upon task completion:
{
"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
}| Field | Description |
|---|---|
| finishTime | The time when the task completed, accurate to the second. |
| instanceName | The name of the Image Search instance. |
| instanceId | The ID of the Image Search instance. |
| status | The task result. NORMAL indicates success. FAIL indicates failure. |
| taskId | The ID of the batch task. |
| message | A result description. success indicates the task completed. |
| processResultUrl | A URL to download detailed failure information if any images failed to process. |
Cancel a batch task
You can cancel a task that is in the Processing state:
On the Batch Operation tab, find the task and click Cancel.
In the confirmation dialog box, click OK.
After cancellation, the completed portions are retained and the task status changes to Stop. Click Download Results to view execution details.
View batch task results
On the Batch Operation tab of the Instance Details page, you can view all batch tasks created for the instance. Tasks in progress display a progress indicator. If a batch task is in the Imported state, you can view the task result description in the Error Message column.
Filter tasks by bucket name or path.
If the Error Message column shows Some of the images cannot be processed and are isolated., some images failed during the incremental task. Click Download Report to view the failure details.