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

Image Search:画像のアップロード

最終更新日:Aug 28, 2026

このトピックでは、Image Search に画像をアップロードする方法を説明します。

背景情報

Image Search には、API または SDK を使用する方法と、Object Storage Service (OSS) の画像を使用してバッチオペレーションを実行する方法の、2 つのアップロード方法があります。

  • アップロードする画像が少ない場合は、API または SDK の使用を推奨します。 詳細については、「AddImage」をご参照ください。

  • エンタープライズユーザーの場合、または Object Storage Service (OSS) に保存されていない多数の画像をアップロードする必要がある場合は、ossimport ツールを使用して画像を OSS バケットに移行し、バッチアップロードを実行します。 詳細については、「手順」をご参照ください。

  • エンタープライズユーザーの場合、または Object Storage Service (OSS) バケットにすでに保存されている多数の画像をアップロードする必要がある場合は、「バッチオペレーションの実行」をご参照ください。

    重要

    Image Search のバッチオペレーション機能を使用するには、Image Search インスタンスと OSS バケットが同じリージョンにあることを確認してください。

Ossimport

ossimport は、データを Object Storage Service (OSS) バケットに移行するための OSS ツールです。 ローカルサーバーまたは ECS インスタンスにデプロイして、オンプレミスストレージや他のクラウドサービスから OSS にデータを移行できます。

ossimport を使用して画像をアップロードすると、次の利点があります。

  • 検索エンジン内の画像インデックスを最新の状態に保ちます。

  • 単一の OSS バケットで、開発プロジェクトや本番プロジェクトなど、複数の環境に対応できます。

  • ビジネスニーズに基づき、さまざまなソースからの画像をより適切に整理、管理できます。

  • 開発プロジェクトやユーザー受け入れテスト (UAT) プロジェクトなど、複雑な環境でのプロジェクト管理を簡素化します。

  • 画像を一度アップロードするだけで複数のアプリケーションで利用できるため、ネットワーク帯域幅の使用を最適化します。

  • 画像管理ワークフローを標準化し、拡張できます。

制限事項

  • 画像サイズは 4 MB までです。

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

手順

手順1:ossimport のダウンロード

ossimport は、スタンドアロンデプロイメントモードと分散デプロイメントモードをサポートしています。

  • スタンドアロンデプロイメントモード:移行するデータが 30 TB 未満の場合に推奨されます。 ソースデータと OSS にアクセスできる任意のマシンに ossimport をデプロイできます。 ossimport をクリックしてダウンロードしてください。

  • 分散デプロイメントモード:移行するデータが 30 TB を超える場合に推奨されます。 ソースデータと OSS にアクセスできる複数のマシンに ossimport をデプロイできます。 ossimport をクリックしてダウンロードしてください。

説明

大量のデータを移行する時間を短縮するには、OSS バケットと同じリージョンの ECS インスタンスに ossimport をデプロイします。 その後、Express Connect を使用してソースデータサーバーを Virtual Private Cloud (VPC) に接続できます。 複数の ECS インスタンスから内部ネットワーク経由で OSS にデータを移行すると、効率が大幅に向上します。

手順2:OSS の有効化

詳細については、「OSS の有効化」をご参照ください。

手順3:バケットの作成

詳細については、「コンソールでのバケットの作成」をご参照ください。

説明

OSS バケットが Image Search インスタンスと同じリージョンにあることを確認してください。

手順4: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 パラメーターは無視されます。

手順5:Image Search への OSS アクセス権の付与

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

手順6:画像のアップロード

  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。

結果の確認

タスクが完了したら、そのステータスを確認できます。

  • [バッチオペレーション] タブのタスクリストに、各タスクのステータスが表示されます。 タスクが成功した場合、メッセージは「Success」と表示されます。 一部の画像の処理に失敗した場合、メッセージには部分的な失敗であることが示されます。[結果のダウンロード] をクリックして詳細を確認してください。 失敗したタスクについては、[増分履歴の表示] をクリックして詳細を確認します。 タスクを再実行するには、[操作] 列の [再送信] をクリックします。 タスクの失敗に関する詳細については、増分タスクの送信が失敗する原因は何ですか。をご参照ください。

  • 画像をアップロードした後、検索機能をテストしてください。 インスタンスの [画像で検索] タブに移動します。 左側のペインで、検索タイプを [SearchByPic] に設定し、検索する画像をアップロードし、[オブジェクト検出] を有効にして [自動] を選択し、[結果数] と [開始位置] を設定してから、[OK] をクリックします。 右側のペインに、RAW JSON レスポンスが表示されます。 返された auctions 配列の各レコードには、score (類似度スコア)、picName (画像名)、productId (商品 ID) などのフィールドが含まれます。 score が高いほど、検索画像との類似度が高いことを示します。