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

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

このクイックスタートでは、商品、商品のグループを含む商品セット、商品に関連する参照画像、という 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. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Vision API:

   gcloud services enable vision.googleapis.com

7. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/storage.objectViewer

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

   • Replace PROJECT_ID with your project ID.

   • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:[e-mail].

   • Replace ROLE with each individual role.
8. Install the Google Cloud CLI.

9. To initialize the gcloud CLI, run the following command:

   gcloud init

10. Create or select a Google Cloud project.

    Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

11. Make sure that billing is enabled for your Google Cloud project.

12. Enable the Vision API:

    gcloud services enable vision.googleapis.com

13. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/storage.objectViewer

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

    • Replace PROJECT_ID with your project ID.

    • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:[e-mail].

    • Replace ROLE with each individual 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",

注: このサンプルの CSV では、省略可能な product-display 列と bounding-poly 列が含まれていません。CSV 要件の詳細については、一括インポート CSV のフォーマットの方法のトピックをご覧ください。

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

次の 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 バケットに保存されている画像を使用します。

注: base64 エンコードのローカル画像を使用して検索することもできます。ローカル画像を使用するサンプルコードについては、商品の検索をご覧ください。

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 リクエストが完成しました。

クリーンアップ

1. Optional: Revoke credentials from the gcloud CLI.

   gcloud auth revoke

2. 注意: プロジェクトを削除すると、次のような影響があります。

   • プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
   • カスタム プロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタム プロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。

   複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにすることができます。

   Delete a Google Cloud project:

   gcloud projects delete PROJECT_ID

次のステップ

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