商品セットを作成して商品を検索する

このクイックスタートでは、商品、商品のグループを含む商品セット、商品に関連する参照画像、という 3 種類の Vision API Product Search リソースについて、その作成方法と使い方を説明します。

このクイックスタートでは、バッチインポートを利用し、商品セット、商品アイテム、参照画像を 1 つのステップで作成します。

商品セットをインデックス登録すると、Vision API Product Search を使用してその商品セットをクエリできます。

このクイックスタートでは、以下の処理を順に行います。

CSV と一括インポートを使用して、商品セット、商品、参照画像を作成します。
Cloud Storage バケットに格納された画像を使用して、Vision API Product Search にリクエストを送信します。

始める前に

まだプロジェクトを設定していない場合、次に示すとおり設定します。

プロジェクトを設定する

Google Cloud アカウントにログインします。Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

Google Cloud CLI をインストールします。

gcloud CLI を初期化するには:

gcloud init

Google Cloud プロジェクトを作成または選択します。

Google Cloud プロジェクトを作成します。
```
gcloud projects create PROJECT_ID
```
PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。
作成した Google Cloud プロジェクトを選択します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、実際の Google Cloud プロジェクト名に置き換えます。

Google Cloud プロジェクトで課金が有効になっていることを確認します。

Vision API を有効にします。

gcloud services enable vision.googleapis.com

Google アカウントにロールを付与します。次の IAM ロールごとに次のコマンドを 1 回実行します。 roles/storage.objectViewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE

PROJECT_ID は、実際のプロジェクト ID に置き換えます。
EMAIL_ADDRESS は実際のメールアドレスに置き換えます。
ROLE は、個々のロールに置き換えます。

Google Cloud CLI をインストールします。

gcloud CLI を初期化するには:

gcloud init

Google Cloud プロジェクトを作成または選択します。

Google Cloud プロジェクトを作成します。
```
gcloud projects create PROJECT_ID
```
PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。
作成した Google Cloud プロジェクトを選択します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、実際の Google Cloud プロジェクト名に置き換えます。

Google Cloud プロジェクトで課金が有効になっていることを確認します。

Vision API を有効にします。

gcloud services enable vision.googleapis.com

Google アカウントにロールを付与します。次の IAM ロールごとに次のコマンドを 1 回実行します。 roles/storage.objectViewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE

PROJECT_ID は、実際のプロジェクト ID に置き換えます。
EMAIL_ADDRESS は実際のメールアドレスに置き換えます。
ROLE は、個々のロールに置き換えます。

環境変数を設定する

このクイックスタートで使用する curl のサンプルを簡単に実行できるように、次の環境変数を設定します。

PROJECT_ID は、Google Cloud プロジェクトの ID です。
LOCATION_ID は、チュートリアルを実行する Google Cloud のロケーションです（例: us-east1）。有効なロケーション識別子は us-west1、us-east1、europe-west1、asia-east1 です。

データセットの使用

このクイックスタートでは、商品カテゴリ apparel-v2 のエントリを 100 個まで含むデータセットを使用します。この一般公開のデータセットは、次の場所にある一般公開の Cloud Storage バケットに保存されます。

gs://cloud-samples-data/vision/product_search/product_catalog.csv

CSV 形式は次のとおりです。

gs://cloud-ai-vision-data/product-search-tutorial/images/filename1.jpg,image0,product_set0,product_id0,apparel-v2,,"style=women,category=shoe",
gs://cloud-ai-vision-data/product-search-tutorial/images/filename2.jpg,image1,product_set0,product_id1,apparel-v2,,"style=men,category=shoe",
gs://cloud-ai-vision-data/product-search-tutorial/images/filename3.jpg,image2,product_set0,product_id2,apparel-v2,,"style=women,category=dress",

一括インポートを使用して商品セット、商品、参照画像を作成する

次の curl コマンドを使用して、商品と参照画像を含む新しい商品セットを作成します。このセットの名前は product_set0 で、値がインポート用の CSV に宣言されています。

まず、import_request.json という名前のリクエストファイルを JSON 形式で作成し、このファイルを現在の作業ディレクトリに保存します。

import_request.json

{
  "inputConfig": {
    "gcsSource": {
      "csvFileUri": "gs://cloud-samples-data/vision/product_search/product_catalog.csv"
    }
  }
}

リクエスト JSON ファイルを作成したら、リクエストを送信します。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @import_request.json \
    https://vision.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/productSets:import

成功したときのレスポンスには、長時間実行オペレーションオブジェクトが含まれています。

{
  "name": "locations/LOCATION_ID/operations/0a0aec86192599fa"
}

このレスポンスには、相対的なオペレーション ID（例: 0a0aec86192599fa）が含まれています。この ID は、オペレーションのステータスを取得する際に使用します。

インポートオペレーションのステータスを取得する

インポートオペレーションから返された operation-id を使用して、一括インポートオペレーションのステータスを確認できます。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/locations/LOCATION_ID/operations/OPERATION_ID

正常なレスポンスは次のようになります。

{
  "name": "locations/LOCATION_ID/operations/0a0aec86192599fb",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.BatchOperationMetadata",
    "state": "SUCCESSFUL",
    "submitTime": "2018-11-30T03:11:04.808114024Z",
    "endTime": "2018-11-30T03:11:38.624444324Z"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.ImportProductSetsResponse",
    "referenceImages": [
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id0/referenceImages/image0",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/46a0cbcf70ba11e89399d20059124800.jpg"
      },
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id1/referenceImages/image1",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/46a1aea370ba11e888d4d20059124800.jpg"
      },
      ...
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id93/referenceImages/image93",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/4697319970ba11e8a7bfd20059124800.jpg"
      },
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id94/referenceImages/image94",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/4698596370ba11e8bf6ad20059124800.jpg"
      }
    ],
    "statuses": [
      {},
      {},
      [...]
      {},
      {}
    ]
  }
}

インデックス登録

商品の Product Search インデックスは、約 30 分ごとに更新されます。画像が追加または削除されると、その変更はインデックスが次に更新されるまで Product Search のレスポンスに反映されません。

インデックス登録が正常に完了したことを確認するには、商品セットの indexTime フィールドを確認します。

商品セットの一覧表示とインデックス登録の確認

すべての商品セットを一覧表示して indexTime フィールドを使用すると、インデックス登録が正常に完了したことを確認できます。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/productSets

正常なレスポンスには、すべての商品セット（product_set0 などの商品セット ID を含む）とインデックス作成の完了を表す indexTime フィールドが含まれます。

{
  "productSets": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/productSets/product_set0",
      "displayName": " ",
      "indexTime": "2019-11-30T18:33:40.093508652Z",
      "indexError": {}
    }
  ]
}

商品を一覧表示する

商品セットのリストで返された PRODUCT_SET_ID を使用すると、商品セット内のすべての商品を一覧を取得できます。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/productSets/PRODUCT_SET_ID/products?pageSize=15

正常なレスポンスには、商品の詳細が一覧表示されます。

このリクエストでは、オプションのクエリパラメータ pageSize を使用して、結果のリストの商品数を 15 に設定します。また、レスポンスの nextPageToken は一覧表示する商品がまだあることを示します。一覧表示されたトークンを使用すると、さらに結果を取得できます。pageToken の使用について詳しくは、リソースの取得と一覧表示をご覧ください。

{
  "products": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id0",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "women"
        },
        {
          "key": "category",
          "value": "shoe"
        }
      ]
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id1",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "men"
        },
        {
          "key": "category",
          "value": "shoe"
        }
      ]
    },
    ...
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id21",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "women"
        },
        {
          "key": "category",
          "value": "dress"
        }
      ]
    }
  ],
  "nextPageToken": "1LqhSgZfM_uWKOxvog"
}

Vision API Product Search で一致する商品を検索する

インデックスの作成が完了すると、サンプル画像に一致する商品を検索できます。このクイックスタートでは、次のような Google Cloud Storage バケットに保存されている画像を使用します。

Cloud Storage バケット内の洋服の画像。 — `gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg`

リモート画像を使用して検索する

次のリクエストを使用して、一般公開の Cloud Storage バケットに保存されている画像を使用します。

まず、search_request.json という名前のリクエストファイルを JSON 形式で作成し、このファイルを現在の作業ディレクトリに保存します。プロジェクトの情報に合わせて、リクエスト JSON の次の値を変更します。

PROJECT_ID
LOCATION_ID
PRODUCT_SET_ID

search_request.json

{
  "requests": [
    {
      "image": {
        "source": {
          "gcsImageUri": "gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg"
        }
      },
      "features": [
        {
          "type": "PRODUCT_SEARCH"
        }
      ],
      "imageContext": {
        "productSearchParams": {
          "productSet": "projects/PROJECT_ID/locations/LOCATION_ID/productSets/PRODUCT_SET_ID",
          "productCategories": [
            "apparel-v2"
          ],
          "filter": "style=womens OR style=women"
        }
      }
    }
  ]
}

リクエスト JSON ファイルを作成したら、リクエストを送信します。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @search_request.json \
    https://vision.googleapis.com/v1/images:annotate

リクエストが成功すると、一致する商品のリストが商品 ID で表示されます。1 つの画像に複数の商品がある場合、結果は境界ボックスで識別された商品ごとにさらに細分化されます。

1 つの画像で 1 つの商品が検出された場合と複数の商品が検出された場合の例については、検索のレスポンスとマルチ検出についてをご覧ください。

score フィールドも返されます。このフィールドは、商品が指定された画像と一致するとサービスが判断した際の信頼度を 0（信頼できない）～1（完全に信頼できる）のスケールで示します。

indexTime フィールドは、検索されているインデックスのバージョンを示します。この時刻以降に行われた画像の変更は、結果に反映されません。

レスポンス

{
  "responses": [
    {
      "productSearchResults": {
        "indexTime": "2020-01-07T18:33:45.300851144Z",
        "results": [
          {
            "product": {
              "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16",
              "displayName": " ",
              "productCategory": "apparel-v2",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 1,
            "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16/referenceImages/image16"
          },
          {
            "product": {
              "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id29",
              "displayName": " ",
              "productCategory": "apparel-v2",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 0.27578148,
            "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id29/referenceImages/image29"
          },
          ...
          {
            "product": {
              "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id22",
              "displayName": " ",
              "productCategory": "apparel-v2",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                },
                {
                  "key": "kids",
                  "value": "true"
                }
              ]
            },
            "score": 0.20356013,
            "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id22/referenceImages/image22"
          }
        ],
        "productGroupedResults": [
          {
            "boundingPoly": {
              "normalizedVertices": [
                {
                  "x": 0.25542393,
                  "y": 0.15517132
                },
                {
                  "x": 0.8196448,
                  "y": 0.15517132
                },
                {
                  "x": 0.8196448,
                  "y": 0.92001766
                },
                {
                  "x": 0.25542393,
                  "y": 0.92001766
                }
              ]
            },
            "results": [
              {
                "product": {
                  "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16",
                  "displayName": " ",
                  "productCategory": "apparel-v2",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 1,
                "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16/referenceImages/image16"
              },
              {
                "product": {
                  "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id57",
                  "displayName": " ",
                  "productCategory": "apparel-v2",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 0.27369013,
                "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id57/referenceImages/image57"
              },
              ...
              {
                "product": {
                  "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id18",
                  "displayName": " ",
                  "productCategory": "apparel-v2",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 0.21221256,
                "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id18/referenceImages/image18"
              }
            ],
            "objectAnnotations": [
              {
                "mid": "/m/01d40f",
                "name": "Dress",
                "score": 0.968603
              }
            ]
          }
        ]
      }
    }
  ]
}

これで、Vision API Product Search サービスに対する最初の images.annotate リクエストが完成しました。

クリーンアップ

（省略可）gcloud CLI から認証情報を取り消します。
```
gcloud auth revoke
```

注意: プロジェクトを削除すると、次のような影響があります。
- プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
- カスタムプロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタムプロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。
複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにすることができます。
Google Cloud プロジェクトを削除します。
```
gcloud projects delete PROJECT_ID
```

次のステップ

Vision API Product Search クライアントライブラリを使用して、選択した言語で Vision API Product Search を利用する。
入門ガイドを参照する。
チュートリアルを参照する。

商品セットを作成して商品を検索する

始める前に

プロジェクトを設定する

環境変数を設定する

データセットの使用

一括インポートを使用して商品セット、商品、参照画像を作成する

インポート オペレーションのステータスを取得する

インデックス登録

商品セットの一覧表示とインデックス登録の確認

商品を一覧表示する

Vision API Product Search で一致する商品を検索する

リモート画像を使用して検索する

クリーンアップ

次のステップ

インポートオペレーションのステータスを取得する