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

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

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

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

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

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

始める前に

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

プロジェクトを設定する

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. Google Cloud CLI をインストールします。

  3. gcloud CLI を初期化するには:

    gcloud init

  4. 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 プロジェクト名に置き換えます。

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

  6. Vision API を有効にします。 

    gcloud services enable vision.googleapis.com

  7. 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 は、個々のロールに置き換えます。
    8.
  8. Google Cloud CLI をインストールします。

  9. gcloud CLI を初期化するには:

    gcloud init

  10. 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 プロジェクト名に置き換えます。

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

  12. Vision API を有効にします。 

    gcloud services enable vision.googleapis.com

  13. 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 は、個々のロールに置き換えます。
    14.

環境変数を設定する

このクイックスタートで使用する 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 バケットに保存されます。

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

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

クリーンアップ

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

    gcloud auth revoke

  2. Delete a Google Cloud project:

    gcloud projects delete PROJECT_ID

次のステップ