All Products
Search
Document Center

Image Search:Perform batch operations

Last Updated:Sep 12, 2023

Image Search provides the batch operation feature. You can use the feature to import images from Object Storage Service (OSS) to Image Search and delete images from Image Search at a time. This feature provides the following benefits: high stability, high efficiency, and ease of use. This feature is suitable for scenarios in which you need to manage a large number of images by using a single task. This topic describes how to import and delete multiple images at a time.

Procedure

  1. Activate OSS.

  2. Import images to OSS.

  3. Create an increment.meta file.

  4. Authorize an Image Search account to access OSS.

  5. Create a batch task.

Activate OSS

If OSS is not activated, activate OSS. For more information, see Activate OSS. After you activate OSS, you must create a bucket. For more information, see Create buckets.

Note
  • You are separately charged for OSS. For more information about the billing methods, see Billing overview.

  • Your OSS bucket and Image Search instance must reside in the same region. Otherwise, the batch operation feature is unavailable.

Import images to OSS

For more information about how to import images to OSS, see Upload objects.

Note

You can specify a custom path in the OSS bucket to store the images that are imported to the OSS bucket. When you create a batch task, you must specify the path as the value of the Path parameter.

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
  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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
  1. 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.

  2. 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.

  3. 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.

  4. 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.

Authorize an Image Search account 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.

  1. Log on to the Image Search console.

  2. Select the service type and click the name of the Image Search instance that you want to manage.

  3. Click the Batch Operation tab.

    批量操作
  4. Click Create Batch Task. In the message that appears, click Confirm the authorization.

  5. On the Cloud Resource Access Authorization page, click Confirm Authorization Policy.

Create a batch task

  1. Log on to the Image Search console.

  2. Select the service type and click the name of the Image Search instance that you want to manage.

  3. Click the Batch Operation tab.

    批量操作
  4. Click Create Batch Task.

    新建批量任务
  5. 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.

      批量上传.png
    • 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.

What to do next

On the Batch Operation tab of the Instance Details page, you can view the details of all batch tasks that are crated in the Image Search instance. If a batch task is in the Imported state, you can view the description of the batch task result in the Error Message column.

实例详情
  • You can filter batch tasks by bucket name or path.

  • If the Some of the images cannot be processed and are isolated. message appears in the Error Message column for a batch task, some images failed to be processed. You can click Download Result in the Result column to view the reason why the images failed to be processed.