すべてのプロダクト
Search
ドキュメントセンター

Image Search:バッチ操作

最終更新日:Jun 23, 2026

Image Search では、Alibaba Cloud Object Storage Service (OSS) からの画像のバッチインポートや、インデックス化された画像のバッチ削除が可能です。これにより、大規模なオフライン画像データを効率的、高信頼性、かつ便利に管理できます。

ワークフロー

  1. OSS の有効化

  2. OSS への画像のインポート

  3. increment.meta ファイルの作成

  4. Image Search への OSS アクセス権限の付与

  5. バッチタスクの作成

OSS の有効化

OSS をまだ有効化していない場合は、まず OSS を有効化し、次にコンソールでバケットを作成します。

説明
  • OSS は別途課金されます。詳細については、「料金概要」をご参照ください。

  • OSS バケットは、Image Search インスタンスと同じリージョンにある必要があります。

OSS への画像のインポート

ファイルをアップロードして OSS バケットに保存します。

説明

バッチタスクの作成時に、カスタムの画像ストレージパスを指定できます。

increment.meta ファイルの作成

画像が保存されている OSS パスに、increment.meta という名前のファイルを作成します。このファイルはバッチタスクの詳細を定義します。

説明
  1. increment.meta で指定された画像は、ファイル自体と同じ バケット にある必要があります。

  2. ファイル名 increment.meta は固定されています。名前を変更しないでください。

  3. 画像は同じバケット内の異なるパスに配置できます。PicName にはバケットルートからの相対パスを使用します。たとえば、バケット名が imagesearch で、increment.meta がルートディレクトリにある場合、girlCloth/ 内の画像は "PicName":"girlCloth/girl_cloth8.jpg" のように指定します。先頭または末尾にフォワードスラッシュ (/) を追加しないでください。

  4. 画像名には拡張子を含めてください。たとえば、"PicName":"girl_cloth10.jpg" を使用し、"PicName":"girl_cloth10" は使用しないでください。

  5. increment.meta の各行では、単一の画像操作を定義してください。

次のコードは、increment.meta ファイルのサンプルです。

{"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"}

各操作は JSON 形式で定義します。次の表で、各フィールドを説明します。

パラメーター

タイプ

必須

説明

OperationType

String

はい

操作タイプ。

  • ADD:画像を追加します。

  • DELETE:画像を削除します。

ProductId

String

はい

画像の一意の識別子。最大 256 文字です。

PicName

String

いいえ

OSS バケット内の画像の名前。最大 256 文字です。ADD 操作では必須です。DELETE 操作では、特定の画像を削除する場合にのみ指定します。

重要
  1. 各行には 1 つの画像名のみを含めることができます。1 つの ProductId に複数の画像がある場合は、画像ごとに個別の行を作成してください。

  2. 拡張子を含めてください。たとえば、girl_cloth.jpg を使用し、girl_cloth は使用しないでください。

  3. 既存の画像と同じ ProductIdPicName を持つ画像を追加すると、内容にかかわらず元の画像が上書きされます。

  4. インデックスに追加する画像は、次の要件を満たす必要があります。

    • 画像サイズは 4 MB を超えることはできません。

    • 対応形式: PNG、JPG、JPEG、BMP、GIF、WEBP、TIFF、PPM。

    • 転送タイムアウトは 5 秒を超えないようにしてください。

    • 商品画像検索、汎用画像検索の場合、画像の幅と高さは 100~4,096 ピクセルの範囲内である必要があります。

    • 画像に回転情報を含めることはできません。

CategoryId

Integer

いいえ

画像カテゴリ。有効なカテゴリは、「カテゴリリファレンス」に記載されています。

  • 商品画像検索の場合、有効なカテゴリを指定する必要があります。そうでない場合、インデックス作成に失敗します。

  • カテゴリを指定しない場合、システムがカテゴリを予測し、レスポンスでそのカテゴリを返します。

  • 汎用画像検索の場合、入力に関係なく、システムはカテゴリを 88888888 に設定します。

CustomContent

String

いいえ

ユーザー定義コンテンツ。最大 4,096 文字です。ADD 操作でのみ必須です。

説明

検索結果にはこの値が含まれます。このフィールドを使用して、画像 URL やその他の追加情報を保存し、画像をビジネスデータに関連付けることができます。

IntAttr

Integer

いいえ

検索結果を絞り込むための整数属性。

説明

フィルタ条件に整数属性を使用して検索結果をフィルタリングします。詳細については、「フィルタ条件」をご参照ください。

StrAttr

String

いいえ

文字列属性。最大 128 文字です。検索クエリでの絞り込みに使用します。

説明
  • フィルタ条件に文字列属性を使用して検索結果をフィルタリングします。詳細については、「フィルタ条件」をご参照ください。

  • \¥$&% などの特殊文字はサポートされていません。

Crop

ブール値

いいえ

主体の識別をおこなうかどうかを指定します。デフォルト: true

  • true :システムは主要な主体を識別し、それに基づいて検索します。

  • false :システムは主体の識別を行わずに、画像全体に基づいて検索します。

Region

String

いいえ

x1,y1,x2,y2 形式の画像の対象領域で、(x1, y1) が左上隅、(x2, y2) が右下隅になります。

説明

このパラメーターが設定されている場合、Crop パラメーターは無視されます。

Image Search への OSS アクセス権限の付与

バッチ操作では、Image Search が OSS リソースにアクセスする必要があります。この機能を初めて使用する際に、この権限を付与してください。すでに権限を付与している場合は、このセクションをスキップしてください。

  1. Image Search コンソールにログインします。

  2. 対象のサービスタイプとインスタンスを選択します。

  3. [一括操作] タブをクリックします。

  4. [バッチタスクの作成] をクリックし、表示されたダイアログボックスで [ワンクリック承認を確定] をクリックします。

  5. [クラウドリソースアクセス承認] ページで、[承認の確認] をクリックします。

    このアクションにより、AliyunImageSearchAccessingOSSRole ロールが作成され、AliyunImageSearchAccessingOSSRolePolicy システムポリシーがアタッチされます。

バッチタスクの作成

  1. Image Search コンソールにログインします。

  2. 対象のサービスタイプとインスタンスを選択します。

  3. [一括操作] タブをクリックします。

  4. [バッチタスクの作成] をクリックします。

    [バッチタスクの作成] ダイアログボックスで、必須の [バケット名] と [パス] を設定し、[Meta ファイル] を確認し、必要に応じて [完了時のコールバック] URL を指定して、[OK] をクリックします。

    • リージョン

      インスタンスが存在するリージョン。

    • バケット名

      OSS で作成したバケットの名前。

      重要

      OSS バケットは、Image Search インスタンスと同じリージョンにある必要があります。

    • パス

      画像と increment.meta ファイルのストレージパスです。

      たとえば、China (Shanghai) のバケット imagesearch1imagesearch/ フォルダーに画像と increment.meta がある場合は、そのパスを入力します。

    • Meta ファイル

      処理対象の画像をリストしたファイル。システムは、increment.meta という名前のファイルが存在するかどうかをチェックします。

    • 完了時のコールバック

      コールバック URL を入力します。HTTP および HTTPS の URL のみがサポートされています。

      {
        "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
      }

      フィールド

      説明

      finishTime

      タスクの完了時刻。形式は YYYY-MM-DD HH:MM:SS です。

      instanceName

      Image Search インスタンスの名前。

      instanceId

      Image Search インスタンスの ID。

      status

      タスクの結果:NORMAL (成功) または FAIL (失敗)。

      taskId

      タスク ID。

      message

      結果の説明。success は操作が成功したことを示します。

      processResultUrl

      エラーレポートをダウンロードするための URL。

バッチタスクのキャンセル

  1. [一括操作] タブで、対象のバッチタスクを見つけ、[操作] 列の [キャンセル] をクリックします。

  2. ポップアップウィンドウの情報を読み、[OK] をクリックしてバッチタスクの停止を開始します。表示される警告ダイアログボックスで、[OK] をクリックしてキャンセルを確定します。このプロセスには約 2 分かかります。

  3. キャンセル後、処理済みのデータは保存され、ステータスは[停止]に変わります。詳細を表示するには、[結果のダウンロード]をクリックします。

次のステップ

[バッチ操作] タブでタスクを監視します。実行中のタスクには [タスクの進捗状況] バーが表示され、[キャンセル] で停止できます。完了したタスクは [成功] または [停止済み] と表示され、[再実行] で再実行できます。

  • [バケット名] または [パス] でタスクを絞り込むことができます。

  • [一部の写真の処理に失敗し、隔離されました] というメッセージが表示された場合は、[結果のダウンロード] をクリックすると、失敗の詳細を表示できます。