Product Search の機能はメンテナンスモードです。スケーラビリティを高め、Product Search と同じ機能を利用するには、Vision Warehouse を使用してください。

このページは Cloud Translation API によって翻訳されました。

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

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

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

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

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

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

始める前に

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

プロジェクトを設定する

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.

Install the Google Cloud CLI.

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Verify that billing is enabled for your Google Cloud project.

Enable the Vision API:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable vision.googleapis.com

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 the following:

PROJECT_ID: Your project ID.
USER_IDENTIFIER: The identifier for your user account. For example, myemail@example.com.
ROLE: The IAM role that you grant to your user account.

Install the Google Cloud CLI.

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Verify that billing is enabled for your Google Cloud project.

Enable the Vision API:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable vision.googleapis.com

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 the following:

PROJECT_ID: Your project ID.
USER_IDENTIFIER: The identifier for your user account. For example, myemail@example.com.
ROLE: The IAM role that you grant to your user account.

環境変数を設定する

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

PROJECT_ID は、実際の Google Cloud プロジェクトの ID です。
LOCATION_ID は、チュートリアルを実行する Google Cloud ロケーションです（例: us-east1）。有効なロケーション ID は 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 リクエストが完成しました。

クリーンアップ

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

次のステップ

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

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

始める前に

プロジェクトを設定する

環境変数を設定する

データセットの使用

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

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

インデックス登録

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

商品を一覧表示する

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

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

クリーンアップ

次のステップ

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