All Products
Document Center

OSS import

Last Updated: Aug 04, 2020


The OSS Import method is suitable for scenarios where you have to import a large volume of images.


To use OSS Import, you must activate the Object Storage Service (OSS) and then authorize the required RAM role to your Image Search account as follows:

1. Activate OSS

  • For information about activating the OSS service, see Sign up for OSS. Make sure your Image Search instances and OSS are in the same region.
  • After the OSS service is activated, you must create a bucket. For more information, see Create a bucket.

2. Import images

To import images to an OSS bucket, follow these guidelines:

  • The path where the images are stored is configurable. After you specify a path, click OSS Import to import images.

  • Make sure that you have created the increment.meta file in the specified path. This file is used to store information about OSS import tasks. The file format must meet the following requirements:

    • Each row corresponds only one image.
    • All image information is encoded in JSON format as follows:
Name Type Description Remarks
OperationType String Action This field specifies the action to be taken on the images. ADD means adding new images.

DELETE means removing images.
ProductId String Unique product/image identifier For product search, this field specifies the product ID.

For generic search, this field specifies the image name.
CategoryId Integer Category information For product search, this field is not required, it specifies the category to which the images belong. For more information, see Category Reference.

This field is not required by generic search. You can leave this field empty or set the value to 88888888.
CustomContent String Custom content This field specifies the custom content, which is read-only to the system and is displayed in the search results.
PicName String Image Name This field specifies a list of image names that you need to import.
  • Example of the increment.meta file:

    1. {"OperationType":"ADD","ProductId":"1000", "CategoryId":0, "CustomContent":"k1:v1,k2:v2,k3:v3","PicName":"girl_cloth1.jpg"}
    2. {"OperationType":"ADD","ProductId":"1001", "CategoryId":1,"CustomContent":"k1:v1,k2:v2,k3:v3", "PicName":"girl_cloth3.jpg"}
    3. {"OperationType":"ADD","ProductId":"1002", "CategoryId":0, "CustomContent":"k1:v1,k2:v2,k3:v3", "PicName":"girl_cloth4.jpg"}
    4. {"OperationType":"ADD","ProductId":"1003", "CustomContent":"k1:v1,k2:v2,k3:v3", "PicName":"girl_cloth6.jpg"}
    5. {"OperationType":"DELETE","ProductId":"1004", "PicName":"fengyi.jpg"}
    6. {"OperationType":"DELETE","ProductId":"1005"}
  • All images listed in the increment.meta file are stored in the same path as the increment.meta file.

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

3. Authorize RAM roles to your account

To use OSS Import, you must use Security Token Service to grant your Image Search account temporary permissions to access OSS. The procedure is as follows:

Create a role

  1. Go to the RAM console, select RAM Roles > Create RAM Role.


  2. Select Alibaba Cloud Service > Image Search.


  3. Enter a RAM role name.


Authorize a role

A newly created role does not have any permissions. You must create a policy to acquire the relevant permissions.

To create a policy, use the following format:

  1. {
  2. "Version": "1",
  3. "Statement": [
  4. {
  5. "Effect": "Allow",
  6. "Action": [
  7. "oss:GetObject"
  8. ],
  9. "Resource": [
  10. "acs:oss:*:*:${bucket}${path}/*"
  11. ]
  12. }
  13. ]
  14. }
  • ${bucket}: Specifies a bucket.
  • ${path}: Specifies a path for storing the images that you need to import.


In this example, a policy is created for importing images to the /increment path in the bucket named imagesearch-increment.

  1. {
  2. "Version": "1",
  3. "Statement": [
  4. {
  5. "Effect": "Allow",
  6. "Action": [
  7. "oss:GetObject"
  8. ],
  9. "Resource": [
  10. "acs:oss:*:*:imagesearch-increment/increment/*"
  11. ]
  12. }
  13. ]
  14. }

Then authorize the RAM role to your account, follow these steps:

  1. On the RAM console, select Permissions > Policies > Create Policy.

    image.png | center | 830x405

  2. On the Create Custom Policy page, enter the Policy Name, select Script and configure the Policy Document.

    image.png | center | 830x639

  3. Click OK.

  4. Return to the RAM console, select RAM Roles.

  5. In the Role Name column, select the target RAM role and click Add Permissions.


  6. In the Policy Name column on the left, select the created policy and click OK.

    image.png | center | 830x405

Import images

To import images from OSS, go to the Image Search console, on Instance Details page, click OSS Import, enter the basic information, and then click Import.

image.png | center | 830x404

ARN: Your RAM role account name created for importing to Image Search. Click your role to view the ARN, as shown in the following figure:


Bucket Name: The name of the bucket that stores your images in OSS.

Note: Make sure your Image Search instance and OSS are in the same region.

Path: The path where your images are stored.

Note: The data path must start with a forward slash (/), for example, /imagesearch.

The following figure shows the data path of /imagesearch in the imagesearch1 bucket:

image.png | center | 830x406

OSS import history

On the Instance Details page, you can click View History to view the history of OSS import tasks. When the OSS import task is complete, you receive a message that indicates the result.

  • If some of the images cannot be processed, you receive the following error message: “Some of the images cannot be imported. Download Report.” If this error occurs, you can download the report to view the impacted images and identify the root cause of the error.
  • If all of the selected images have been imported, you receive a message indicating that the import task is successful.