OSS からの画像の一括インポートと削除 - Image Search

Image Search では、バッチ操作を通じて画像をまとめてインポートおよび削除できます。Object Storage Service (OSS) に保存されたマニフェストファイル (increment.meta) で操作を定義すると、Image Search はそれらを単一のタスクとして処理します。

事前準備

前提条件	説明
OSS の有効化	まだ有効化していない場合は、OSS を有効化し、バケットを作成します。OSS は別途課金されます。詳細については、「課金概要」をご参照ください。
同一リージョン要件	OSS バケットと Image Search インスタンスは、同じリージョンにある必要があります。
画像のアップロード	OSS バケットに画像をアップロードします。詳細については、「オブジェクトのアップロード」をご参照ください。
画像要件	最大サイズ：4 MB。サポートされているフォーマット：PNG、JPG、JPEG、BMP、GIF、WEBP、TIFF、PPM。解像度：100 x 100 から 4096 x 4096 ピクセル (商品画像検索および一般的な画像検索の場合)。画像に回転情報を含めることはできません。伝送レイテンシは 5 秒未満である必要があります。

ステップ 1：increment.meta ファイルの作成

OSS バケットに increment.meta という名前のファイルを作成します。このマニフェストファイルは、インポートまたは削除する画像を Image Search に指示します。各行には、単一の操作を記述する 1 つの JSON オブジェクトが含まれます。

ファイルルール

ルール	詳細
場所	`increment.meta` ファイルとそれが参照する画像は、同じバケット内にある必要があります。
ファイル名	正確に `increment.meta` である必要があります。名前を変更しないでください。
フォーマット	1 行につき 1 つの JSON オブジェクト。1 行に複数のエントリがあると、操作は失敗します。
画像名	ファイル拡張子を含める必要があります (例：`girl_cloth10.jpg`。 `girl_cloth10` ではありません)。
サブディレクトリ	先頭にスラッシュを付けずに相対パスを使用します (例：`girlCloth/girl_cloth8.jpg`)。

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

パラメーターリファレンス

必須パラメーター

パラメーター	タイプ	説明
OperationType	文字列	操作タイプです。`ADD`：Image Search に画像をインポートします。`DELETE`：Image Search から画像を削除します。
ProductId	文字列	画像の一意の ID です。ID の長さは最大 256 文字です。
PicName	文字列	OSS バケットに保存されている画像の名前です。名前の長さは最大 256 文字です。ファイル拡張子を含め、サブディレクトリ内の画像には相対パスを使用してください。
CustomContent	文字列	検索結果で返されるユーザー定義コンテンツです。値の長さは最大 4,096 文字です。このフィールドを使用して、画像 URL やその他のビジネス関連情報などのメタデータを保存できます。

オプションパラメーター

パラメーター	型	デフォルト	説明
CategoryId	Integer	自動予測	画像のカテゴリです。詳細については、「カテゴリリファレンス」をご参照ください。商品画像検索の場合、指定されたカテゴリが優先され、カテゴリリファレンスのトピックで説明されている有効範囲内である必要があります。カテゴリを指定しない場合、システムがカテゴリを予測し、その結果を応答で返します。一般的な画像検索の場合、この値は入力値に関わらず `88888888` に設定されます。
IntAttr	Integer	-	条件による絞り込み検索クエリで画像をフィルタリングするための整数属性です。詳細については、「」をご参照ください。
StrAttr	String	-	検索クエリで画像をフィルタリングするための文字列属性です。値の長さは最大 128 文字です。特殊文字 (`\`、`¥`、`$`、`&`、`%`条件によるフィルタリングなど) はサポートされていません。詳細については、「」をご参照ください。
Crop	ブール値	`true`	画像内の主題を識別し、識別された主題に基づいて検索するかどうかを指定します。画像全体に基づいて検索する場合は、値を `false` に設定します。
Region	String	-	画像の主題領域です。`x1,x2,y1,y2` の形式で指定します。x1 と y1 は左上隅の座標を、x2 と y2 は右下隅の座標を表します。このパラメーターを指定した場合、`Crop` パラメーターより優先されます。説明このパラメーターを設定した場合、`Crop` パラメーターは無視されます。

重要

ファイルの各行には、1 つの画像名のみを含めることができます。1 つのプロダクト ID が複数の画像名に対応する場合は、画像ごとに別の行を追加してください。
既存の画像と同じ ProductId と PicName を持つ画像をインポートすると、新しい画像が既存の画像を上書きします。

ステップ 2：Image Search への OSS アクセス権限の付与

初めてバッチ操作を使用する際には、ご利用の Image Search アカウントに OSS へのアクセスを許可する必要があります。この権限付与を既に完了している場合は、このステップをスキップしてください。

Image Search コンソールにログインします。
サービスタイプを選択し、管理したいインスタンスの名前をクリックします。
[バッチ操作] タブをクリックします。
[バッチタスクの作成] をクリックします。表示されるダイアログボックスで、[権限付与の確認] をクリックします。
[クラウドリソースアクセス権限付与] ページで、[権限付与ポリシーの確認] をクリックします。

ステップ 3：バッチタスクの作成

Image Search コンソールにログインします。
サービスタイプを選択し、管理したいインスタンスの名前をクリックします。
[バッチ操作] タブをクリックします。
[バッチタスクの作成] をクリックします。
次のパラメーターを設定します：

パラメーター	説明
リージョン	ご利用の Image Search インスタンスがデプロイされているリージョンです。
バケット名	OSS バケットの名前です。バケットがご利用の Image Search インスタンスと同じリージョンにあることを確認してください。
パス	画像と `increment.meta` ファイルが保存されているパスです。
META ファイル	`increment.meta` マニフェストファイルです。[更新] アイコンをクリックして、ファイルが存在することを確認します。
操作完了後のコールバック	(オプション) HTTP または HTTPS で始まるコールバック URL です。タスクが完了すると、Image Search はこの URL にタスク結果を送信します。

コールバック応答フォーマット

コールバック URL が設定されている場合、Image Search はタスク完了時に次の JSON ペイロードを送信します：

{
  "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	タスクが完了した時刻 (秒単位まで正確)。
instanceName	Image Search インスタンスの名前です。
instanceId	Image Search インスタンスの ID です。
status	タスクの結果です。`NORMAL` は成功を示し、`FAIL` は失敗を示します。
taskId	バッチタスクの ID です。
message	結果の説明です。`success` はタスクが完了したことを示します。
processResultUrl	処理に失敗した画像がある場合に、詳細な失敗情報をダウンロードするための URL です。

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

[処理中] 状態のタスクはキャンセルできます：

[バッチ操作] タブでタスクを見つけ、[キャンセル] をクリックします。
確認ダイアログボックスで、[OK] をクリックします。

キャンセル後、完了した部分は保持され、タスクのステータスは [停止] に変わります。[結果のダウンロード] をクリックして実行詳細を表示します。

バッチタスク結果の表示

インスタンス詳細ページの [バッチ操作] タブで、インスタンス用に作成されたすべてのバッチタスクを表示できます。進行中のタスクには進捗インジケーターが表示されます。バッチタスクが [インポート済み] 状態の場合、[エラーメッセージ] 列でタスク結果の説明を表示できます。

[バケット名] または [パス] でタスクをフィルターします。
「[エラーメッセージ]」列に「[処理できないイメージがいくつかあり、分離されています。]」と表示された場合、増分タスク中に一部のイメージの処理に失敗しました。「[レポートのダウンロード]」をクリックして、失敗の詳細を確認します。